spinning-cult: The Spinning Cult¶
spinning-cult is a complete example quest mod that adds a custom map, a new character model, a custom item and photography invention, new character animations, and synthesized background music:
- Behind a door in Palm Brinks, a large fish rotates in a dark room above a hooded figure named Brother Gill.
- Brother Gill gives Max a Camera and asks him to photograph the fish and invent an object for the town.
- Max photographs the rotating fish from three angles, invents the gŷros (a gyroscope), and shows it to five townspeople in Palm Brinks.
- Each villager who sees the gŷros begins to spin in place. After three villagers turn, Palm Brinks switches to a dark lighting preset and custom music. When all five villagers turn, they gather under the fish for the ending sequence.
This directory contains no proprietary game files:
- Base maps (
m01andm07) and villager models are exported from your retail ISO. - Python scripts for Blender procedurally generate Brother Gill, the gŷros item and character models, the Fish Room map geometry, the menu icon, and the villager animations.
- A Python script synthesizes the custom music track.
Building the mod¶
Run these commands from the repository root to export the base maps, generate the 3D assets and mod files in Blender, and build the modded ISO:
dc2tk map-export m01
dc2tk map-export m07
blender --background --python docs/scripting/examples/spinning-cult/make_gill.py
blender --background --python docs/scripting/examples/spinning-cult/make_gyros.py
blender --background --python docs/scripting/examples/spinning-cult/make_mod.py
blender --background --python docs/scripting/examples/spinning-cult/make_villagers.py
dc2tk build extracted/scripts dc2.iso -o spinning-cult.iso --mod dc2tk.spinning-cult --dev
Asset generation scripts¶
make_gill.py: Generates Brother Gill (model/gill.gltf), a 34-unit-tall robed character with an 18-bone armature and six animations:idle,beckon,raise,spin,turn_head, andvanish(a material alpha fade).mod.jsonpackages this model asmod:gill.chr(on the disc,mods/dc2tk.spinning-cult/gill.chr), whichfishroom.cloads asMOD_DIR "gill.chr".make_gyros.py: Generates the gyroscope (~7 units tall, compared to Max at 26 units) as three assets undermodel/:gyros_item.gltf: The static item model for item ID429.mod.jsonpackages it asitem/gyros.chr(matchingmodel:takaraky), anddata/items.jsonsets"model": "gyros".gyros.gltf: The animated character pack (mod:gyros.chr) with five bones (stand,outer,middle,inner,rotor) and a 4-second loopingspinanimation. Map scripts load and animate it in cutscenes withload_chara(MEMORY_STACK_EVENT, MOD_DIR "gyros.chr", "info.cfg", slot)andset_chara_motion(slot, "spin").gyros_icon.png: The 32×32 menu icon.
fish_room.py: Builds the Fish Room map in Blender from your export ofm07(nighttime Palm Brinks): clears existing placements, builds a tiled room with floor, wall, and camera collision, places a 420-unit floating fish rotated 1.5 degrees per frame by a Piece animation point, adds an exit door trigger, and places the entrance triggerdoor_fishin Palm Brinks (m01) atdoor10.make_mod.py: Runsfish_room.pyand adds:- A second fish model with dilated pupils for the ending sequence.
- Three directional photography (
Invent) bounding boxes rotating with the fish, each visible within 60 degrees of its side so photographing the fish yields Turning (251), More Turning (252), or Endless Turning (253). - Black fog and a red lighting preset for the ending in the Fish Room, plus a dark ninth lighting preset with red fog for Palm Brinks.
- The synthesized music track (
compose_turned.py). - The item icon patched into cell
191(an unused reserved cell) of the disc'stexture:itemiconsheet, quantized to the sheet's existing 256-color palette and saved totextures/itemicon.png.
make_villagers.py: Exports five Palm Brinks villagers from your disc (Parn, Sheriff Blinkhorn, Giles, Aegira, and Fournet), adds two animations to each in Blender (spinandstare), and exports them into the mod.compose_turned.py: Synthesizes"The Turning"(BG_201), a custom music track with five WAV instruments (musicbox,drone,choir,bell, andwhisper).data/items.jsonanddata/inventions.json: Configure item429(gŷros, using icon cell191on sheet1and model"gyros"), photography ideas251–253(Turning, More Turning, and Endless Turning), and the invention recipe that crafts the gŷros from one Scrap of Metal.
Script files¶
cult.h: Stores the mod's persistent state inside a single 16-bit save counter (NEW_COUNTER), accessed through a Cunionof anintand a bit-fieldstruct(tracking which of the five villagers have turned, the quest stage, whether town lighting has changed, and the total turn count).fishroom.c: The map script for the Fish Room. Controls Brother Gill, dialogue interactions, camera and item rewards, progress hints, and the ending cutscene.m01.c: A#pragma target map m01patch for Palm Brinks. Handles showing the gŷros to the five villagers, playing each villager's turning cutscene, persisting their spinning state across saves, switching the town lighting and music after the third villager turns, and facing all five villagers toward the Fish Room door after the ending.speech.h: Speech bubble and camera helper functions forfishroom.c.
Playing the mod in-game¶
With --dev, selecting New Game starts in Palm Brinks ("dev": {"start_at": "m01"}) and advances SAVE_SET_PROGRESS to 3 so the townspeople are outside.
- Enter the Fish Room and talk to Brother Gill: Enter the house door near the start of the street and talk to Brother Gill beneath the rotating fish to receive the Camera, Notebook, Photo Album, and a Scrap of Metal.
- Photograph the fish from three angles: Equip the Camera and take three photographs as the fish rotates to capture Turning, More Turning, and Endless Turning.
- Invent and craft the gŷros: Open the Invention menu, combine Turning, More Turning, and Endless Turning to invent the gŷros, and craft it using the Scrap of Metal. Show the gŷros to Brother Gill.
- Show the gŷros to five townspeople: Return to Palm Brinks and talk to Parn, Sheriff Blinkhorn, Giles, Aegira, and Fournet while holding the gŷros.
- Return to the Fish Room: Once all five villagers have turned, re-enter the Fish Room and talk to Brother Gill to watch the ending sequence.