Mod Permissions

Every mod declares the permissions it needs in its ModManifest.json. Permissions are enforced at runtime by the Lua sandbox — undeclared permissions produce a LuaSandboxPermissionException inside the script, not a game crash. When a player installs a mod, the mod browser presents a plain-language summary of each requested permission before the player confirms.

Permission levels

ReadEntityState

What it grants: Read-only access to entity component values via the Entity Lua module — position, health, tag, name, and any component the developer explicitly registers as readable.

What it does not grant: Writing to components, spawning or destroying entities, or accessing private components the developer has not exposed.

Plain-language summary shown to players: “This mod can read the position, health, and name of entities in the current scene.”

---

ModifyLocalState

What it grants: The ability to call Game.EmitAction() for actions that modify local game state — score, UI state, cosmetic effects — without any network effect. Only actions categorised as LocalOnly by the developer are reachable under this permission.

What it does not grant: Access to any action that emits an Echo or modifies server-authoritative state.

Plain-language summary shown to players: “This mod can modify your local game state — scores, UI, visual effects — but has no effect outside your game session.”

---

TriggerGameActions

What it grants: The ability to call Game.EmitAction() for any action registered by the game developer, including actions that may have effects beyond local state. Developers decide which actions are accessible — this permission is a broad grant to the entire registered action surface.

What it does not grant: Direct access to EchoService or any Living World write path.

Plain-language summary shown to players: “This mod can trigger game actions, which may affect gameplay beyond visual effects.”

Note

If you want to limit what TriggerGameActions mods can do, register only LocalOnly actions and use ModifyLocalState instead. TriggerGameActions is appropriate when you intentionally want mods to have gameplay-level access.

---

ReadWorldState

What it grants: Read-only access to Living World state via the World Lua module — weather, species populations, resource levels, faction stances, world time.

What it does not grant: Any write path to the simulation. Reading world state has no side effects.

Plain-language summary shown to players: “This mod can read the current state of the living world — weather, wildlife populations, and faction information.”

---

ModifyWorldInfluence

What it grants: The ability to trigger game actions or code paths that may result in Echo events being submitted to the Living World simulation. Because Echoes have persistent, shared effects on the world, this permission requires explicit player acknowledgement.

What it does not grant: Unlimited Echo submission. All Echoes are still rate-limited and plausibility-validated by the Root. This permission grants the player permission to allow the mod to participate in that system — the security enforcement remains server-side.

Plain-language summary shown to players: This mod can influence the living world shared by all players. Its actions may affect wildlife, resources, or factions in zones you visit.

Danger

ModifyWorldInfluence mods can affect the shared Living World for all players in a zone. Players are warned before installing, with the above warning displayed prominently. If your game does not expose a ModifyWorldInfluence-compatible action handler, mods cannot exercise this path even if they declare the permission.

---

What players see

The mod browser renders each permission as a plain-language row:

Permissions requested by this mod:
  • Read entity position, health, and name (ReadEntityState)
  • Read living world state (ReadWorldState)
  ⚠ Can influence the shared living world (ModifyWorldInfluence)

The ModifyWorldInfluence permission is always rendered with a warning icon and a distinct colour. Players must scroll past the permission list and click a separate confirm button after seeing a ModifyWorldInfluence declaration.

Designing your permission surface

As a game developer, you control what each permission level can actually do in your game. Some recommendations:

Keep TriggerGameActions handlers local by default. If you register game actions, categorise them as LocalOnly until you have a specific reason to allow broader access. Players and modders see a smaller, less intimidating permission surface.

Do not expose EchoService through action handlers unless you intend to. If a TriggerGameActions handler internally calls EchoService.EmitAsync(), that handler is exercisable by any mod with TriggerGameActions — not just mods with ModifyWorldInfluence. Either require ModifyWorldInfluence on the action handler’s registration, or do not expose Echo-emitting handlers to mods at all.

// Register an action handler with the required permission level
Services.Get<LuaScriptEngine>().RegisterActionHandler(
    new HuntEchoActionHandler(echoService),
    requiredPermission: ModPermission.ModifyWorldInfluence   // <-- enforced at call time
);

Expose only what you designed for. The action registration API is your game’s public modding interface. Treat it like a public API: document it, version it, and do not expose implementation details that mods could abuse.