Research Report R3 Kisculeref

Kiscule Node Reference for Modders

This track asked for a complete, modder-usable reference of TNC's "kiscule" mission-scripting node graph — what each of the 205 used node types does, how they wire together, and which ones are relevant to building spawn/trigger/objective/door/dialogue/music logic in a custom map. The answer is a machine-readable catalogue built by scanning all 2,408 retail mission scripts (70,274 node instances), cross-checked against the game's own RTTI class list with zero missing classes. All of this is static analysis of retail decl data — nothing about actual node behavior was tested in a running game. This pass added a corpus-verified wiring idiom (multiple edges into one input port) and a first behavioral read of three previously-undocumented bitflags.

Format, numbers

• 205 distinct node types actually used in retail scripts, all resolve by exact name in the game's RTTI with the expected base class. 153 inherit idKisculeInstanceNode directly, 29 idKisculeNodeNotification directly, 23 through the typed idKisculeVariableNode<T> template family.
• 176 distinct parameters.class payload classes back the 205 node types (6 are shared by several node types — e.g. all 5 NamedVariable* nodes share one parameters class).
• Wiring grammar: Regular ports carry an execution pulse, Variable ports carry a value, Notification ports are event outputs; every parameter also exists as an InputVariable/OutputVariable pair of the same name.
• New idiom, corpus-proven: a single input port instance can receive more than one wired edge. Example: AiKilledNotification.listenedEntities — 114/157 retail instances have at least one EntityReference edge, 29 have exactly two, one has eight. A node can listen to several named entities wired individually, not just via one ListEntityReference.
• properties bitmask, partially decoded behaviorally (not from source): bit 0x1 marks a non-core/optional port (95% correlation); bit 0x4 is used exclusively by FlowFlagCheck's dynamic per-flag ports; bit 0x20 correlates 100% both ways with "never wired in any retail script" (1,817 occurrences, 0 wired) and is not simply the editor's "visible" flag (88% of those ports are still marked visible).

Custom-map categories (retail usage counts)

Category	Used node types	Notes
spawn	AiKilledNotification (157), PlayerStartNotification (76), AISpawnNotification (8), ActionAISpawn (1 — almost never used; spawning is normally done via map-layer idTarget_AISpawn entities, not from inside a script)
trigger_volume	TriggerNotification, VolumeNotification (classFilter="idAI2" used 58 times for AI-only volumes), UseNotification, ActionActivatable, ActionTrigger, ActionRemoveAIFromVolume, AIVolumeCountNotification, FlowEntityInVolume
objective	ActionMission family — 407 instances/69 scripts is the objective-chain hub
door_like	no dedicated "Door" node is used anywhere in retail (0/2,408 scripts); doors are built from ActionActivatable/ParametricTranslation/ActionRotateEntity/KeyframedTranslation/constraint nodes instead
dialogue / music / checkpoint	ActionSoundVoiceOver2 (3,499 uses), ActionSoundPostEvent (1,493, ~16% of values match a music-event naming pattern), ActionAutosave (177, always saveSlot="AUTOSAVE" except one "TRANSITION")

Unused but present node classes worth knowing about

105 node classes exist in the engine's RTTI but are used by 0 retail scripts. 13 of them have an obvious used-node counterpart and are plausible candidates for custom-map work — untested, 0 retail instances, never loaded in-game: idKisculeNodeDoorNotification (a real "door" notification node that simply isn't used), idKisculeNodeActivatableNotification, idKisculeNodeActionCountAIInVolume, idKisculeNodeAlarmGlobalNotification/AlarmBrokenNotification, idKisculeNodeHudTimer, idKisculeNodeVaultCheck, idKisculeNodeGeneralUINotification, idKisculeNodeActionShowScreen, idKisculeNodeActionIngameComment, idKisculeNodeMoveAIToSceneNotification/ActionMidnightMoveAIToScene, idKisculeNodeChallengeEntity.

Open / unresolved

• Whether any of the 105 unused classes actually load and run if hand-added to a script — untested.
• The true engine-side meaning of the properties bits beyond the behavioral correlations above (no source access).
• A total-class-count discrepancy against an older report's RTTI figure remains unresolved after repeated correction attempts; it only affects "what else exists in the EXE" trivia, not any of the 205 catalogued, usable node types.

Reproduction

python tools/kiscule.py --dump                       # one-time, fills the kiscule cache
python re_probes/kisculeref/build_catalogue.py        # writes catalogue.json, ~1 MB

catalogue.json holds one entry per node type with ports, parameters, and wiring statistics, plus a list of the unused classes.