Skip to content

Authoring Settings

Jump to bottom
EmoTracker Community edited this page Apr 8, 2026 · 1 revision

Authoring a Settings File

settings.json is an optional file at the root of your pack that carries a handful of runtime settings — window resize behavior, default disabled-image filter, pack-wide chest art, and a few others. Unlike manifest.json, it isn't required — omit the file entirely and EmoTracker accepts all the defaults. When it exists, the runtime reads it immediately after loading the manifest, via Tracker.LoadPackageSettings.

This page documents every field the parser reads and when to set each one.

See Authoring a Manifest for the required manifest.json, Packaging Your Pack for where settings.json goes in the pack directory layout, and Image Filters for the syntax used by disabled_image_filter.

Where it lives

settings.json must be at the root of the pack, next to manifest.json:

my_pack/
├── manifest.json
├── settings.json   ← THIS FILE (optional)
├── scripts/
├── items/
├── locations/
└── layouts/

EmoTracker reads settings.json on every pack load — including after you press F5 to refresh while authoring — so you can iterate on its fields without restarting.

If the file is missing, EmoTracker logs a warning and falls back to reading the same fields from a legacy tracker_layout.json at the pack root. New packs should use settings.json; tracker_layout.json only exists for backwards compatibility.

A minimal settings file

The smallest useful settings.json sets just the fields you need:

{
    "allow_resize": false,
    "disabled_image_filter": "saturation|0.2|BT709, brightness|0.6"
}

Every field is optional — you only include what you want to override.

JSON schema

The canonical JSON schema is published at EmoTracker-Service/sdk/schema/settings.json. Wire it up in VS Code along with the other pack schemas (see Developer Setup → Configuring JSON schema validation) so you get autocomplete and validation for every field while authoring:

// .vscode/settings.json — add this entry to the json.schemas array
{
    "fileMatch": [ "settings.json" ],
    "url": "https://raw.githubusercontent.com/EmoTracker-Community/EmoTracker-Service/main/sdk/schema/settings.json"
}

Field reference

Parsed in EmoTracker.Data/Tracker.cs:LoadPackageSettings (with chest-image fields delegated to LocationDatabase.ParseLocationVisualProperties).

Window behavior

Field Type Default Description
allow_resize boolean true Whether the user is allowed to resize the main tracker window while this pack is loaded. Set to false to pin the window to whatever size your layout is designed for — useful for packs with pixel-exact layouts or streaming overlays.

Default disabled image filter

Field Type Default Description
disabled_image_filter string "grayscale, dim" The image filter spec used as the pack-wide default for inactive/disabled icons. When an item needs an "off" state and no explicit disabled_img is supplied, EmoTracker derives one by applying this filter to the base icon.

This is the supported authoring path for setting a custom pack-wide disabled look. The resolution chain when an item needs an inactive icon:

  1. If the item's disabled_img_mods field is set, use that filter spec
  2. Otherwise, if the item's disabled_image_filter base field is set, use that
  3. Otherwise, if disabled_image_filter is set in settings.json, use that
  4. Otherwise, fall back to the tracker default: "grayscale, dim"

Don't set Tracker.DisabledImageFilterSpec from Lua. The underlying property is technically settable, but the supported authoring path is this settings.json field — Lua-set values get reset to the tracker default on every reload. See Image Filters → The default disabled filter for more.

Default chest art

Field Type Default Description
chest_opened_img string built-in Pack-relative path to the image used for open (cleared) chest slots in the location-popup chest list. Cascades down to every location and section unless they override it individually.
chest_unopened_img string built-in Pack-relative path to the image used for unopened (unchecked) chest slots. Cascades the same way.

These override the built-in chest art pack-wide. Individual locations and sections can still override them via their own chest_opened_img / chest_unopened_img fields — see Authoring Locations → Visual properties (chest icons).

Chest manipulation override

Field Type Default Description
always_allow_chest_manipulation boolean false Pack-wide default for whether the user can click chests even when the containing section isn't normally reachable. Individual locations and sections can still override this per-section. Useful for packs where chest manipulation should always work regardless of access logic — typically beginner-friendly packs or "manual tracking only" variants.

Advanced: accessibility rule cache

Field Type Default Description
enable_accessibility_rule_caching boolean true Whether the runtime caches rule-evaluation results across an accessibility refresh. Leave at the default unless you're debugging a logic issue and need to force every rule to re-evaluate from scratch on every lookup.

Turning caching off is almost always a mistake in production — every accessibility refresh becomes O(rules × codes) rather than O(unique-codes), which can tank performance on large packs. Set it to false only temporarily, while you're hunting down a rule whose result is getting cached when you expect it not to.

Common settings files

A fixed-size streaming pack

{
    "allow_resize": false,
    "disabled_image_filter": "saturation|0.15|BT709, brightness|0.55"
}

Pins the window at the layout's natural size and gives inactive icons a softer "washed out" look instead of the default harsh grayscale — nice for streaming overlays.

A pack with custom chest art

{
    "chest_opened_img": "images/ui/chest_open.png",
    "chest_unopened_img": "images/ui/chest_closed.png"
}

Sets the chest icons pack-wide. Every location and section inherits these unless they explicitly override them.

A beginner-friendly pack that skips logic gating

{
    "always_allow_chest_manipulation": true
}

Lets the user click any chest in any section at any time, regardless of whether the access logic considers the section reachable. Useful for packs where the logic is aspirational (hints the player to the intended path) rather than prescriptive.

Tips and pitfalls

  • Every field is optional. If you don't need to override anything, don't create the file.
  • Reload (F5) picks up changes to settings.json — unlike manifest.json, which requires a full restart. See Packaging Your Pack → Reloading after edits.
  • Set disabled_image_filter here, not from Lua. The Lua property exists but is reset on every reload; this field is the supported place.
  • chest_opened_img / chest_unopened_img are pack-wide defaults, not hard overrides. Locations and sections can still override them. Set the art you want as the common case here, then override individually when you need something different.
  • Don't set auto_unpin_on_clear in settings.json. Although the parser reads it when processing location visual properties, the function explicitly skips that field when applied to the root location, so setting it at the top level of settings.json has no effect. Set it on individual locations or sections instead — see Authoring Locations.
  • Validate the JSON. EmoTracker logs the exception if settings.json fails to parse, but your pack still loads with every default in place. A JSON linter (or VS Code with the schema wired up) catches problems earlier.

See also

Home

For Users

For Developers

The Basics
Authoring Items
Authoring Locations
Authoring Layouts
Authoring Lua Scripts
Hosting Packages

Clone this wiki locally