🧩 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
└── images/
    ├── people/
    ├── belts/
    └── logos/

wrestlers.json (People Database)

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

promotions.json (World Database)

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

🔗 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 databases don't always separate commentators, interviewers, and ring announcers the way Booker Blitz does. Here is how each import handles them.

TEW database conversion (New Game → Convert Database)

• TEW's Announcer workers, its announcer and colour positions, and each promotion's or TV show's announce team all become commentators. In TEW these are the play-by-play and colour voices, not ring announcers.
• TEW Personality workers become managers.
• A worker is imported as an interviewer or ring announcer only if the database marks them that way directly. Standard TEW databases don't, so in practice a converted TEW universe has no ring announcers and its Ring Announcers key staff is empty.
• After converting, open the Staff screen or Datastudio, change your ring announcers' role to Ring Announcer, and add them to the promotion's Ring Announcers key staff.

Cagematch scraper

Roles listed on a person's Cagematch profile are read in this order:

1. Play-by-play or commentator → commentator
2. Ring announcer → ring_announcer
3. Interviewer → interviewer
4. Any other "announcer" → commentator

Pro Wrestling data converter

A promotion's two backstage staff go into its Interviewers key staff. That format has no ring announcer field, so add ring announcers by hand afterwards.