Add a cutscene to a town¶
This guide shows how to add a one-time welcome cutscene to Sindain (g01) using a #pragma override patch and mod.json. For background on retail cutscene structure, see Cutscenes.
1. Inspect the map's entry program (Before)¶
Run dc2tk map to inspect Sindain (g01):
In extracted/scripts/map/g/g01_sindain/g01_1.c, map_start (100) runs play_map_start_arrival:
// extracted/scripts/map/g/g01_sindain/g01_1.c
PROGRAM(setup, setup_georama_editing_by_flag);
PROGRAM(map_start, play_map_start_arrival);
2. Write the cutscene patch (After)¶
Generate a patch for play_map_start_arrival on map g01:
Edit mods/sindain-hello/g01.c to allocate a save flag (NEW_FLAG), run the original play_map_start_arrival handler, and play a short welcome cutscene the first time the player enters Sindain:
// mods/sindain-hello/g01.c
#pragma target map g01
#include <event.h>
#include <pal.h>
#include <disc.h>
#include "modkit/text.c"
NEW_FLAG(SINDAIN_HELLO_SEEN);
static void wait_for_actor(int actor)
{
while (check_actor_busy(actor)) {
WAIT();
}
}
static void play_sindain_hello(void)
{
float x, y, z;
if (get_flag(SINDAIN_HELLO_SEEN)) {
return;
}
set_flag(SINDAIN_HELLO_SEEN, 1);
init_event();
init_chara_actor(0, CHARA_PLAYER);
get_chara_pos(CHARA_PLAYER, &x, &y, &z);
cut_camera(x + 120.0, y + 60.0, z + 120.0, x, y + 20.0, z);
move_camera_to(x + 60.0, y + 30.0, z + 80.0, x, y + 20.0, z, 60);
play_actor_motion_then_loop(0, MOTION_WAVE, MOTION_STAND_2);
wait_for_actor(0);
modkit_say("Sindain looks busier today.");
reset_camera(CAMERA_RESET_ACTIVE);
finish_event();
}
#pragma override
int play_map_start_arrival(void)
{
int result;
result = original();
play_sindain_hello();
return result;
}
play_sindain_hello follows the standard cutscene lifecycle:
- Check and set
SINDAIN_HELLO_SEENso the cutscene plays only once. - Call
init_event()and bind actor0toCHARA_PLAYER. - Queue the camera movement and wave animation, then wait until actor
0finishes. - Show the dialogue line with
modkit_say. - Restore the gameplay camera with
reset_camera(CAMERA_RESET_ACTIVE)and exit event mode withfinish_event().
3. Add mod.json and test in-game¶
Create mods/sindain-hello/mod.json with "dev": {"start_at": "g01"} so New Game spawns directly in Sindain:
{
"format": 2,
"id": "you.sindain-hello",
"version": "1.0.0",
"name": "Sindain Hello",
"dev": {"start_at": "g01"}
}
Validate and build:
dc2tk mod check extracted/scripts you.sindain-hello
dc2tk build extracted/scripts dc2.iso -o test.iso --mod you.sindain-hello --dev --play
Tip: Custom characters, scene skipping, and warps - Triggering from a warp or map point: Declare
NEW_PROGRAM(HELLO_SCENE);andPROGRAM(HELLO_SCENE, play_sindain_hello);, then warp to it withjump_to_map(-1, "g01", HELLO_SCENE)or set"dev": {"start_at": "g01:HELLO_SCENE"}inmod.jsonand build with--dev. - Adding NPCs: Load.chrmodels into unused scene slots withload_inactive_charaorload_scene_chara, bind actors to those slots, and calldelete_charabeforefinish_event(). - Skipping with Start: Wrap the camera and actor sequence betweenenable_scene_skip();andSKIP_END(); disable_scene_skip();. Keep allset_flag,delete_chara, andfinish_eventcalls outside the skippable block. - Complete example: Seespinning-cultfor a multi-scene quest mod with custom Blender models and map triggers.