添加 claude code game studios 到项目

.claude/rules/ai-code.md

@@ -0,0 +1,15 @@
+---
+paths:
+  - "src/ai/**"
+---
+
+# AI Code Rules
+
+- AI update budget: 2ms per frame maximum — profile to verify
+- All AI parameters must be tunable from data files (behavior tree weights, perception ranges, timers)
+- AI must be debuggable: implement visualization hooks for all AI state (paths, perception cones, decision trees)
+- AI should telegraph intentions — players need time to read and react
+- Prefer utility-based or behavior tree approaches over hard-coded if/else chains
+- Group AI must support formation, flanking, and role assignment from data
+- All AI state machines must log transitions for debugging
+- Never trust AI input from the network without validation

.claude/rules/data-files.md

@@ -0,0 +1,46 @@
+---
+paths:
+  - "assets/data/**"
+---
+
+# Data File Rules
+
+- All JSON files must be valid JSON — broken JSON blocks the entire build pipeline
+- File naming: lowercase with underscores only, following `[system]_[name].json` pattern
+- Every data file must have a documented schema (either JSON Schema or documented in the corresponding design doc)
+- Numeric values must include comments or companion docs explaining what the numbers mean
+- Use consistent key naming: camelCase for keys within JSON files
+- No orphaned data entries — every entry must be referenced by code or another data file
+- Version data files when making breaking schema changes
+- Include sensible defaults for all optional fields
+
+## Examples
+
+**Correct** naming and structure (`combat_enemies.json`):
+
+```json
+{
+  "goblin": {
+    "baseHealth": 50,
+    "baseDamage": 8,
+    "moveSpeed": 3.5,
+    "lootTable": "loot_goblin_common"
+  },
+  "goblin_chief": {
+    "baseHealth": 150,
+    "baseDamage": 20,
+    "moveSpeed": 2.8,
+    "lootTable": "loot_goblin_rare"
+  }
+}
+```
+
+**Incorrect** (`EnemyData.json`):
+
+```json
+{
+  "Goblin": { "hp": 50 }
+}
+```
+
+Violations: uppercase filename, uppercase key, no `[system]_[name]` pattern, missing required fields.

.claude/rules/design-docs.md

@@ -0,0 +1,18 @@
+---
+paths:
+  - "design/gdd/**"
+---
+
+# Design Document Rules
+
+- Every design document MUST contain these 8 sections: Overview, Player Fantasy, Detailed Rules, Formulas, Edge Cases, Dependencies, Tuning Knobs, Acceptance Criteria
+- Formulas must include variable definitions, expected value ranges, and example calculations
+- Edge cases must explicitly state what happens, not just "handle gracefully"
+- Dependencies must be bidirectional — if system A depends on B, B's doc must mention A
+- Tuning knobs must specify safe ranges and what gameplay aspect they affect
+- Acceptance criteria must be testable — a QA tester must be able to verify pass/fail
+- No hand-waving: "the system should feel good" is not a valid specification
+- Balance values must link to their source formula or rationale
+- Design documents MUST be written incrementally: create skeleton first, then fill
+  each section one at a time with user approval between sections. Write each
+  approved section to the file immediately to persist decisions and manage context

.claude/rules/engine-code.md

@@ -0,0 +1,37 @@
+---
+paths:
+  - "src/core/**"
+---
+
+# Engine Code Rules
+
+- ZERO allocations in hot paths (update loops, rendering, physics) — pre-allocate, pool, reuse
+- All engine APIs must be thread-safe OR explicitly documented as single-thread-only
+- Profile before AND after every optimization — document the measured numbers
+- Engine code must NEVER depend on gameplay code (strict dependency direction: engine <- gameplay)
+- Every public API must have usage examples in its doc comment
+- Changes to public interfaces require a deprecation period and migration guide
+- Use RAII / deterministic cleanup for all resources
+- All engine systems must support graceful degradation
+- Before writing engine API code, consult `docs/engine-reference/` for the current engine version and verify APIs against the reference docs
+
+## Examples
+
+**Correct** (zero-alloc hot path):
+
+```gdscript
+# Pre-allocated array reused each frame
+var _nearby_cache: Array[Node3D] = []
+
+func _physics_process(delta: float) -> void:
+    _nearby_cache.clear()  # Reuse, don't reallocate
+    _spatial_grid.query_radius(position, radius, _nearby_cache)
+```
+
+**Incorrect** (allocating in hot path):
+
+```gdscript
+func _physics_process(delta: float) -> void:
+    var nearby: Array[Node3D] = []  # VIOLATION: allocates every frame
+    nearby = get_tree().get_nodes_in_group("enemies")  # VIOLATION: tree query every frame
+```

.claude/rules/gameplay-code.md

@@ -0,0 +1,31 @@
+---
+paths:
+  - "src/gameplay/**"
+---
+
+# Gameplay Code Rules
+
+- ALL gameplay values MUST come from external config/data files, NEVER hardcoded
+- Use delta time for ALL time-dependent calculations (frame-rate independence)
+- NO direct references to UI code — use events/signals for cross-system communication
+- Every gameplay system must implement a clear interface
+- State machines must have explicit transition tables with documented states
+- Write unit tests for all gameplay logic — separate logic from presentation
+- Document which design doc each feature implements in code comments
+- No static singletons for game state — use dependency injection
+
+## Examples
+
+**Correct** (data-driven):
+
+```gdscript
+var damage: float = config.get_value("combat", "base_damage", 10.0)
+var speed: float = stats_resource.movement_speed * delta
+```
+
+**Incorrect** (hardcoded):
+
+```gdscript
+var damage: float = 25.0   # VIOLATION: hardcoded gameplay value
+var speed: float = 5.0      # VIOLATION: not from config, not using delta
+```

.claude/rules/narrative.md

@@ -0,0 +1,15 @@
+---
+paths:
+  - "design/narrative/**"
+---
+
+# Narrative Rules
+
+- All new lore must be cross-referenced against existing lore for contradictions
+- Every lore entry must specify canon level: Established / Provisional / Under Review
+- Character dialogue must match the voice profile defined for that character
+- World rules (what is possible/impossible) must be explicitly documented and consistent
+- Mysteries must have documented "true answers" even if players never learn them
+- Faction motivations, relationships, and power structures must be internally logical
+- All narrative text must be localization-ready: no idioms that don't translate, named placeholders for variables
+- No line of dialogue should exceed 120 characters for dialogue box constraints

.claude/rules/network-code.md

@@ -0,0 +1,15 @@
+---
+paths:
+  - "src/networking/**"
+---
+
+# Network Code Rules
+
+- Server is AUTHORITATIVE for all gameplay-critical state — never trust the client
+- All network messages must be versioned for forward/backward compatibility
+- Client predicts locally, reconciles with server — implement rollback for mispredictions
+- Handle disconnection, reconnection, and host migration gracefully
+- Rate-limit all network logging to prevent log flooding
+- All networked values must specify replication strategy: reliable/unreliable, frequency, interpolation
+- Bandwidth budget: define and track per-message-type bandwidth usage
+- Security: validate all incoming packet sizes and field ranges

.claude/rules/prototype-code.md

@@ -0,0 +1,40 @@
+---
+paths:
+  - "prototypes/**"
+---
+
+# Prototype Code Standards (Relaxed)
+
+Prototypes are throwaway code for validating ideas. Standards are intentionally
+relaxed to maximize iteration speed. The goal is learning, not production quality.
+
+## What's Allowed in Prototypes
+- Hardcoded values (no need for data-driven config)
+- Minimal or no doc comments
+- Simple architecture (no dependency injection required)
+- Singletons and global state
+- Copy-pasted code (no need for abstraction)
+- Debug output left in place
+- Placeholder art and audio
+- Quick-and-dirty solutions
+
+## What's Still Required
+- Each prototype lives in its own subdirectory: `prototypes/[name]/`
+- Every prototype MUST have a `README.md` with:
+  - What hypothesis is being tested
+  - How to run the prototype
+  - Current status (in-progress / concluded)
+  - Findings (updated when prototype concludes)
+- No production code may reference or import from `prototypes/`
+- Prototypes must not modify files outside `prototypes/`
+- Prototypes must not be deployed or shipped
+
+## When a Prototype Succeeds
+If a prototype validates a concept and the feature moves to production:
+1. The prototype code is NOT migrated directly — it is rewritten to production standards
+2. The prototype `README.md` findings inform the production design document
+3. The prototype directory is preserved for reference but never extended
+
+## Cleanup
+Concluded prototypes should be archived or deleted after findings are captured.
+Never let prototype code grow into production code through incremental "cleanup."

.claude/rules/shader-code.md

@@ -0,0 +1,44 @@
+---
+paths:
+  - "assets/shaders/**"
+---
+
+# Shader Code Standards
+
+All shader files in `assets/shaders/` must follow these standards to maintain
+visual quality, performance, and cross-platform compatibility.
+
+## Naming Conventions
+- File naming: `[type]_[category]_[name].[ext]`
+  - `spatial_env_water.gdshader` (Godot)
+  - `SG_Env_Water` (Unity Shader Graph)
+  - `M_Env_Water` (Unreal Material)
+- Use descriptive names that indicate the material purpose
+- Prefix with shader type: `spatial_`, `canvas_`, `particles_`, `post_`
+
+## Code Quality
+- All uniforms/parameters must have descriptive names and appropriate hints
+- Group related parameters (Godot: `group_uniforms`, Unity: `[Header]`, Unreal: Category)
+- Comment non-obvious calculations (especially math-heavy sections)
+- No magic numbers — use named constants or documented uniform values
+- Include authorship and purpose comment at the top of each shader file
+
+## Performance Requirements
+- Document the target platform and complexity budget for each shader
+- Use appropriate precision: `half`/`mediump` on mobile where full precision isn't needed
+- Minimize texture samples in fragment shaders
+- Avoid dynamic branching in fragment shaders — use `step()`, `mix()`, `smoothstep()`
+- No texture reads inside loops
+- Two-pass approach for blur effects (horizontal then vertical)
+
+## Cross-Platform
+- Test shaders on minimum spec target hardware
+- Provide fallback/simplified versions for lower quality tiers
+- Document which render pipeline the shader targets (Forward/Deferred, URP/HDRP, Forward+/Mobile/Compatibility)
+- Do not mix shaders from different render pipelines in the same directory
+
+## Variant Management
+- Minimize shader variants — each variant is a separate compiled shader
+- Document all keywords/variants and their purpose
+- Use feature stripping where possible to reduce build size
+- Log and monitor total variant count per shader

.claude/rules/test-standards.md

@@ -0,0 +1,42 @@
+---
+paths:
+  - "tests/**"
+---
+
+# Test Standards
+
+- Test naming: `test_[system]_[scenario]_[expected_result]` pattern
+- Every test must have a clear arrange/act/assert structure
+- Unit tests must not depend on external state (filesystem, network, database)
+- Integration tests must clean up after themselves
+- Performance tests must specify acceptable thresholds and fail if exceeded
+- Test data must be defined in the test or in dedicated fixtures, never shared mutable state
+- Mock external dependencies — tests should be fast and deterministic
+- Every bug fix must have a regression test that would have caught the original bug
+
+## Examples
+
+**Correct** (proper naming + Arrange/Act/Assert):
+
+```gdscript
+func test_health_system_take_damage_reduces_health() -> void:
+    # Arrange
+    var health := HealthComponent.new()
+    health.max_health = 100
+    health.current_health = 100
+
+    # Act
+    health.take_damage(25)
+
+    # Assert
+    assert_eq(health.current_health, 75)
+```
+
+**Incorrect**:
+
+```gdscript
+func test1() -> void:  # VIOLATION: no descriptive name
+    var h := HealthComponent.new()
+    h.take_damage(25)  # VIOLATION: no arrange step, no clear assert
+    assert_true(h.current_health < 100)  # VIOLATION: imprecise assertion
+```

.claude/rules/ui-code.md

@@ -0,0 +1,15 @@
+---
+paths:
+  - "src/ui/**"
+---
+
+# UI Code Rules
+
+- UI must NEVER own or directly modify game state — display only, use commands/events to request changes
+- All UI text must go through the localization system — no hardcoded user-facing strings
+- Support both keyboard/mouse AND gamepad input for all interactive elements
+- All animations must be skippable and respect user motion/accessibility preferences
+- UI sounds trigger through the audio event system, not directly
+- UI must never block the game thread
+- Scalable text and colorblind modes are mandatory, not optional
+- Test all screens at minimum and maximum supported resolutions