Skip to content

Developer Setup

Jump to bottom
EmoTracker Community edited this page Apr 8, 2026 · 4 revisions

Developer Setup

This page is the starting point for anyone who wants to build a pack, contribute to EmoTracker, or help improve the community service. It covers the tools we recommend, how to wire up JSON schema validation in your editor, and where to learn the two languages you'll actually write code in: JSON (for the data files) and Lua (for pack scripts).

If you're a pack author: the rest of the Developers section walks through authoring each piece of a pack. Start here, then read Authoring Items and work your way through the sub-pages.

The quick summary

  • Most of a pack is JSON. Items, locations, layouts, and maps are all JSON files placed at known paths inside the pack. Editor autocomplete and validation against the published JSON schema save enormous amounts of time — set this up first.
  • Logic and glue are Lua. EmoTracker exposes a Tracker global to Lua scripts (and some other helpers) that let you register items, react to memory changes from autotracking, and update state procedurally.
  • Everything lives on GitHub. The tracker app is in EmoTracker-Community/EmoTracker; the JSON schemas and community package index are in EmoTracker-Community/EmoTracker-Service. Forks and pull requests are how we take contributions.

Recommended tools

Tool Why
Visual Studio Code The best editor for pack authoring — first-class JSON schema support, a good Lua extension, and integrated Git.
Git + GitHub Version control is not optional. Fork the repos, branch for your work, and open PRs against the originals.
Sumneko Lua (VS Code extension) Language server, diagnostics, definitions, and autocomplete for Lua. Strongly recommended.
JSON / built-in JSON support VS Code ships with JSON support — you don't need a separate extension unless you want extras like schema previews.
Pillow (if you're working with Python tooling) Used by some community scripts for image processing. Not required for pack authoring itself.

Configuring JSON schema validation in VS Code

EmoTracker publishes JSON schemas for the three main pack file types in the EmoTracker-Service/sdk/schema directory:

Schema file What it validates
items.json Arrays of items (see Authoring Items)
locations.json Arrays of locations and their sections
layouts.json The tracker layout tree
all.json Aggregate schema — matches any of the above

Wiring these up in VS Code gives you autocomplete, inline validation of required fields, and hover documentation for every property — which is a huge quality-of-life upgrade when authoring packs.

Option A: per-pack .vscode/settings.json (recommended)

In the root of your pack repository, create .vscode/settings.json and map the schemas to the file globs in your pack:

{
  "json.schemas": [
    {
      "fileMatch": [
        "items.json",
        "items/**/*.json"
      ],
      "url": "https://raw.githubusercontent.com/EmoTracker-Community/EmoTracker-Service/main/sdk/schema/items.json"
    },
    {
      "fileMatch": [
        "locations.json",
        "locations/**/*.json"
      ],
      "url": "https://raw.githubusercontent.com/EmoTracker-Community/EmoTracker-Service/main/sdk/schema/locations.json"
    },
    {
      "fileMatch": [
        "layouts.json",
        "layouts/**/*.json"
      ],
      "url": "https://raw.githubusercontent.com/EmoTracker-Community/EmoTracker-Service/main/sdk/schema/layouts.json"
    }
  ]
}

Adjust the fileMatch globs to whatever your pack actually uses. Many packs split items into several files like items/common.json, items/keys.json, etc., and the **/*.json pattern covers all of them.

Option B: user-level settings.json

If you work on several packs and want the schemas active everywhere, put the same json.schemas block into your VS Code user settings. The trade-off is that the globs are applied globally — using a more specific glob like **/items/**/*.json helps avoid false positives on unrelated projects.

Pointing at a local schema

If you want to test changes against a modified local copy of a schema, replace the "url" field with a "url" that uses the file:/// scheme, or use $schema inside the JSON file itself:

{
  "$schema": "../../EmoTracker-Service/sdk/schema/items.json"
}

This is handy when you're contributing to the schema itself and want both files to update in lockstep.

Verifying it works

Open any items JSON file in VS Code and:

  • Type "type": " inside an item object — you should get a drop-down of the valid type values (toggle, progressive, consumable, etc.).
  • Hover a property name — the description from the schema should appear in a tooltip.
  • Remove a required field — VS Code should underline the object in red with an explanation.

If none of that happens, the glob didn't match. Check Output → JSON Language Server in VS Code for errors.

Learning JSON

Pack data files are plain JSON. If you've never worked with JSON:

  • json.org — the original spec in a single page. Skim it once and you'll know the entire language.
  • MDN: Working with JSON — a gentle introduction with examples.
  • JSON Schema — the spec EmoTracker's schemas are written against. Only needed if you want to modify the schemas themselves, but useful for understanding why the existing ones are structured the way they are.

A few quick tips:

  • Trailing commas and comments are not allowed in strict JSON. VS Code's JSON mode will flag them — some editors' "JSON with comments" modes allow comments, but EmoTracker's loaders don't.
  • Always save as UTF-8 without a BOM.
  • When in doubt, copy a similar item from an existing pack (the official ALttPR pack is a good reference) and modify it.

Learning Lua

Pack scripting is Lua (currently Lua 5.3/5.4 semantics via the embedded runtime). If you've never written Lua before, pick whichever resource matches your style:

What you actually need for pack authoring is:

  • Tables (both as arrays and as dictionaries)
  • Functions and closures
  • String manipulation
  • The require-like convention EmoTracker uses for loading other Lua files in the pack

You don't need OOP, coroutines, metatables, or the C API.

The pack directory layout

A typical pack looks something like this:

my_pack/
├── manifest.json         # Pack metadata — required, at the root
├── scripts/
│   └── init.lua          # Entry point — EmoTracker runs this when the pack loads
├── items/
│   ├── common.json       # Items data files, loaded by scripts/init.lua
│   └── keys.json
├── locations/
│   └── ...               # Location data files
├── layouts/
│   └── ...               # Layout data files
└── images/               # Pack's icon/image assets referenced from JSON
  • manifest.json is the only file EmoTracker strictly requires at a known path — it tells EmoTracker the pack's name, game, variants, etc. See Authoring a Manifest for the full reference.
  • Everything else is loaded by your Lua code via Tracker:AddItems("items/common.json"), Tracker:AddLocations(...), Tracker:AddLayouts(...), etc.
  • Files are always referenced relative to the pack root in the JSON paths you pass to those functions.

Where to get help

  • EmoTracker Discord — the fastest way to get an answer, especially for pack-specific questions. There's a developer channel where other pack authors hang out.
  • Existing packs on GitHub — the package repositories list links to dozens of community packs. Reading a working pack that targets a similar game is often the fastest way to figure out how to structure yours.
  • The EmoTracker source — EmoTracker-Community/EmoTracker on the avalonia branch is authoritative. When a docs page disagrees with the code, the code wins — please open an issue so we can fix the docs.

See also

Home

For Users

For Developers

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

Clone this wiki locally