Engine Specification

A compact specification of what the games/crpg-realm engine actually does, taken from the code. It covers the runtime layout, the dice and combat math in CombatManager.gd, saves, spells, traps, fog of war, pathfinding, the data layer and the test harness. Where the game departs from D&D 5e, this page says so. For a guided course on the same material, see the interactive eLearning app.

Table of contents

1. TOC

1. Runtime layout

Per-scene nodes. CombatManager is not an autoload. It is class_name CombatManager, added as a child node of each location scene and reached with $CombatManager. Location roots are flat Node2Ds with y_sort_enabled = true; enemies, NPCs, traps and companions are direct children of the root.

Camera. HeroPlayer.set_camera_limits() sets the Camera2D limits and turns smoothing off:

func set_camera_limits(left: int, top: int, right: int, bottom: int) -> void:
	# ...
	if camera:
		camera.limit_left = left
		camera.limit_top = top
		camera.limit_right = right
		camera.limit_bottom = bottom
		camera.position_smoothing_enabled = false
		camera.offset = camera_current_offset

Source: scripts/HeroPlayer.gd.

Real-time with pause. Space calls GameState.toggle_pause(), which sets GameState.is_game_paused and emits pause_toggled. HeroPlayer, PartyCompanion, ShadowHound and TacticalEnemy check that flag and stop processing. The Godot SceneTree itself is not paused.

2. Characters

Source: GameState.init_hero() in scripts/GameState.gd.

- Ability scores: roll_dnd_stat() rolls 4d6 and keeps the highest three.
- Modifier: get_stat_modifier(val) = floor((val - 10) / 2).
- Racial bonuses are a match on the race id, not read from races.json. Examples: human +1 to all, elf DEX +2 / INT +1, dwarf CON +2 / STR +1, halfling DEX +2 / CHA +1.
- Class HP and AC are also a match, not read from classes.json:

3. Attack rolls

Source: execute_attack() and execute_ranged_attack() in scripts/CombatManager.gd.

func roll_d20() -> int:
	return (randi() % 20) + 1

func execute_attack(attacker_name: String, attack_bonus: int, damage_dice_min: int, damage_dice_max: int, target_name: String, target_ac: int, target_pos: Vector2 = Vector2.ZERO) -> Dictionary:
	# ... advantage / disadvantage / buffs, see below
	var r1 = roll_d20()
	var r2 = roll_d20()
	var d20 = r1
	if has_adv and not has_disadv:
		d20 = max(r1, r2)
	elif has_disadv and not has_adv:
		d20 = min(r1, r2)

	var is_crit = (d20 == 20)
	if gs and gs.has_method("has_status_effect") and (gs.has_status_effect(target_name, "paralyzed") or gs.has_status_effect(target_name, "unconscious")):
		is_crit = true

	var is_fumble = (d20 == 1)
	var total_attack = d20 + attack_bonus
	var is_hit = is_crit or (not is_fumble and total_attack >= target_ac)
	var damage = 0

	if is_hit:
		damage = randi_range(damage_dice_min, damage_dice_max)
		if is_crit:
			damage += randi_range(damage_dice_min, damage_dice_max)

The rules this implements:

- Hit: d20 + attack_bonus >= target_ac. A natural 20 always hits; a natural 1 always misses.
- Damage: a uniform integer between damage_dice_min and damage_dice_max. There are no dice expressions and no separate ability modifier.
- Critical hit: the whole min–max range is rolled twice and added. In melee, a paralyzed or unconscious target is always critically hit. Ranged attacks have no automatic crit.
- Advantage / disadvantage: two d20s are always rolled; keep the higher or lower. If both apply, they cancel.

Several callers ignore the result. VillageSquare._execute_hero_strike_on_hound() then calls hound.take_damage(99) whatever was rolled, and TacticalBattle.execute_hero_attack_on_enemy() applies randi_range(16, 24) damage even on a miss. Equipped weapons and the hero's ability scores do not feed into these rolls.

Enemy attacks. TacticalEnemy rolls its own attack every 2.4 s in the ATTACK state: d20 + attack_bonus vs the target's AC (natural 20 hits, natural 1 misses), damage randi_range(damage_min, damage_max). No advantage, no crit doubling. attack_bonus, damage_min, damage_max, armor_class and max_hp are exports set per instance in the scene.

Hit points. At 0 HP the hero gets the unconscious status and GameState.check_party_defeat() runs. cure-wounds and healing-word remove unconscious when they heal.

4. Saving throws

There is no spell save DC formula. Each effect uses a fixed DC and the target's exported save modifier:

5. Spells

CombatManager.execute_cast_spell() and execute_aoe_spell() are match blocks on the spell id. Adding a spell to spells.json does nothing on its own; it needs a branch here.

Before the match, execute_cast_spell() refuses the cast if the target is invisible and the caster cannot see invisible, or if the target has sanctuary (except cure-wounds, healing-word and sanctuary).

Single-target ids handled: magic-missile, cure-wounds, healing-word, shield, sleep, mage-armor, burning-hands, thunderwave, bless, hold-person, spiritual-weapon, fireball, lightning-bolt, blizzard, stinking-cloud, haste, counterspell, find-traps, knock, invisibility, dispel-magic, sanctuary, see-invisibility, tremor-stomp, crushing-cleave, rallying-stomp.

Area ids handled by execute_aoe_spell(): fireball, burning-hands, thunderwave, lightning-bolt, blizzard, stinking-cloud, sleep, tremor-stomp, crushing-cleave, rallying-stomp.

Formulas for the most-used spells:

6. Traps

Source: resolve_trap_detection(), resolve_trap_disarm(), resolve_trap_trigger() in CombatManager.gd.

7. Fog of war

Source: scripts/FogOfWar.gd and shaders/fog_of_war.gdshader.

- 8 px cells (320x180 grid for a 2560x1440 map), red channel = explored, green = in sight.
- Vision circle around the HeroPlayer only: clear inside 240 px, smoothstep fade to 340 px.
- Shader alpha = (1 - explored) + explored (1 - in_vision) memory_darkness, with memory_darkness = 0.65 and shroud colour (0.02, 0.02, 0.04).
- Registered actors fade out when their cell is not in sight. Explored cells are cached per scene in GameState metadata.

Details: World Systems & Pathfinding.

8. Pathfinding

Source: scripts/Pathfinder.gd.

- is_line_clear() casts three rays on collision mask 1 (centre plus two offset by check_radius).
- get_nav_path() returns the target directly if the line is clear. Otherwise it builds an AStar2D over the scene's get_nav_points() -> Array[Vector2], connecting points with clear lines, and smooths the result.
- No NavigationServer2D, NavigationRegion2D or navigation mesh is used. A scene without get_nav_points() gets straight-line movement.
- Only HeroPlayer uses it. Companions follow formation slots in a straight line and slide along walls.

9. Data layer

- data/.json files are JSON arrays of objects with an id field (except game.json).
- The DataStore autoload iterates each array into a dictionary keyed by id. npcs, monsters, spells and items hold NPCData, MonsterData, SpellData and ItemData objects; the rest hold plain dictionaries.
- Runtime reads: items (GameState.get_item_data()), dialogue trees, NPC records, traps. Spells, monsters, classes and races are loaded but their numbers are not used by combat or character creation.
- Three schemas exist in schemas/; nothing validates at runtime.
- Mods: DataStoreV1.load_mods() scans res://mods/ and user://mods/; _load_single_mod() merges only a traps_file array.
- packages/crpg-builder generated the first version of these files. Do not re-run it against the game; it overwrites the hand-edited data, DataStoreV1.gd and project.godot.

!Combat in the tactical battle scene
TacticalBattle: party and enemies in real-time combat with the activity log below.*