Tutorial Overlay Projects

Tutorial: Overlay Projects — adding to a map you don't own

Some projects are built beside another one: you import a baseline, keep it out of your repo, and add your own content over the top. Three things make that work — event records, added objects, and appendable ceremonies. All three are additive: the baseline's files are never edited.

Add an object to someone else's map

data/objects/<Map>.json places NPCs, signs and trainers on a map whose .tmx you don't own:

{
 "id": "objects:PewterCity",
 "map": "map:PewterCity",
 "objects": [
  {
   "id": "SPRITE_GAMBLER@22,17",
   "x": 22, "y": 17,
   "sprite": "SPRITE_GAMBLER",
   "args": ["STAY", "DOWN"],
   "event": "event:pewter_tipster"
  }
 ]
}

One record per map, named for it. Your objects merge into the map's own list at load — the map's first, yours after — so they spawn, block movement, can be interacted with, and answer hide_object/show_object exactly like objects that came from the map file.

• id is the runtime key. Events target it ("object": "SPRITE_GAMBLER@22,17"), and so do commands like face_object. The SPRITE_X@x,y form matches what extracted maps use, so it's the convention worth following.
• args is [movement, facing] positionally — ["STAY", "DOWN"], ["WALK", "NONE"] — the way the map format stores them.
• Optional: event, plus trainer, sight, battle_text, end_text, after_text for a trainer you're adding.

--validate treats your additions as being on the map, so an event pointing at one is clean — while a genuine typo still refuses by name. And the map file is never written: your objects live only in this record, so a Studio map save can't leak them into a baseline you don't ship.

Append to a ceremony you can't copy

Some scenes are native beats — the Hall of Fame, a gift ceremony. You can't edit them and you can't copy their text, but you can run beside them:

{
 "id": "event:champion_afterword",
 "trigger": {
  "kind": "beat_start",
  "map": "map:ChampionsRoom",
  "beat": "hall_of_fame"
 },
 "commands": [
  {"cmd": "say", "text": "OAK: One more thing, {player}..."}
 ]
}

• beat_start runs just before the ceremony, beat_end just after.
• They key on the beat name, not the map — a beat can end somewhere else entirely.
• Neither consumes: every matching record runs, in filename order, and each sees the flags the previous one set. Several overlays can append to one ceremony without knowing about each other.

Which one do you want? If the ceremony's own ending closes the scene, beat_start is the hook that works. hall_of_fame saves the game and returns to the title, so a beat_end record on it would run after the player is already back at the title — its flags discarded, its text over the title screen. For ceremonies that simply return (a dex rating, a fossil revival, a prize counter), beat_end is the natural place to add your reaction.

These fire for beats your records invoke with the beat command. Beats the engine runs on its own — the opening speech, an evolution, a nurse — are the engine's ceremonies, not composition points.

Pairs with Item Field Scripts, the other "reach your own content" seam. Gates: --mapobjtest, --eventtest.