Custom light rules and developer adapters

Define an item’s portable light

Use a rule when you want to change which stacks emit, their brightness or color, or the conditions under which they emit. This is an operator and developer reference for the source-based 1.3.1 snapshot. Examples below describe files you can create; this wiki has not installed them or changed the mod.

A rule changes visual item lighting. It does not create the item, grant a stack, add a recipe or modify real world-light behavior. Server-shared policy replaces the local item table, so choose the appropriate side before editing.

Choose the file scope

Scope	Path	Reload
Loose local file	`config/dynamicitemlights/items/<namespace>/<name>.json`	F3 + T
Client resource-pack resource	`assets/<namespace>/dynamicitemlights/items/<name>.json`	F3 + T
Server data-pack resource	`data/<namespace>/dynamicitemlights/items/<name>.json`	`/reload` or `/dilpolicy reload`

A rule ID comes from its namespace and relative name. Reusing a bundled ID replaces that rule; bundled rules use the namespace dynamicitemlights. A loose file directly in the items directory uses namespace local. These rule IDs differ from the item targeted inside the file.

While a shared server snapshot is active, clients use that compiled table rather than merging in personal rules. An item omitted from the snapshot has no item light. Personal rendering preferences still apply. See server configuration for reconnect behavior and command permissions.

Rule fields

Field	Required or default	Accepted value / effect
`schema_version`	Required	Integer `1`
`target_type`	Required	`item` or `tag`
`target`	Required	Namespaced item/tag ID, such as `minecraft:torch`
`brightness`	Required	Integer 0–15; zero explicitly disables emission
`color`	White if omitted	`#RRGGBB`
`priority`	`0`	Integer −1000 to 1000, within a target category
`held`	`true`	False makes the winning rule emit zero when held
`dropped`	`true`	False makes the winning rule emit zero when dropped
`water`	`always`	`always`, `dry_only` or `water_only`
`predicates`	Empty list	At most 16 conditions; every condition must match

Resolution order

Try exact-item rules before tag rules.
Within each category, try higher priority first, then alphabetical rule ID.
Use the first matching rule. A zero-brightness result or a false held/dropped flag still decides; it does not fall through to another rule.
If no explicit rule matches, use the automatic block-default fallback.

This rule selection is separate from the per-entity competition among hands, Luminous and headlamp. See one entity, one winning source.

Disable the bundled Ender Chest light

Save this as config/dynamicitemlights/items/dynamicitemlights/ender_chest.json, then reload client resources with F3 + T when using local rules. It replaces the bundled rule ID while targeting the existing vanilla item.

{
  "schema_version": 1,
  "target_type": "item",
  "target": "minecraft:ender_chest",
  "brightness": 0
}

Under server-shared policy, make the corresponding server data-pack change instead and use the server reload path. Confirm active scope with /dilclient status.

Match an exact component value

Use a separate custom rule ID for this example, such as a loose file under your own namespace. It applies only to sticks whose synchronized custom-model-data component decodes to the exact value 7.

{
  "schema_version": 1,
  "target_type": "item",
  "target": "minecraft:stick",
  "brightness": 11,
  "color": "#7FFFE0",
  "predicates": [
    { "type": "component", "component": "minecraft:custom_model_data", "equals": 7 }
  ]
}

This does not grant a stick or set its component. All conditions in a rule must match. Missing or undecodable client-side conditions can warn and never match; malformed definitions can reject loading.

Fix invalid reloads

Unknown fields, malformed IDs or colors, out-of-range values and unsupported components/adapters are errors. The limits are 32 rules per target, 16 predicates per rule, and 16,384 total rules. Optional absent item targets produce warnings rather than adding content.

Reload is atomic: invalid input retains the previous valid set. After a failed initial load, bundled defaults are used. Correct the invalid file, reload the right side, and inspect status/errors. Do not assume a changed file became active just because the game remained open.

Automatic block fallback

For an unruled block item, the catalog evaluates default-state block emission once per rule/registry reload. Non-block items default to zero. Fallback color is the block map color mixed halfway toward white, or white if unknown.

World-sensitive emission overrides, or blocks whose evaluation throws, are marked as needing a rule or adapter and resolve to zero automatically. A bright-looking texture is insufficient. Explicit bundled rules give carried furnaces, candles and redstone lamps their intended values even when the ordinary default block state would not emit.

A held redstone lamp’s level 15 and a helmet-mounted redstone lamp’s default level 14 are different systems. Item rules do not turn that helmet lamp into level 15.

Developer adapters

ItemLightAdapters.register accepts a namespaced adapter ID, component dependencies and a predicate over an item stack. Keep the predicate quick, side-effect free and based only on synchronized data. An external mod must actually register the adapter before a rule can use it.

Example predicate entry inside a rule:

"predicates": [
  { "type": "adapter", "adapter": "mymod:charged" }
]

This fragment demonstrates an extension point. It is not a bundled charged-wand feature or evidence that a specific third-party item integrates.

Headlamp recipe inputs use minecraft:head_armor, c:glass_blocks and c:glass_panes. Beacon-color glass behavior determines recognized modded glass colors. These tag/API paths establish intended integration mechanisms; individual items, glass combinations and custom head-render alignment remain untested.