Project Documentation

These notes move with each release.

Docs

🧩 Modding Guide: Custom Datapacks

🧩 Modding Guide: Custom Datapacks

This is the modder-focused section for building your own Booker Blitz universe.

For the visual datapack editor, see 8.1 DataStudio.

📁 Required Folder Structure

your-datapack/
├── wrestlers.json
├── promotions.json
├── alliances.json (optional)
└── images/
 ├── people/
 ├── belts/
 └── logos/

wrestlers.json (people and staff)

Each entry represents one person (wrestler or staff).

Must-have basics

  • Unique id
  • Name fields
  • Role/type
  • Picture filename (stored in images/people/)

Staff roles (type)

wrestler, manager, commentator, interviewer, ring_announcer, referee, writer, businessperson, medic, scout, trainer.

Commentators, interviewers, and ring announcers are separate roles. Give the person who makes ring announcements ring_announcer, not interviewer or commentator.

Common references

  • promotionId links that person to a promotion in promotions.json
  • managerId links to another person by ID

🤝 alliances.json (Promotion Alliances, optional)

Alliances are partnerships between promotions, not groups of wrestlers. Each entry has a name, an optional picture, and a promotionIds list. A promotion can only belong to one alliance, and an alliance needs at least two promotions to start the game.

Groups of wrestlers (stables, factions) are teams and live in each promotion's teams list in promotions.json. Older datapacks that list stables in alliances.json are converted into teams automatically when imported.

promotions.json (promotions and world)

Each entry is one promotion and includes:

  • Promotion identity (name, logo, region)
  • Shows and major events
  • Championships
  • Staff references
  • Storyline/tournament/team containers

Common references

  • Promotion id is used by wrestler promotionId
  • Champion and staff slots should point to valid person IDs
  • Broadcast key staff slots are role-specific: keyStaff.commentators for commentators, keyStaff.interviewer for interviewers, and keyStaff.ringAnnouncers for ring announcers. Shows accept the same slots in their own keyStaff.
  • Logo and belt image names should match files in images/logos/ and images/belts/

Broadcast key staff example

"keyStaff": {
 "commentators": [
 { "id": 101, "name": "Jim Caller" },
 { "id": 102, "name": "Joey Colour" }
 ],
 "interviewer": [{ "id": 103, "name": "Gene Mic" }],
 "ringAnnouncers": [{ "id": 104, "name": "Lillian Ring" }]
}

Each ID must point to a person whose type matches the slot (commentator, interviewer, ring_announcer). All three slots are optional. If a promotion has no keyStaff at all when a new game starts, the game builds it from the roster, including ring announcers picked from its ring_announcer staff. If you set keyStaff yourself, add ringAnnouncers by hand.

The warnings list in the in-game Editor and in Datastudio shows a notice when someone sits in a broadcast slot that doesn't match their role, for example an interviewer in ringAnnouncers. It won't stop the pack from loading, but that person won't show up as an option for the slot in game.

🖼️ Images

Use clean, consistent filenames and keep formats simple (PNG, JPG, or WebP).

  • images/people/ → wrestler/staff portraits
  • images/belts/ → championship art
  • images/logos/ → promotion logos

🏟️ Arenas (.bbarenas)

Venue data usually lives in a separate .bbarenas file (same content as arenas.json: a JSON array of arena objects). Images stay on disk in a folder you set in Settings → Data → Arenas Images Folder, they are not embedded in the pack.

On the New Game screen, open the Arenas tab to add, edit, or delete buildings before the first night. Load an arenas.json or .bbarenas file, export the list you are looking at, and point the game at a custom arena image folder. The list you leave on that tab is the one the new save books.

Give each arena a base (a wrestler home territory such as USA or Japan). Talent from that base gets a hometown crowd bump in the building. If you leave base off, the game uses location.country when it matches a territory name.

You can still include arenas.json inside a .bbdb for compatibility. The game default datapack keeps a bundled arenas.json as the fallback when no .bbarenas path is set.

🔗 ID and Reference Rules

  • Every wrestler/staff ID must be unique.
  • Every promotion ID must be unique.
  • Any referenced ID must exist.
  • Any referenced image filename must exist.
  • Keep spelling consistent for names and assets.

✅ Validation Checklist (Before Import)

  • No duplicate IDs in either JSON file.
  • All wrestler promotionId values point to real promotions (or free agent setup).
  • All manager/champion/staff references point to real people.
  • All image files exist in the correct folder.
  • Both JSON files open and parse cleanly.
  • You can load the pack and run at least one full show without errors.

📦 Packaging Tips

  • Zip the datapack root folder (with both JSON files + images/).
  • Add a short readme for your universe theme.
  • Credit any third-party art you are allowed to use.

🔄 From Your Save Game: Export as Datapack

New in v0.1.2+: You don't have to build a datapack by hand. Any save game can be exported as a ready-to-use datapack:

  1. Load your save
  2. Open Settings → Datapacks
  3. Click Export Save Database
  4. Choose a folder, the game generates wrestlers.json, promotions.json, and copies all images

This creates a fully valid datapack you can share, back up, or import into a new game via New Game → Import from Exported Datapack Folder.

Broadcast roles in imported data

Other sims' .db and .mdb files do not always split commentators, interviewers, and ring announcers the way Booker Blitz does.

Legacy .db / .mdb conversion (New Game → Custom DB → Convert Database)

  • Workers filed as announcers, plus promotion or TV announce teams, import as commentators (play-by-play and colour roles, not ring announcers).
  • Personality-style workers import as managers.
  • Interviewers and ring announcers only appear when the source file marks them that way. Many converted worlds have no ring announcers at first, so the Ring Announcers key staff slot stays empty until you fix it.
  • After converting, open Staff in the game or Staff in DataStudio, set the right Ring Announcer role, and add them to the promotion's Ring Announcers key staff.

Some older .db layouts

A promotion's two backstage staff slots may map to Interviewers key staff. If ring announcers are missing, add them manually after import.