godot-turn-system

Q: How do I install godot-turn-system?

Run npx skills add https://github.com/thedivergentai/game-dev-agentic-skills --skill godot-turn-system in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/godot-turn-system/ (personal) or .claude/skills/godot-turn-system/ (project).

by thedivergentaiAI & Agents

Expert blueprint for turn-based combat with turn order, action points, phase management, and timeline systems for strategy/RPG games. Covers speed-based initiative, interrupts, and simultaneous turns. Use when implementing turn-based combat OR tactical systems. Keywords turn-based, initiative, action points, phase, round, turn order, combat.

Installs: 357
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/thedivergentai/game-dev-agentic-skills --skill godot-turn-system

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads godot-turn-system automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

NEVER Do (Expert Anti-Patterns)

Order & Determinism

NEVER recalculate turn order every action; strictly sort once per round or ONLY when a speed-relevant stat changes to prevent O(n log n) lag.
NEVER use random tie-breaking for initiative; strictly use a secondary static attribute (Agility, ID, or persistent "luck") for deterministic replays.
NEVER modify an active turn-order queue while iterating it; strictly iterate over a duplicate() or apply queue modifications after the loop.
NEVER broadcast global turn state changes using immediate call_group(); strictly use call_group_flags(SceneTree.GROUP_CALL_DEFERRED, ...) to prevent frame spikes when notifying hundreds of units.
NEVER rely on the Node hierarchy as the source of truth; strictly use a Dictionary board state for logical grid coordinates.

Logic & Action Economy

NEVER deduct Action Points (AP) before validation; strictly call can_perform_action(cost) before applying current_ap -= cost to prevent exploits.
NEVER hardcode phase transitions (if phase == 0); strictly use an enum + match or a dedicated State Machine for Draw/Main/End phases.
NEVER emit "Turn Ended" before internal cleanup; strictly reset AP and tick status effects BEFORE signaling the next turn.
NEVER use exact floating-point equality (==) for AP checks; strictly use >= or is_equal_approx() for robust comparisons.

Tactical Grid & UI

NEVER use generic AStar2D for tile grids; strictly use AStarGrid2D for 10x faster pathfinding and native diagonal handling.
NEVER forget to call update() on AStarGrid2D after changing obstacle states; if you toggle set_point_solid(), the grid MUST refresh before the next query.
NEVER lock the main thread with while loops for input; strictly use the await keyword or signals to yield execution back to the Tree.
NEVER handle turn decisions with is_action_pressed(); strictly use is_action_just_pressed() for discrete, frame-locked menu input.
NEVER skip turn timeouts in networked games; strictly implement a server-side timer with a default "pass" action to prevent griefing. See Networked Turn Timeout golden path below.

Decision Tree — Pick a Turn Model

Need	Choose	MANDATORY script
Discrete rounds (chess / tactics / card phases)	Round + initiative queue + AP phases	turn_system_patterns.gd
Continuous gauges (FF-style ATB)	Per-actor gauge fill in `_process`	active_time_battle.gd
Timeline / CTB with interrupts & prediction	Event timeline + predictive UI	timeline_turn_manager.gd

Do NOT invent a fourth model inline. Read the matching script before coding.

Expert Components (scripts/)

turn_system_patterns.gd — Match-based phase machines, UndoRedo, AStarGrid2D board helpers.
active_time_battle.gd — ATB gauges, pause-on-ready, async action handoff.
timeline_turn_manager.gd — Timeline / CTB with interrupts and pre-visualization.
turn_predictor.gd — Simulate ATB gauges for timeline UI preview.
combat_stats_resource.gd — Deterministic damage preview Resource for hover UI.

TurnManager Autoload — Interface Contract Only

Keep the Autoload thin. Do not paste full queue math here — implement in the script chosen above.

# turn_manager.gd (AutoLoad) — contract only
extends Node
signal turn_started(combatant: Node)
signal turn_ended(combatant: Node)
signal round_ended
signal turn_timed_out(combatant: Node)  # multiplayer: server default-pass

func start_combat(participants: Array[Node]) -> void: pass
func end_turn() -> void: pass
func request_pass(combatant: Node) -> void: pass  # default action on timeout

Networked Turn Timeout (Golden Path)

Referenced from NEVER: server owns the clock; clients never decide "pass."

On turn_started, server starts a one-shot Timer / SceneTreeTimer (authoritative).
On timeout: server calls request_pass(current) (or auto-end-turn), then emits turn_timed_out.
Clients only render the countdown; never mutate the turn queue locally.
Pair with godot-multiplayer-networking for host-auth RPC.

Action Points (Contract)

func can_perform_action(cost: int) -> bool:
    return current_action_points >= cost

func perform_action(cost: int) -> bool:
    if not can_perform_action(cost):
        return false
    current_action_points -= cost
    return true

Phases: prefer enum Phase { DRAW, MAIN, END } + match, or route to godot-state-machine-advanced. Full ATB / timeline math lives in the MANDATORY scripts — do not duplicate Elite snippets here.

Deep recipes (on demand)

LLM-ignorance rule: if a general agent would not know it before reading, it lives here or in scripts/ — never delete, only move.

Topic	Reference
ATB / prediction / previews	elite-turn-patterns.md

Reference

Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing work to a peer domain — do not preload the whole lattice.

Official Documentation

Idle and Physics Processing — When turn ticks belong in _process vs _physics_process vs pure event steps.
Using signals — Turn-start / turn-end / unit-acted events without polling gauges.
Resources — Initiative/speed stats as Resources for sim and UI prediction.
Singletons (Autoload) — TurnManager ownership boundaries.
GDScript basics — await sequencing for multi-phase turns.
Object — Signal connect flags for turn bus listeners.
SceneTree — Pausing gameplay while menus resolve turn choices.
Timer — Optional realtime turn clocks without busy loops.
Tween — Animating ATB gauges and turn handoff juice.
AnimationPlayer — Action animations that must finish before the next turn.
MultiplayerAPI — Authoritative turn order in networked matches.
JSON — Deterministic turn replay / seed logs for balance labs.

Related Skills

Prerequisites

godot-project-foundations — Scene and Autoload placement for TurnManager.
godot-signal-architecture — Turn bus contracts (signals up, commands down).
godot-resource-data-patterns — Speed/initiative Resources shared with combat/UI.
godot-autoload-architecture — Lifecycle of a global turn orchestrator.

Complements

godot-state-machine-advanced — Per-unit states nested under turn phases.
godot-combat-system — Actions resolved inside a granted turn.
godot-rpg-stats — Speed/AGI feeding ATB gauges.
godot-ability-system — Cooldowns measured in turns, not wall-clock only.
godot-tweening — Gauge fill and handoff presentation.
godot-multiplayer-networking — Host-auth turn order and lockstep.

Downstream / consumers

godot-genre-action-rpg — ATB/turn hybrids in ARPG/JRPG-adjacent combat.
godot-genre-card-game — Card turns and priority windows.
godot-genre-rts — Discrete orders in strategy loops.
godot-monte-carlo-balancer — Simulate turn matrices for speed/action fairness.

Master

godot-master — Library router and mirrored module entry for turn systems.

FAQ

What does the godot-turn-system skill do?

How do I install godot-turn-system?

Run npx skills add https://github.com/thedivergentai/game-dev-agentic-skills --skill godot-turn-system in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/godot-turn-system/ (personal) or .claude/skills/godot-turn-system/ (project).

Which AI agents can use godot-turn-system?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is godot-turn-system safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains godot-turn-system?

It is published by thedivergentai in thedivergentai/game-dev-agentic-skills. It has 357 recorded installs.