Skip to content

C Language, SDK, and Patches

Scripts in dc2tk are standard C99. What the game's virtual machine has that C does not is written as macros, which sdk/dc2tk.h defines for C compilers and editors and dc2tk compiles as built-ins, so a script (a decompiled one too) compiles with any C99 compiler: cc -std=c99 -pedantic -fsyntax-only with the SDK's folder on the include path.

Language basics

  • Built-in types: int (32-bit signed integer), float (32-bit float), and string (text literal, such as "Hello").
  • Standard C features: Functions, local and global variables, arrays, pointers (*p, &x), struct, union, enum, typedef, if/else, while, for, do/while, switch/case, break, continue, return, #define, #include, and #if.
  • The VM's statements and instructions:
    • WAIT(); — Yield execution until the next frame (1/25 second on PAL).
    • END(); — Stop the current script program immediately.
    • SKIP_END(); — Target label where a skipped cutscene jumps when the player presses Start.
    • SIN(x) and COS(x) — Trigonometric functions (angles in radians).
    • PRINT(...) — Debug print instruction.

C's semantics, and the VM's values

Every script has C's semantics: a value stored in a variable, passed to one of the script's functions or returned is converted to that type (an int stored in a float becomes a float, a float stored in an int is truncated), && and || give 0 or 1, and a native call in an operand C skips (a && get_flag(5)) is not made. A native's arguments go as they are: set_bgm_master_volume(1) passes the int 1, and the engine reads it with GetStackFloat, which converts as C does, so the native sees 1.0 either way. x = 0; with x a float stores the int 0: its bits are 0.0's, and every read of a float variable treats the slot as a float, so nothing can tell them apart.

The virtual machine keeps a value's own type where it is stored, and some of the game's scripts rely on it. The decompiler writes these macros where they do, so the script compiles to its own bytes; new code rarely needs them:

Macro What the VM does What C tools read
FLOAT_AS_INT(x) x stored, passed or returned as an int with no conversion: the variable holds a float, or (count = FLOAT_AS_INT(get_rage_hits_left());) the bits of a native's float result, which the native writes straight into it (int)(x)
INT_AS_FLOAT(x) the same for an int value where a float is expected (float)(x)
AND_VALUE(a, b), OR_VALUE(a, b) a && b and a \|\| b as the VM gives them: 0 or 1 when a decides, else b's own value, where C gives b as 0 or 1 a ? b : 0, a ? 1 : b
DOUBLE_STORE(x = value) value stored in x twice, as some scripts do (x = x = value says the same, but C leaves a variable changed twice in one expression undefined) (x = value)

A native's declaration that C cannot write (a parameter of type any, which takes whatever the call passes, or OPTIONAL(...) first) holds its parameters in VM_ARGS(...): extern void get_camera_pos VM_ARGS(any x, any y, any z) NATIVE(207);. C tools read it as a function whose parameters are not checked.

SDK headers

Every script includes the header for its script type from sdk/:

  • <event.h> — Town, story map, cutscene, and dungeon scripts.
  • <monster.h> — Monster and boss AI scripts.
  • <action.h> — Player, monster transform, and Ridepod combat scripts.
  • <effect.h> — Visual and hitbox effect scripts.
  • <arg.h> — Event argument scripts.

Two additional headers provide named constants:

  • <pal.h> — Named save flags (FLAG_...), sound banks (SE_...), and music tracks (BG_...).
  • <disc.h> — Generated by dc2tk setup from your disc. Defines every monster kind (MONSTER_GOLEM), item (ITEM_BREAD), NPC (NPC_GORDON), character motion, and effect name.

Value kinds

In the API Reference, many parameters use descriptive value kind typedefs such as monster_kind, item_id, or bgm_file. These compile as plain int or string values and tell the decompiler and editor which constants from <disc.h> or <pal.h> belong in each parameter.

modkit

sdk/modkit/ provides small C helper libraries that any mod script can include:

#include "modkit/text.c"
#include "modkit/input.c"
  • "modkit/text.c":
    • modkit_say("Hello!") — Shows a message in window 0, waits for the player to press (X) or (O), and closes the window.
    • modkit_caption("Wave 1") — Shows a non-blocking banner at the top of the screen during gameplay, or closes it when passed "".
    • modkit_text_number(0, 1, score) — Sets [Number1] before showing a message.
  • "modkit/input.c":
    • modkit_wait(frames) — Waits frames frames (25 frames = 1 second on PAL).
    • modkit_button_pressed(PAD_CROSS) — Returns 1 on the frame a button is newly pressed.
  • "modkit/tick.c":
  • "modkit/math.c": Common math helpers (modkit_abs, modkit_min, modkit_max, modkit_clamp).

For all functions, see the modkit API Reference.

Patching scripts in a mod

Instead of copying an entire game script into your mod, write a short patch .c file in mods/<your-mod>/.

Generate a starter patch with dc2tk mod override:

dc2tk mod override extracted/scripts my-mod --map s51 start_castle_battle

Or write the patch file directly:

#pragma target map s51          // Apply to map s51 (all 5 PAL languages)
#include <event.h>
#include <disc.h>

NEW_FLAG(CASTLE_MOD_ACTIVE);    // Allocate a free save flag

#pragma override                // Replace start_castle_battle in the target script
void start_castle_battle(void)
{
    original();                 // Call the original function from the game
    set_flag(CASTLE_MOD_ACTIVE, 1);
}
  • #pragma target: Selects which scripts to patch:
    • #pragma target map s51 — All 5 language variants of map s51.
    • #pragma target monster golem — The AI script for MONSTER_GOLEM (e33a).
    • #pragma target script mainchr/c01_max.c — A specific script path (* and ? wildcards allowed).
    • #pragma target library lib/map/base_town_villagers_v1.c — Every script that includes a shared library.
  • #pragma override: Replaces a function of the same name in the target script, including functions the script gets from an #include "lib/..." file. Call original(...) inside it to run the replaced function.
  • #pragma override NATIVE_NAME: Intercepts every call the target script makes to an engine native (such as place_monster or play_se).
  • #pragma every_frame: Calls a void func(void) function before every WAIT(); in the target script.

Message text formatting codes

Strings passed to show_message or modkit_say can include these tags:

Tag Displays
\n Line break
<page> Page break (waits for button press before showing the next page)
(O) (X) (A) (#) Circle, Cross, Triangle, and Square button icons
[l1] [r1] [l2] [r2] [start] [select] Shoulder, Start, and Select button icons
[Number1] … [Number16] Integer set before show_message with set_message_value(window, slot, val)
[heart] [hp] [mp] [weapon] [fish] Status and item icons

Editor setup (VS Code / clangd)

dc2tk setup writes compile_flags.txt in extracted/scripts/. Open extracted/scripts/ in VS Code with the clangd extension installed for autocomplete, type checking, and hover documentation across all natives and constants.

For a mod in mods/<name>/, dc2tk mod override (or dc2tk mod header extracted/scripts <name>) generates compile_commands.json inside the mod folder so clangd resolves all functions and globals from the target script.