Granting authority over other mods' entities

A mod can act on the entities it created, and on instances of archetypes it ships. It cannot touch another mod’s entities. That default is what stops a decoration mod from moving your props around, and it needs no configuration from you.

Some mods legitimately need more: a round janitor that clears props at the end of a match, or a moderation tool that removes one griefer’s prop. Those act on entities whose creators have never heard of them, so no two mods can arrange it between themselves — you decide it, in config/server.toml.

If you run none of those, you never touch this page.

A grant

[[grants.rule]]
to    = "acme:janitor"
verbs = ["read", "remove"]
over  = "owner:*"

That mod may now look at and remove any entity any mod created, for this session.

Three fields, and all three are required:

Field	Means
`to`	The mod this is granted to, by its full `author:mod` id.
`verbs`	What it may do: any of `read`, `write`, `remove`.
`over`	Whose entities: `owner:*` for every mod’s, or `owner:<author:mod>` for one mod’s.

The granularity is the mod, because authority is exercised by running code, and anything coarser would hand a whole suite whatever its author needed for one member of it.

The three verbs

Verb	Lets the mod
`read`	Look at another mod’s entities — read their components, resolve their parts.
`write`	Change them: move them, recolour them.
`remove`	Delete them.

They are separate because the mods that need them need different ones. A janitor needs remove and little else. Grant the narrowest set that makes the mod work.

Narrowing it

owner:* covers every mod’s entities. To confine a grant to one mod’s, name that mod after the owner: prefix:

[[grants.rule]]
to    = "acme:janitor"
verbs = ["remove"]
over  = "owner:bree:props"

There is no exclusion list — no way to say “everything except”. One row’s effect would then depend on rows elsewhere in the file, and any mod installed later would fall outside everybody’s exclusions and be quietly reachable. Listing the owners you mean is more typing and says what it does.

What a grant can never do

Reach a player’s body. No grant moves, reads or deletes one, whatever it says. The widest row you can write does not touch players, and there is no scope word for bodies to write at all. The one thing a body takes — decoration rows such as a label — is not a grant: the mod declares the row in its own manifest, and enabling the mod is the permission.
Take a player over. Possession belongs to the session’s gamemode alone; there is no setting for it.
Rename another mod’s entities. Naming is not in the grant vocabulary, so no row can produce it.

The gamemode already has one

The mod holding the gamemode role may read and remove any mod’s entities without a row, because clearing the field at the end of a round is the session’s own business, and holding the role is already your decision — [session] gamemode, or being the only candidate. It is never granted write, so it can clear another mod’s props but not silently rewrite them.

Swapping which mod is the gamemode moves that authority with it, so there is nothing to keep in step.

Checking it

The server states the policy it resolved at session start, one line per grant with the row it came from. In logs/host.log:

grant: 'acme:janitor' may read,remove over owner:* (from row 1)
grant: 'ironlark:freeroam' may read,remove over owner:* (from the gamemode role)
grant: no grant moves, reads, names or destroys a player's body — a body takes only declared decoration rows, and possession is the gamemode's alone

With no [grants] section at all:

grants: none; no mod may touch another mod's entities

Every refused call is logged too, naming who asked, whose entity it was, and what was missing — so a mod that swallows its own errors cannot hide the problem from you.

When it goes wrong

Rows are numbered as you count them, so every message names the row you would edit.

What you see	Cause
`[grants] row 1, over: 'bree:props' is not a scope; write 'owner:*' for every mod's entities, or 'owner:<author:mod>' for one mod's`	The `over` field is malformed — here, a missing `owner:` prefix. The session refuses to start.
`[grants] row 1 grants 'acme:janitor' nothing; give it verbs or delete the row`	`verbs` is empty. The session refuses to start.
`[grants] row 2 names 'acme:janitor', which this session does not run; the row is ignored`	A warning, not a refusal: the row is dropped for this session. Either the mod is not enabled, or the id is wrong — check it against the session’s load-order line.
A mod reports refusals you expected the grant to cover	Compare the verb in the refusal against the row’s `verbs`, and the owner against `over`.

A malformed row stops the session on purpose. Starting with a policy you did not write is worse than not starting: a janitor you believe is running and is not gets noticed a week later, by which time the map is full. A row naming a mod that is not running is only a warning, so disabling one mod never forces an edit to a second section.

Changing it

Grants resolve when a session starts, so edit the file and host again. They do not change mid-session — a mod that lost remove halfway through a sweep would leave the field half cleared.