ai-game-2/AGENTS.md

AGENTS.md - AI Agent Guidelines for ai-game-2

Project Overview

This is a Godot 4.6 game project (King's Quest IV remake). The project uses:

• Godot's scene system (.tscn files)
• GDScript (.gd files) for game logic
• NavigationServer2D for pathfinding
• Custom script builder pattern for game scripts

Build & Development Commands

Running the Game

# Open in Godot editor (headless for CI)
godot --headless --path .

# Or run the exported game (if built)
./export/linux/ai-game

Single Test/Scene Testing

Godot doesn't have a traditional test framework. To test a single scene:

1. Open the project in Godot
2. Set the scene as the main scene in project.godot
3. Run with F5

Code Quality

# Godot's built-in lint (via editor)
# Tools > Analyze > Check Code

# For CI, you can run headless:
godot --headless --script-check .

Code Style Guidelines

*** CRITICAL **** When you need to create a new uid, run python make_uid.py, and it will return a unique uid. When creating scenes, at a .tscn.uid with the contents uid://

File Organization

• Scenes: scenes/kq4_XXX_room_name/
• Scripts: scenes/kq4_XXX_room_name/kq4_XXX_room_name.gd
• Resources: Visual assets copied to room folders
• Template: Use scenes/kq4_placeholder_template/ when creating new rooms

Naming Conventions

Element	Convention	Example
Scenes	kq4_XXX_description (snake_case)	kq4_010_forest_path
Nodes	PascalCase	kq4_004_ogres_cottage
Scripts	snake_case.gd	kq4_010_forest_path.gd
Variables	snake_case	appear_at_node
Constants	SCREAMING_SNAKE	const MAX_SPEED = 100
Classes	PascalCase	class_name Scene

GDScript Patterns

Class Definition

extends Node2D
class_name MyClass

# Use @export for editor-exposed variables
@export var my_var: int = 0
@export_file("*.tscn") var target_scene: String

Type Hints (Required)

var player: Node2D
var score: int = 0
var name: String = ""

func move_to(position: Vector2) -> void:
    pass

Signals

signal my_signal(value: int)

# Connecting
some_node.my_signal.connect(_on_my_signal)

# Or in editor-created connections:
[connection signal="interacted" from="transition_piece" to="." method="_on_interacted"]

Scene Structure (.tscn)

Header

[gd_scene format=3 uid="uid://xxxxx"]

[ext_resource type="Script" uid="uid://xxxxx" path="res://path/to/script.gd" id="1_abc"]
[ext_resource type="Texture2D" uid="uid://xxxxx" path="res://path/to/texture.png" id="2_abc"]
[ext_resource type="PackedScene" uid="uid://xxxxx" path="res://TransitionPiece.tscn" id="3_abc"]

Node Hierarchy

• Use meaningful node names
• Prefix private nodes with underscore when appropriate
• Use unique_id= for editor-managed nodes

Transition Pieces

When adding exits to rooms:

[node name="kq4_004_ogres_cottage" parent="." instance=ExtResource("4_abc")]
position = Vector2(910, -213)
polygon = PackedVector2Array(...)
appear_at_node = "kq4_010_forest_path"  # Node name in target scene
target = "uid://xxxxxxxx"                  # Scene UID
label = "Ogre's Cottage"

[node name="entrance" parent="kq4_004_ogres_cottage" index="0"]
position = Vector2(163, 598)

[node name="exit" parent="kq4_004_ogres_cottage" index="1"]
position = Vector2(159, 459)

[connection signal="interacted" from="kq4_004_ogres_cottage" to="." method="_on_ogres_cottage_interacted"]

[editable path="kq4_004_ogres_cottage"]

Error Handling

• Use push_error() for critical issues
• Use push_warning() for non-critical issues
• Always check load() returns with if resource: before using
• Use @onready for node references (handles load order)

Room Creation Process

1. Copy template: cp -r scenes/kq4_placeholder_template scenes/kq4_XXX_name
2. Rename files: Update .gd and .tscn filenames
3. Copy visual: Copy pic_XXX_visual.png from decompile
4. Update .tscn:
   • Remove hardcoded UIDs (let Godot generate)
   • Add transition pieces for cardinal directions
   • Set labels to human-readable names
5. Update .gd: Add signal handlers for connected rooms
6. Generate UIDs: Let Godot import, then create .uid files
7. Wire transitions: Update target fields with real UIDs

Import Files

When creating new room textures, create .import files:

[remap]
importer="texture"
type="CompressedTexture2D"
uid="uid://xxxxxxxx"
path="res://.godot/imported/image.png-xxx.ctex"

[deps]
source_file="res://scenes/room_name/image.png"
dest_files=[...]

[params]
compress/mode=0
# ... standard Godot texture params

What NOT to Do

• Don't commit secrets/keys (use .gitignore)
• Don't use print() for debugging in production (use push_warning())
• Don't hardcode paths - use res:// relative paths
• Don't modify project.godot unless necessary
• Don't delete the meadow-2 scene (unrelated to KQ4 rooms)

File Extensions to Know

Extension	Purpose
.gd	GDScript source
.tscn	Godot scene
.tres	Godot resource
.import	Import configuration
.uid	Resource UID cache
.md	Room documentation (in kq4-sierra-decompile)

Room Specs Reference

Room specifications are in kq4-sierra-decompile/rooms/kq4-XXX-name/. Each room has:

• kq4-XXX-name.md - Technical documentation
• pic_XXX_visual.png - Background image
• pic_XXX_control.png - Control/hitbox areas
• pic_XXX_priority.png - Priority/z-ordering

Key Classes

• Scene (Scene.gd) - Base room class with navigation
• TransitionPiece (TransitionPiece.gd) - Exit/entry points
• GameScript (GameScript.gd) - Script builder for cutscenes
• Ego (Ego.gd) - Player character

Common Patterns

Navigation

var path = NavigationServer2D.map_get_path(map, start, end, true)

Pathfinding Movement

scene.start_main_script(scene.ScriptBuilder.init(scene.ScriptBuilder.walk_path(ego, path)).build())

Scene Transitions

func _on_exit_interacted() -> void:
    $target_scene.default_script(self)