Policy Files

Policy Files

This page describes the JSON files Greenlight reads from server resource packs.

Terms

• Feature ID: the namespaced ID of a mod feature, such as examplemod:cave_tint.
• Policy file: the JSON file a server ships for one feature.
• Grant: an enabled, trusted policy that the client mod can understand.
• Settings: the feature-specific JSON body. Greenlight stores it, but the owning mod decides what the keys mean.

How Greenlight Trusts a Server Policy

1. The server sends a resource pack using resource-pack, or the equivalent server API. The pack can be required or optional.
2. Minecraft marks downloaded server packs with PackSource.SERVER.
3. Greenlight only trusts selected packs that are server-sourced.
4. Local packs, world packs, and built-in packs do not grant features.
5. When the server pack is removed, rejected, or no longer selected, the grant disappears.

This is a client-side permission signal, not enforcement.

Policy File Location

Each feature gets one JSON file:

assets/<feature_namespace>/client_features/v1/<feature_path>.json

For feature examplemod:cave_tint:

assets/examplemod/client_features/v1/cave_tint.json

A server pack can safely include policies for many optional client mods. If the client does not have the mod that owns a feature, no feature code will use that policy.

Envelope Format

{
  "protocol_version": 1,
  "feature": "examplemod:cave_tint",
  "enabled": true,
  "settings_version": 1,
  "settings": {
    "...": "feature-defined body"
  }
}

Fields:

• protocol_version is required and must be 1. It versions the Greenlight envelope, not the feature's settings.
• feature is required and must match the feature ID from the file path.
• enabled defaults to false. Use true to grant the feature.
• settings_version defaults to 1. This is owned by the feature mod.
• settings defaults to an empty object. The owning mod decodes this body.

Malformed files fail closed. Greenlight logs the problem and treats the feature as denied.

Settings Versioning

protocol_version belongs to Greenlight. settings_version belongs to the feature mod.

A mod registers the settings version it understands:

Greenlight.feature(Identifier.fromNamespaceAndPath("examplemod", "cave_tint"))
        .decoder(1, CaveTintPolicy::fromJson)
        .register();

Use additive changes when possible. New fields should be optional, and missing values should mean the most restrictive behavior.

Bump settings_version only when older clients would misread the new shape.

Multiple Packs and Policy Sources

If several trusted server packs declare the same feature, the topmost trusted declaration wins.

If that topmost declaration is unreadable, Greenlight denies the feature instead of falling back to a lower pack.

The server resource pack is the built-in policy source at priority 0.

Advanced integrations can register additional sources, such as a custom network payload from a server-side mod. For each feature, the highest-priority source that declares a policy wins. A disabled policy counts as a declaration and can revoke a lower-priority grant.

Practical Notes

• Do not put secrets in policy JSON. Resource packs are visible to clients.
• Keep feature IDs stable.
• Document every settings key your feature supports.
• Server owners should not need to read source code to write a policy.