Imported from fuzzy123-ai/Steam_Godot_Prototyp (AGENTS.md). Install upstream with npx skills add fuzzy123-ai/Steam_Godot_Prototyp. Copyright stays with the author.

Steam Mouse Sync Godot 4.7 Rules

The active Godot project is:

E:/TankGame

This repository is intentionally reset to a minimal Steam networking baseline. The current product is an empty Host/Join start page plus synchronized mouse cursors over Steam. Keep Steam and networking code, and do not reintroduce old gameplay prototype systems until this baseline is verified on two machines.

Required Toolchain

Use the workspace-local Godot 4.7 editor unless an environment variable points elsewhere:

E:/Godot_With_Steam/tools/godot-4.7/Godot_v4.7-stable_win64.exe

Preferred launcher:

E:/TankGame/run-mouse-sync-godot-4.7.cmd

Console/headless launcher:

E:/TankGame/run-mouse-sync-godot-4.7-console.cmd --headless --quit-after 3

Main scene:

res://scenes/cursor_mvp/cursor_mvp.tscn

Current Baseline Scope

Keep:

• addons/godotsteam/
• addons/godot_mcp/
• scripts/globals/Online.gd
• scripts/player_data_resource.gd
• scenes/cursor_mvp/
• steam_appid.txt

Do not add gameplay, maps, vehicles, weapons, terrain, VFX, inventory, match rules, or extra assets until the two-machine Steam mouse-sync flow is proven.

Godot Authoring Rules

1. Build node-first. Use Godot scenes, nodes, resources, groups, signals, exported inspector properties, and scene instances before code-only structures.
2. Build as if a human used the Godot editor. Create named nodes, set inspector properties, wire signals, and save scenes instead of constructing large UI or scene trees in _ready().
3. Runtime add_child() is only for genuinely dynamic entities, such as remote cursor markers or future spawned gameplay objects.
4. Prefer Control containers, anchors, themes, and inspector settings for UI layout. Avoid pixel-perfect layout code unless the element is inherently dynamic.
5. Use scenes for reusable UI/components and resources for reusable data. Do not use large dictionaries when a typed Resource or named scene is clearer.
6. All tunables that a designer might adjust must be @export values or Resource fields: intervals, colors, limits, PackedScenes, NodePaths, text, and thresholds.
7. Avoid hidden coupling through deep NodePaths. Prefer signals, exported NodePaths, groups, or clearly named local child nodes.

Editor-First Level Rules

1. Node and Node2D should primarily be scene roots, structural containers, or code components when no more specific Godot node type fits.
2. Fixed visible level content must be editor-visible scene instances or designated Godot nodes, not created in _ready() or reset code.
3. Terrain should be authored as TileMapLayer. Runtime-generated terrain sprites are only acceptable as a temporary migration step with a follow-up removal plan.
4. Spawn positions must be Marker2D nodes, not hardcoded Vector2 values, once a level is promoted beyond a runtime sandbox.
5. Capture points must be Area2D scenes with a CollisionShape2D radius plus visual child nodes for outline, progress, and flag state.
6. Buildings, cover, foliage, props, HQs, and capture points belong in level scenes as named instances under editor-visible containers.
7. Runtime spawning is reserved for Units, Squads, VFX, projectiles, remote cursors, and temporary feedback objects.
8. RPC payloads remain primitives, arrays, dictionaries, or stable IDs. Never send Nodes, Resources, or scene instances over the network.

Code Size And Structure

1. Target maximum .gd file length: 180 lines.
2. Warning threshold: 220 lines. Refactor before adding more behavior.
3. Hard limit: 300 lines. Passing this requires an explicit written reason in the final response and a follow-up split plan.
4. One script owns one responsibility. No catch-all manager scripts.
5. A scene controller may orchestrate its scene, but subsystem logic belongs in smaller child scripts/resources.
6. Do not mix UI rendering, Steam transport, player registry, sync protocol, and feature logic in one file.
7. Prefer small functions with typed arguments and typed return values.

GDScript 4.7 Style

1. Use typed variables, typed arrays/dictionaries where practical, and return type annotations.
2. Use explicit type annotations in loops, for example for peer_id: int in peers:.
3. Do not define nested functions.
4. Do not mutate the root tree from _ready() unless there is a strong lifecycle reason and it is verified.
5. Use call_deferred() only when the deferred lifecycle is intentional and documented by the code shape.
6. Keep comments sparse and useful. Comment the reason for non-obvious behavior, not what the next line literally does.
7. Keep generated or edited text ASCII unless the file already intentionally uses non-ASCII.

Multiplayer And Steam Rules

1. Keep Steam/network transport in scripts/globals/Online.gd or a deliberately named networking module.
2. Gameplay and UI must not call GodotSteam directly when Online.gd can expose a clear method or signal.
3. RPC payloads must use primitives, arrays, dictionaries, or stable IDs. Do not serialize Nodes or Resources over the network.
4. Authority must be explicit. State whether host, client, or local-only code owns a behavior.
5. Preserve SteamMultiplayerPeer as the transport for the baseline.
6. Keep AppID 480 for prototype testing unless a real Steam app ID is explicitly assigned.
7. Do not log or persist Steam credentials, private tokens, unrelated machine secrets, or chat data.

Project Hygiene

1. Do not edit addons/godotsteam/ or addons/godot_mcp/ unless explicitly asked.
2. Do not edit project.godot by hand when an editor/MCP project-setting tool is available. If direct editing is necessary, keep it minimal and verify immediately.
3. Do not leave dead scenes, scripts, resources, imports, docs, or project references after removing a feature.
4. Keep README and runbooks about the actual current state, not speculative roadmaps.
5. Do not add broad refactors while implementing a narrow feature.
6. Use stable, human-readable names: HostButton, LobbyIdInput, CursorLayer, Online, PlayerData.
7. Do not create generated names like Node42, Button3, or NewScript.gd in committed project content.

Verification Rules

After any project, scene, script, addon setting, or launcher change, run:

E:/TankGame/run-mouse-sync-godot-4.7-console.cmd --headless --quit-after 3

After changing a script, also run a script check for the touched script, for example:

E:/TankGame/run-mouse-sync-godot-4.7-console.cmd --headless --check-only --script res://scenes/cursor_mvp/cursor_mvp.gd

Any ERROR: from Godot must be investigated, fixed, or explicitly reported as a blocker. Do not call a change clean while Godot is reporting errors.

Baseline Gate

Before adding the next system, prove this flow manually on two Steam accounts/machines:

1. Host creates a Steam lobby.
2. Host copies the lobby ID.
3. Client joins by pasted lobby ID.
4. Both users move the mouse.
5. Both screens show both Steam names and cursor positions updating.

Only after this gate passes should new gameplay scope be introduced.