Given Jar Example

given.jar is a complete Minecraft Bedrock add-on built with the five skills as their first real test. It lives in examples/given-jar/ with its own README. Display name given.jar; identifier namespace given_jar, because a dot inside a namespace is risky in identifiers and Molang. Target: Windows PCs on one LAN world, about four players, no experiments, cheats off.

The game

A dark sphere with one big bloodshot eye, named The Given, floats in the world. When its eye opens it asks for an item, the same item for everybody. Every player in survival must find their own copy and drop it on the sphere before the clock runs out. If everyone delivers, the eye closes for a break and then asks again. If someone does not, the whites of the eye turn blood red and the sphere flies through walls to catch them, one player at a time.

For players there is a one-page guide in plain words: HOW-TO-PLAY.md.

Rules (what the code does)

	Normal	Test mode
Mission time	30 min	30 s
/given_jar:skip takes off	10 min	10 s
Eye closed between missions	10 min	10 s
First mission after the sphere arrives	5 s	5 s

• One sphere per world (given_jar:watcher), from the spawn egg or /given_jar:summon. A second one disappears with a chat message.
• A mission picks one item from the current tier (/given_jar:tier easy|medium|hard, default easy), never the same item twice in a row. src/items.ts lists 37 easy, 25 medium and 20 hard items, each with a checked vanilla texture path.
• Delivering means dropping the item on the sphere or just in front of it. The player who dropped it gets the credit, found by watching whose inventory lost one, not by who stands closest. One item is used up; extras are given back.
• When everyone in survival or adventure has delivered, the eye closes for the break, then a new mission starts by itself.
• When the clock runs out, everyone in survival or adventure who did not deliver is on the list. The eye turns red, and the sphere flies straight at the closest one, through blocks, 6 blocks a second. A touch deals 1000 damage through applyDamage, so a Totem of Undying still works. Then the next closest, until each has been caught once.
• Leaving the game, going to another dimension, or dying some other way also counts as caught.
• A totem save: the eye closes and the sphere backs away for 3 seconds, waits 4, then appears right in front of the player's face with the red eye and a scream (no flashing). That counts as caught.
• Creative and spectator players are left out of everything.
• If the sphere's chunk unloads during a hunt, a new sphere appears near the target, and the old one is removed when its chunk loads again.

Every number lives in src/config.ts.

Commands

Custom commands need operator rights (Game Directors) but not cheats. /given_jar:status works for everyone.

Command	Fallback (needs cheats)	What it does
/given_jar:summon	/scriptevent given_jar:summon	Brings The Given 3 blocks in front of you
/given_jar:attack	/scriptevent given_jar:attack	Summons The Given if needed, then starts the hunt now (to try the hunt)
/given_jar:skip	/scriptevent given_jar:skip	Takes 10 minutes off; below zero, the hunt starts now
/given_jar:tier easy|medium|hard	/scriptevent given_jar:tier hard	Item difficulty from the next mission on
/given_jar:testmode on|off	/scriptevent given_jar:testmode on	Minutes become seconds
/given_jar:status	/scriptevent given_jar:status	Phase, item, time left, who still has to deliver
	/scriptevent given_jar:selftest	The in-world self-test, for a throwaway server world

Bedrock also registers short aliases (/skip, /tier) when the name is free. /summon belongs to the vanilla command, so always type /given_jar:summon. Bedrock Dedicated Server says so in a warning at startup (Checks and the BDS harness).

Architecture

src/config.ts          every duration, speed and distance
src/items.ts           curated items per tier, with checked vanilla texture paths
src/core/              pure rules, no @minecraft imports: machine.ts (state machine), zone.ts (where a drop counts),
                       attribution.ts (who dropped it), serialize.ts (save/load), hud.ts (title markers), vec.ts
src/main.ts            Script API adapter: one system.runInterval loop, commands, events, the self-test
test/                  node:test unit tests of the rules, items and geometry helpers
behavior_pack/         manifest, entities/watcher.json, texts; scripts/main.js is built
resource_pack/         client entity, model, render controller, animations, textures, ui/hud_screen.json, texts
scripts/               build helpers (geometry, textures, pack, texture fixture)

How it uses the patterns from Design and Script API:

• Pure core, thin adapter. src/core/ holds the rules with no @minecraft/* import; src/main.ts is the only file that talks to the game.
• One loop. system.runInterval(loop, CONFIG.loopTicks), every 2 ticks.
• State. One world dynamic property (given_jar:state), saved every 5 seconds and on every change, so a reload resumes the mission.
• Rendering. Entity properties given_jar:eye and given_jar:mode drive the render controller, which picks the open, closed or red eye texture.
• Credit for a drop. Inventory diffs between ticks, and a dynamic property on the item entity naming the dropper.
• HUD. A title gj_item:<texture path> with the subtitle Bring me: <item>, and an actionbar updated every second. resource_pack/ui/hud_screen.json hides the raw title, shows the item picture mid-screen and drops it toward the actionbar. Without JSON UI, players see the raw gj_item: text once, and the subtitle, chat and actionbar still say everything (HUD and UI).

The textures came from our own image generation, with prompts and settings in art/PROMPTS.md. The HUD shows vanilla item textures by path; those are Mojang's and are not shipped in the add-on.

Build

Needs Node 24, and Python 3 for packing (Pillow only for regenerating textures). In examples/given-jar:

npm install
npm run typecheck     # tsc --noEmit
npm run lint          # eslint with typescript-eslint and eslint-plugin-minecraft-linting
npm test              # node --test, Node 24 strips the types; no build step
npm run build         # esbuild: src/main.ts -> behavior_pack/scripts/main.js (@minecraft/* external)
npm run pack          # build + scripts/pack.py -> dist/given-jar-<version>.mcaddon

On 2026-10-27, npm ci, npm run build and scripts/pack.py ran on a copy of the example and wrote a 19-file .mcaddon (Project and packaging). CI runs npm ci, the type check, lint, unit tests, build and pack on every push, then mw_check.py on the result.

What is tested, and by what

Layer	Tool	Result on 2026-10-27
Rules	npm test: 40 unit tests in 13 suites under node --test	40 pass
Packs, types, lint	mw_check.py	7 pass, 0 fail, 1 skip (mct, opt-in)
Scripts on a real server	bds_run.py with scriptevent given_jar:selftest on BDS 1.26.60.6	11 PASS markers, 0 errors
Everything a person sees	the manual playtest	owed

The full reports are on Checks and the BDS harness. The 11 self-test checks: scripts_loaded, config_loads, commands_registered, custom_command_runs, tickingarea_loaded, sphere_spawns, entity_properties, one_sphere_per_world, item_delivery, teleport_phases_through_blocks and state_persists. Between them they prove that a ticking area loads a chunk with no players connected, that entities and items spawn there, that entity properties read back one tick after being set, that teleport steps carry an entity through stone, that item entities keep dynamic properties, that custom commands run from a script, and that world state survives a save and load.

Playtest

What only a person can check (rendering, HUD, sounds, the hunt, the totem) is in PLAYTEST.md: 37 numbered steps in test mode, best with two players on LAN, grouped as arrival, mission, skip, hunt, totem jump-scare and saving, plus a look-and-feel list. It ends with a question for the group: is anything too scary for the youngest player? None of it has been run for this wiki.

Install

INSTALL.md covers Windows: close Minecraft, double-click the .mcaddon, activate the behavior pack on a world with experiments off, and turn on LAN. Other platforms: Platforms and install. Download the .mcaddon from CurseForge or the GitHub release, or build it with npm run pack.

Known limits

• Bedrock merges item entities lying close together. If two players drop the mission item on the same spot within a moment, the merged stack keeps one dropper, and the other player has to drop again.
• Items moved by hoppers or dispensers have no dropper and never count.
• The texture glow and the HUD offsets were tuned without seeing them in the game; PLAYTEST.md has the checks.