Script API

Globals

• function main(drone: drone, owner: owner, args: {[input: string]: any})

  Define this in every program, as a generator: function* main(drone, owner, args) { ... }. The program runs from it; it yields drone actions to wait on them, and ends when it returns. `args` holds what the player picked for the inputs the program declares in its header comments, one line each: `// @input <name> <kind> "<prompt>" [optional] [default=owner|look|here]`. Before the program runs the console walks the player through them (a click, or a zone or route drawn) and shows the prompt; an optional one can be skipped with Esc or Enter. The kinds and what args.<name> is: `point` and `chest` (a container block) are {x, y, z}; `area` is {center: {x, y, z}, radius} (radius 1 to 16); `entity` is what a scan gives of a body ({id, type, name, x, y, z, ...}); `path` is a list of {x, y, z} (at most 32). An optional input left out with no default is not a property, so args.<name> is undefined: test it before use. default=owner uses the owner's own spot (or the owner, for an entity), default=look the block (or body) they are looking at, default=here the spot the drone stands on. A program with no inputs gets an empty args. A program runs in a locked-down scope: Promise, Map, Set, WeakMap, WeakSet, Symbol, BigInt, ArrayBuffer and the typed arrays, XML and RegExp are not defined (nothing queues work behind the program's back, and a regular expression cannot run away), so a regular expression literal or any regex-taking String method (match, search, split or replace with a pattern) is an error; split(","), replace("a", "b" or a function), replaceAll, indexOf and includes work on plain strings. Arrays and strings are capped at 100000 elements or characters (fill, join, repeat, padStart, padEnd and the other array methods throw past it; join and JSON.stringify refuse results over a million characters or 200000 values). A program that holds more than about 16 MB of values stops with "out of memory"; a step that runs over 200000 instructions, nests structures too deeply for the stack or fails any other way crashes that program alone.

• function plan(ctx: {tick: number, dt: number, params: {kind: string, radius: number, height: number, speed: number, passes: boolean, tighten: number, defendOnly: boolean, retreatBelow: number, engageRange: number, spreadRadius: number}, owner: {id: string, pos: {x: number, y: number, z: number}, look: {x: number, y: number, z: number}, velocity: {x: number, y: number, z: number}, pool: number, health: number, maxHealth: number, yaw: number, anchorYaw: number, age: number, onGround: boolean}, target: {id: string, type: string, pos: {x: number, y: number, z: number}, velocity: {x: number, y: number, z: number}, pool: number, distance: number, airborne: boolean, hostile: boolean, player: boolean, effects: object} | null, enemies: {id: string, type: string, pos: {x: number, y: number, z: number}, velocity: {x: number, y: number, z: number}, pool: number, distance: number, airborne: boolean, hostile: boolean, player: boolean, effects: object}[], units: {index: number, slot: number, id: string, pos: {x: number, y: number, z: number}, velocity: {x: number, y: number, z: number}, pool: number, target: string | null, ready: object, order: string | null, busy: boolean, fallingBack: boolean}[], state: object})

  A formation script defines this, and the game calls it every few ticks (the file's @cadence, 5 to 10, slower when the server is under load) once for the whole squad. ctx is a snapshot, capped (at most 16 enemies and 16 units) and rebuilt each plan: ctx.tick (the world's time), ctx.dt (ticks since the last plan), ctx.params (numbers from the squad's definition), ctx.owner (the body the squad guards: its position, look, velocity and yaw are the owner's, or the stand-in body's while the owner has left one behind; id and health stay the owner's), ctx.target (the squad's main target, or null), ctx.enemies, ctx.units (each with ready: which of its moves are off cooldown) and ctx.state, an object that is yours and keeps what you store on it from one plan to the next. Return {units: [...]} with one entry per ctx.units entry, in order (null leaves a unit to the default). An entry is {point, face?, target?, prefer?, hold?, speed?, pass?, direct?}: point is where the unit should be (the game steers it there round walls and moves it to open air with a line to its target, unless direct); face a point to look at; target an enemy id from ctx.enemies; prefer a list of move ids to favour when the unit picks a move (it still cannot use one on cooldown, out of range or without a line of sight); hold stands still; speed is blocks a tick; pass marks a fly-through. The result may also say defendOnly: true (fight only what attacks the owner or the squad) and scout: true. A plan may run 50,000 instructions. If it throws, overruns or returns nonsense (a point more than 80 blocks from the owner, NaN), the last good plan is kept, then a ring round the owner; a built-in only logs, but a formation of a player's takes their suit offline like a crashed program. The file's first lines are its header: // @formation "Name" makes it a formation (in a program-store file it also keeps the editor from running it as a drone program); // @description is a line for the picker; // @cadence N plans every N ticks (5 to 10, default 5); // @pattern surround|escort|ring takes ctx.params from the squad's pattern of that kind; // @order N sorts the built-ins.

• vec(x: number, y: number, z: number)

  A point.

• add(a: {x: number, y: number, z: number}, b: {x: number, y: number, z: number})

  a + b.

• sub(a: {x: number, y: number, z: number}, b: {x: number, y: number, z: number})

  a - b.

• scale(a: {x: number, y: number, z: number}, k: number)

  a times k.

• len(a: {x: number, y: number, z: number})

  The length of a.

• dist(a: {x: number, y: number, z: number}, b: {x: number, y: number, z: number})

  The distance between two points.

• flat(a: {x: number, y: number, z: number})

  a with y set to 0.

• norm(a: {x: number, y: number, z: number})

  a scaled to length 1 ({0, 0, 0} for a point at the origin).

• rotY(a: {x: number, y: number, z: number}, radians: number)

  a turned round the vertical axis.

• yawVec(degrees: number)

  The horizontal unit vector a Minecraft yaw faces: 0 is +z, 90 is -x. owner.yaw and owner.anchorYaw are in these degrees.

• toward(from: {x: number, y: number, z: number}, to: {x: number, y: number, z: number}, step: number)

  from moved toward to by at most step (to itself when it is that close).

• clamp(v: number, lo: number, hi: number)

  v kept between lo and hi.

• component(body: (component: Component) => void) | component(id, body)

  Ability scripts (data/<namespace>/abilities/<any folders>/<name>.js): declares an ability as a component -- the parts it is built from, and the phases it can be in. A file that declares one may leave it unnamed and the file name is its id; a file may declare any number in loops, naming each (component(id, ...)), over the read-only lists registry(), tag(), tags() and data(). The body runs once at load and builds the same definition the JSON format holds, through the builder it is handed; it never runs on the key press. Every builder method: section ability_script, or docs/thematic.d.ts.

• ability(id, type, options?)

  Ability scripts: defines an ability of a built-in Java type (docs/ability-types.md), configured as its JSON file would be.

• preset(id: string, spec: PresetSpec, apply: (def: ContentBuilder, options: any) => void): void

  Preset libraries: data/<namespace>/content_prefabs/<any folders>/<file>.js. A file declares any number of presets, preset(id, { kind, doc, options }, (def, options) => { ... }), each a bundle of fields and hooks a definition of that kind applies by name with def.use(id, options). The function is handed the definition's own builder, so it calls the same set() and hook methods the file would. A bare id is thematic:.

• contentSample(body: (def: ContentBuilder) => void): void | contentSample(type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void | contentSample(id: string, type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void

  A sample kind that proves the scripted-content pipeline end to end; the engine ships no files of it. data/<namespace>/content_samples/<any folders>/<id>.json or .js. Files in data/<namespace>/content_samples/ call it: once, when the file name is the id, or once per id, naming each (a family file).

• statusEffect(body: (def: ContentBuilder) => void): void | statusEffect(type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void | statusEffect(id: string, type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void

  Status effects: data/<namespace>/status_effects/<any folders>/<id>.json or .js. The file name is the effect's id (status_effects/stun.json is thematic:stun). Each id registers its own status effect at startup, so a new one, or a changed category, colour, attribute modifier or stun flag, needs a restart; everything else reloads with /reload. How the effect looks on a suit is an effect_visuals file of the same id. Files in data/<namespace>/status_effects/ call it: once, when the file name is the id, or once per id, naming each (a family file).

• damageElement(body: (def: ContentBuilder) => void): void | damageElement(type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void | damageElement(id: string, type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void

  What a hit can be made of, for the weakness, resistance and immunity system: data/<namespace>/damage_elements/<any folders>/<id>.json or .js. The file name is the element's word (damage_elements/fire.json is "fire", the word suits, ability options and the element option use). The damage types themselves stay vanilla damage_type JSON; an element says which of them, and which damage-type tags, count as it. A hit also counts when its type is in the tag <namespace>:is_<id> (when the element has a damage_type) or <namespace>:compat/<mod>/<id> (while that compat module bridges damage types). Read on each side at startup and reloaded with /reload; a pack overrides an engine element by writing the same id. Files in data/<namespace>/damage_elements/ call it: once, when the file name is the id, or once per id, naming each (a family file).

• vfxPreset(body: (def: ContentBuilder) => void): void | vfxPreset(type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void | vfxPreset(id: string, type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void

  Named effects the vfx action plays: data/<namespace>/vfx/<any folders>/<id>.json or .js. The file name is the id (vfx/sonar_beam.json is thematic:sonar_beam); the old upper-case preset names still find them ("SONAR_BEAM" is thematic:sonar_beam). Read on the server, which sends the finished effect to every client near it, and reloaded with /reload. Files in data/<namespace>/vfx/ call it: once, when the file name is the id, or once per id, naming each (a family file).

• block(body: (def: ContentBuilder) => void): void | block(type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void | block(id: string, type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void

  Blocks: data/<namespace>/blocks/<any folders>/<id>.json or .js registers the block <namespace>:<id> and its block item. Blocks are registry entries, read once at startup from mod jars, the dev tree and thematic/packs: a new block or a changed identity field needs a restart. The type is the block's shape and rules (a vanilla shape: solid, slab, stairs, wall, door...); a .json file names it (or a parent that does), a script's block(def => ...) is solid when it names none. Its model, blockstate, loot table and lang lines are ordinary resource files under the same id. Files in data/<namespace>/blocks/ call it: once, when the file name is the id, or once per id, naming each (a family file).

• item(type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void | item(id: string, type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void

  Items: data/<namespace>/items/<any folders>/<id>.json or .js registers the item <namespace>:<id>. Items are registry entries, read once at startup from mod jars, the dev tree and thematic/packs: a new item or a changed identity field needs a restart, while hooks, stats and looks retune on /reload. Files in data/<namespace>/items/ call it: once, when the file name is the id, or once per id, naming each (a family file).

• arrow(body: (def: ContentBuilder) => void): void | arrow(type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void | arrow(id: string, type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void

  Trick arrows: data/<namespace>/arrows/<any folders>/<id>.json or .js. Each id registers its own arrow item and entity type at startup (a restart is needed for a new one); the definition is what its hits do, how it looks and how it flies, and it reloads with /reload. Files in data/<namespace>/arrows/ call it: once, when the file name is the id, or once per id, naming each (a family file).

• throwable(body: (def: ContentBuilder) => void): void | throwable(type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void | throwable(id: string, type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void

  Things thrown and flying: gadgets, grenades, vials, thrown items. data/<namespace>/throwables/<any folders>/<id>.json or .js. Every one is the entity thematic:thrown; the definition is how it flies, looks and what its hits do. A definition with an item block also registers that item (a restart is needed for a new one). Files in data/<namespace>/throwables/ call it: once, when the file name is the id, or once per id, naming each (a family file).

• criminal(body: (def: ContentBuilder) => void): void | criminal(type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void | criminal(id: string, type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void

  Criminals: data/<namespace>/criminals/<any folders>/<id>.json or .js. Each id registers its own entity type, attributes, spawn rules and spawn egg (<id>_spawn_egg) at startup (a restart is needed for a new one, or for new stats); the look, the fight and the hooks reload with /reload. A crew file defines many ids, criminal("<id>", "thematic:criminal", c => c.use("thematic:criminal_<role>", { ...crew })). Files in data/<namespace>/criminals/ call it: once, when the file name is the id, or once per id, naming each (a family file).

• entity(type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void | entity(id: string, type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void

  Entity types: data/<namespace>/entities/<any folders>/<id>.json or .js. "type" names the body (a generic entity: zone, tether, owner_copy, mob, vehicle...) and the file sets its options. Each id registers its own entity type at startup (and a spawn egg <id>_spawn_egg with spawn_egg), so a new one, or a changed size, group, tracking, attributes, egg or boss flag, needs a restart; the render block and the body's options reload with /reload. Files in data/<namespace>/entities/ call it: once, when the file name is the id, or once per id, naming each (a family file).

• profession(body: (def: ContentBuilder) => void): void | profession(type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void | profession(id: string, type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void

  Villager professions: data/<namespace>/professions/<id>.json. The file name is the profession's id, and an unemployed villager near the workstation block takes the job, restocking there like any villager. Its name is the lang key entity.minecraft.villager.<file name>. A new id or a changed workstation needs a restart; the look and trades reload. Files in data/<namespace>/professions/ call it: once, when the file name is the id, or once per id, naming each (a family file).

• suit(body: (def: ContentBuilder) => void): void | suit(type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void | suit(id: string, type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void

  Suits: data/<namespace>/armors/<collection>/<any folders>/<id>.json or .js. The first folder under armors/ is the suit's collection (data/<namespace>/collections/<collection>.json describes it). A suit's id is always thematic:<file name>, whatever namespace the file is in. A file with "parent", or one under a folder named alt/, is an alt (a skin variant) of its parent. Each id registers its own suit item at startup (a restart is needed for a new one); the kit reloads with /reload. When two packs define one suit id, the higher pack's file is the one /reload applies, whatever folder it sits in, unless the other sets a higher "priority". Files in data/<namespace>/armors/ call it: once, when the file name is the id, or once per id, naming each (a family file).

• abilityEffect(body: (def: ContentBuilder) => void): void | abilityEffect(type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void | abilityEffect(id: string, type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void

  Ability effects: data/<namespace>/ability_effects/<any folders>/<id>.json or .js. What a beam, a bolt or a spray carries (an ability's "effects": ["thematic:laser", {"id": "thematic:blindness", "duration": 3.5}]) and does to what it hits. Read before abilities are, and again on /reload. Files in data/<namespace>/ability_effects/ call it: once, when the file name is the id, or once per id, naming each (a family file).

• effectVisual(body: (def: ContentBuilder) => void): void | effectVisual(type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void | effectVisual(id: string, type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void

  How a status effect shows on a suit: data/<namespace>/effect_visuals/<any folders>/<effect>.json or .js. The file name is the status effect's id (effect_visuals/frozen.json is thematic:frozen), or its effect field names one. Synced to clients and reloaded with /reload; an effect with no file shows nothing on the suit. Files in data/<namespace>/effect_visuals/ call it: once, when the file name is the id, or once per id, naming each (a family file).

• animController(body: (def: ContentBuilder) => void): void | animController(type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void | animController(id: string, type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void

  The GeckoLib controllers every suit carries: data/<namespace>/anim_controllers/<any folders>/<id>.json or .js. The engine ships thematic:armor (anim_controllers/armor.js); a pack changes it by shipping the same path, or adds to it with a file of its own id. Every definition is read together, thematic:armor first and the rest in id order: a later one's idle wins, its states are tried before the earlier ones', its while_active controllers and trigger_clips_from are added, and its effect_clips replace the same effect's. What plays reloads with /reload; which controllers a suit has is fixed when the suit is first drawn. Synced to clients. Files in data/<namespace>/anim_controllers/ call it: once, when the file name is the id, or once per id, naming each (a family file).

• encounter(body: (def: ContentBuilder) => void): void | encounter(type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void | encounter(id: string, type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void

  Ready-made missions: data/<namespace>/encounters/<any folders>/<id>.json or .js. The file name is the template's name (/thematic dev encounter template <name>, /thematic dev encounter import <name>, an NPC start). The fields are the wave spawner's own encounter NBT, key for key, so a mission authored in game and exported with /thematic dev encounter export is already a valid file. Read by the server and reloaded with /reload; a file in config/thematic/encounters/ with the same name wins. Files in data/<namespace>/encounters/ call it: once, when the file name is the id, or once per id, naming each (a family file).

• arenaTheme(body: (def: ContentBuilder) => void): void | arenaTheme(type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void | arenaTheme(id: string, type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void

  Remembered places shown round a mission: data/<namespace>/arena_themes/<any folders>/<id>.json or .js. An encounter names one in Arena.Memory (a bare name means thematic:). The place is vanilla structure templates, dissolved at their edges and set in a ring beyond the fight, shown only to the participants. Read by the server and reloaded with /reload. Files in data/<namespace>/arena_themes/ call it: once, when the file name is the id, or once per id, naming each (a family file).

• pocketDimension(body: (def: ContentBuilder) => void): void | pocketDimension(type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void | pocketDimension(id: string, type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void

  Pocket dimensions a wearer is sent into for a while and then brought back from: data/<namespace>/pocket_dimensions/<any folders>/<id>.json or .js. The file name is the pocket's id, which the Java that sends someone in names. The dimension itself stays vanilla data (dimension/<id>.json and its dimension_type, whose coordinate_scale scales the walk back out). Read by the server and reloaded with /reload. Files in data/<namespace>/pocket_dimensions/ call it: once, when the file name is the id, or once per id, naming each (a family file).

• multiblock(body: (def: ContentBuilder) => void): void | multiblock(type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void | multiblock(id: string, type: string, body?: ((def: ContentBuilder) => void) | { [field: string]: unknown }): void

  Structures built from blocks the player places in a layout: data/<namespace>/multiblocks/<any folders>/<id>.json or .js. Using a placed part runs the thematic:assemble action, which swaps the layout for another set of blocks (a model block and its fillers); breaking any of them runs thematic:disassemble, which swaps the parts back. Read by the server and reloaded with /reload. Files in data/<namespace>/multiblocks/ call it: once, when the file name is the id, or once per id, naming each (a family file).

• gun(body: (gun: Gun) => void) | gun(type, body)

  Gun scripts (data/<namespace>/guns/<any folders>/<id>.js; gun_effects/ calls gunEffect(type, fields), huds/ calls hud(body)): declares the file's gun, effect or HUD, built once at load into the same JSON the .json format holds. Every builder method: section gun_script, or docs/thematic.d.ts.