@jarrodmedrano/claude-skills 1.0.3 → 1.0.4

package/.claude/skills/godot/references/godot4-physics-api.md

@@ -0,0 +1,302 @@
+# Godot 4.x Physics API Quick Reference
+
+This reference covers common physics operations in Godot 4.x, focusing on correct API usage and common patterns.
+
+## Raycasting
+
+### PhysicsRayQueryParameters3D (Correct Class Name)
+
+**Important**: The class is `PhysicsRayQueryParameters3D`, NOT `PhysicsRayQuery3D`.
+
+### Basic Raycast Setup
+
+```gdscript
+# Get the physics space
+var space_state = get_world_3d().direct_space_state
+
+# Create ray query parameters
+var query = PhysicsRayQueryParameters3D.create(from_position, to_position)
+
+# Optional: Exclude specific bodies
+query.exclude = [self, other_body]
+
+# Optional: Set collision mask (which layers to check)
+query.collision_mask = 1  # Layer 1 only
+query.collision_mask = 0b0011  # Layers 1 and 2
+
+# Perform the raycast
+var result = space_state.intersect_ray(query)
+
+# Check if hit something
+if result:
+    var hit_object = result.collider
+    var hit_position = result.position
+    var hit_normal = result.normal
+```
+
+### Common Raycast Patterns
+
+**Camera-based raycast (first-person interaction):**
+```gdscript
+var camera = get_viewport().get_camera_3d()
+var from = camera.global_position
+var to = from + (-camera.global_transform.basis.z * range)
+
+var query = PhysicsRayQueryParameters3D.create(from, to)
+query.exclude = [player]
+var result = space_state.intersect_ray(query)
+```
+
+**Downward raycast (ground detection):**
+```gdscript
+var from = global_position
+var to = global_position + Vector3.DOWN * 10.0
+
+var query = PhysicsRayQueryParameters3D.create(from, to)
+var result = space_state.intersect_ray(query)
+
+if result:
+    var distance_to_ground = from.distance_to(result.position)
+```
+
+**Line-of-sight check:**
+```gdscript
+func has_line_of_sight(target: Node3D) -> bool:
+    var space_state = get_world_3d().direct_space_state
+    var from = global_position
+    var to = target.global_position
+
+    var query = PhysicsRayQueryParameters3D.create(from, to)
+    query.exclude = [self, target]
+
+    var result = space_state.intersect_ray(query)
+    return not result  # True if nothing blocking
+```
+
+## Shape Queries
+
+### PhysicsShapeQueryParameters3D
+
+For checking if a shape overlaps with objects (useful for area attacks, detection zones).
+
+```gdscript
+# Create shape query
+var query = PhysicsShapeQueryParameters3D.new()
+
+# Set the shape (sphere, box, capsule, etc.)
+var sphere = SphereShape3D.new()
+sphere.radius = 2.0
+query.shape = sphere
+
+# Set transform (position and rotation)
+query.transform = Transform3D(Basis(), global_position)
+
+# Optional: collision mask
+query.collision_mask = 1
+
+# Perform query
+var space_state = get_world_3d().direct_space_state
+var results = space_state.intersect_shape(query)
+
+# Iterate results
+for result in results:
+    var collider = result.collider
+    # Do something with each overlapping object
+```
+
+### Common Shape Query Patterns
+
+**Area attack (sphere around player):**
+```gdscript
+func perform_area_attack(radius: float, damage: float):
+    var query = PhysicsShapeQueryParameters3D.new()
+    var sphere = SphereShape3D.new()
+    sphere.radius = radius
+    query.shape = sphere
+    query.transform = Transform3D(Basis(), global_position)
+    query.collision_mask = 2  # Enemies layer
+
+    var space_state = get_world_3d().direct_space_state
+    var results = space_state.intersect_shape(query)
+
+    for result in results:
+        if result.collider.has_method("take_damage"):
+            result.collider.take_damage(damage)
+```
+
+**Cone detection (enemy field of view):**
+```gdscript
+# Use multiple raycasts in a cone pattern
+func detect_in_cone(angle_degrees: float, range: float) -> Array:
+    var detected = []
+    var rays = 5  # Number of rays in cone
+
+    for i in range(rays):
+        var angle = -angle_degrees/2 + (angle_degrees / (rays-1)) * i
+        var direction = global_transform.basis.z.rotated(Vector3.UP, deg_to_rad(angle))
+
+        var from = global_position
+        var to = from + direction * range
+
+        var query = PhysicsRayQueryParameters3D.create(from, to)
+        var result = space_state.intersect_ray(query)
+
+        if result:
+            detected.append(result.collider)
+
+    return detected
+```
+
+## Collision Layers and Masks
+
+Understanding layers is critical for efficient physics.
+
+### Layer Setup
+
+```gdscript
+# In project settings, name your layers:
+# Layer 1: World (walls, floors)
+# Layer 2: Player
+# Layer 3: Enemies
+# Layer 4: Projectiles
+# Layer 5: Interactables
+
+# Set what layers an object is ON
+collision_layer = 0b00010  # Layer 2 (Player)
+
+# Set what layers an object can COLLIDE WITH
+collision_mask = 0b00101  # Layers 1 (World) and 3 (Enemies)
+```
+
+### Common Layer Patterns
+
+**Player should collide with world and enemies:**
+```gdscript
+# Player
+collision_layer = 0b00010  # Layer 2
+collision_mask = 0b00101   # Layers 1 (world) and 3 (enemies)
+```
+
+**Enemy projectile should hit player but not other enemies:**
+```gdscript
+# Enemy Projectile
+collision_layer = 0b01000   # Layer 4
+collision_mask = 0b00011    # Layers 1 (world) and 2 (player)
+```
+
+**Interaction raycast should only hit interactables:**
+```gdscript
+var query = PhysicsRayQueryParameters3D.create(from, to)
+query.collision_mask = 0b10000  # Layer 5 (interactables) only
+```
+
+## Area3D vs RigidBody3D vs StaticBody3D vs CharacterBody3D
+
+### When to Use Each
+
+**StaticBody3D**
+- Non-moving collision objects (walls, floors, obstacles)
+- Cannot be moved by physics
+- Very efficient
+
+**CharacterBody3D**
+- Player characters, NPCs with custom movement
+- Controlled by code, not physics engine
+- Has `move_and_slide()` for smooth movement
+- Use for anything you want direct control over
+
+**RigidBody3D**
+- Objects controlled by physics (crates, barrels, ragdolls)
+- Affected by gravity, forces, collisions
+- Good for destructible/pushable objects
+
+**Area3D**
+- Trigger zones (doesn't block movement)
+- Detection volumes (pickup radius, damage zones)
+- Cannot collide physically, only detect overlaps
+
+### Common Patterns
+
+**Damage zone (Area3D):**
+```gdscript
+extends Area3D
+
+signal body_damaged(body: Node3D, damage: float)
+
+@export var damage_per_second: float = 10.0
+
+func _ready():
+    body_entered.connect(_on_body_entered)
+    body_exited.connect(_on_body_exited)
+
+var bodies_inside: Array[Node3D] = []
+
+func _on_body_entered(body: Node3D):
+    bodies_inside.append(body)
+
+func _on_body_exited(body: Node3D):
+    bodies_inside.erase(body)
+
+func _process(delta: float):
+    for body in bodies_inside:
+        if body.has_method("take_damage"):
+            body.take_damage(damage_per_second * delta)
+            body_damaged.emit(body, damage_per_second * delta)
+```
+
+**Pickup detection (Area3D child of player):**
+```gdscript
+# As child of CharacterBody3D (player)
+extends Area3D
+
+func _ready():
+    collision_layer = 0  # Not on any layer
+    collision_mask = 0b10000  # Only detect interactables
+
+    body_entered.connect(_on_pickup_entered)
+
+func _on_pickup_entered(body: Node3D):
+    if body.has_method("pickup"):
+        body.pickup(get_parent())  # Pass player to pickup
+```
+
+## Performance Tips
+
+1. **Use collision layers efficiently** - Don't check unnecessary layers
+2. **Limit raycast distance** - Shorter rays are faster
+3. **Cache space_state** - Don't call `get_world_3d().direct_space_state` every frame if possible
+4. **Use Areas for detection** - More efficient than frequent raycasts
+5. **Exclude irrelevant bodies** - Use `query.exclude` to skip known objects
+
+## Common Gotchas
+
+1. **Wrong class name**: It's `PhysicsRayQueryParameters3D`, not `PhysicsRayQuery3D`
+2. **Forgetting collision mask**: Raycast won't hit anything if mask is 0
+3. **Self-collision**: Always exclude `self` from queries
+4. **Result dictionary**: Check `if result:` before accessing `result.collider`
+5. **Global vs local positions**: Raycasts use global coordinates
+6. **Basis direction**: `-transform.basis.z` is forward, not `transform.basis.z`
+
+## Debugging Physics
+
+```gdscript
+# Visualize raycasts in editor
+func _draw_debug_ray(from: Vector3, to: Vector3, hit: bool):
+    var immediate = ImmediateMesh.new()
+    var material = StandardMaterial3D.new()
+    material.albedo_color = Color.RED if hit else Color.GREEN
+    material.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED
+
+    # Add debug line drawing here
+    # (Use MeshInstance3D with ImmediateMesh for runtime visualization)
+
+# Print collision layers
+func debug_print_layers():
+    print("collision_layer: ", collision_layer, " (binary: ", String.num_int64(collision_layer, 2), ")")
+    print("collision_mask: ", collision_mask, " (binary: ", String.num_int64(collision_mask, 2), ")")
+```
+
+## Further Reading
+
+- Official Godot 4 Physics Docs: https://docs.godotengine.org/en/stable/tutorials/physics/
+- Understanding collision layers: https://docs.godotengine.org/en/stable/tutorials/physics/physics_introduction.html#collision-layers-and-masks

package/.claude/skills/godot/scripts/validate_tres.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""
+Validates Godot .tres (resource) files for common syntax errors.
+
+Common mistakes this catches:
+- Using preload() instead of ExtResource()
+- Using GDScript syntax (var, const, func) in resource files
+- Missing ExtResource declarations
+- Incorrect array type syntax
+"""
+
+import sys
+import re
+from pathlib import Path
+
+
+class TresValidator:
+    def __init__(self, file_path):
+        self.file_path = Path(file_path)
+        self.errors = []
+        self.warnings = []
+
+    def validate(self):
+        """Run all validation checks."""
+        if not self.file_path.exists():
+            self.errors.append(f"File not found: {self.file_path}")
+            return False
+
+        content = self.file_path.read_text()
+
+        self._check_preload_usage(content)
+        self._check_gdscript_keywords(content)
+        self._check_array_syntax(content)
+        self._check_resource_references(content)
+
+        return len(self.errors) == 0
+
+    def _check_preload_usage(self, content):
+        """Check for illegal preload() usage."""
+        preload_pattern = r'preload\s*\('
+        matches = list(re.finditer(preload_pattern, content, re.IGNORECASE))
+
+        for match in matches:
+            line_num = content[:match.start()].count('\n') + 1
+            self.errors.append(
+                f"Line {line_num}: Found 'preload()' - use ExtResource() instead in .tres files"
+            )
+
+    def _check_gdscript_keywords(self, content):
+        """Check for GDScript keywords that shouldn't be in .tres files."""
+        # Split into lines and check each
+        lines = content.split('\n')
+        keywords = ['var ', 'const ', 'func ', 'class_name ', 'extends ']
+
+        for i, line in enumerate(lines, 1):
+            # Skip comments
+            if line.strip().startswith('#'):
+                continue
+
+            for keyword in keywords:
+                if keyword in line and not line.strip().startswith('['):
+                    self.errors.append(
+                        f"Line {i}: Found GDScript keyword '{keyword.strip()}' - "
+                        f"not allowed in .tres files"
+                    )
+
+    def _check_array_syntax(self, content):
+        """Check for proper typed array syntax."""
+        # Look for array assignments without type
+        untyped_array_pattern = r'=\s*\[[^\]]*\]'
+        lines = content.split('\n')
+
+        for i, line in enumerate(lines, 1):
+            # Skip resource headers
+            if line.strip().startswith('[') and line.strip().endswith(']'):
+                continue
+
+            if re.search(untyped_array_pattern, line):
+                # Check if it's preceded by Array[Type]
+                if 'Array[' not in line:
+                    self.warnings.append(
+                        f"Line {i}: Array may need type specification - "
+                        f"use Array[Type]([...]) syntax"
+                    )
+
+    def _check_resource_references(self, content):
+        """Check that ExtResource IDs are declared."""
+        # Find all ExtResource usages
+        usage_pattern = r'ExtResource\s*\(\s*"([^"]+)"\s*\)'
+        usages = re.findall(usage_pattern, content)
+
+        # Find all ExtResource declarations
+        decl_pattern = r'\[ext_resource[^\]]*id\s*=\s*"([^"]+)"'
+        declarations = re.findall(decl_pattern, content)
+
+        # Check for undefined references
+        for resource_id in set(usages):
+            if resource_id not in declarations:
+                self.errors.append(
+                    f"ExtResource('{resource_id}') used but not declared - "
+                    f"add [ext_resource ...] declaration"
+                )
+
+    def print_results(self):
+        """Print validation results."""
+        print(f"\n{'='*60}")
+        print(f"Validating: {self.file_path}")
+        print(f"{'='*60}\n")
+
+        if self.errors:
+            print("❌ ERRORS:")
+            for error in self.errors:
+                print(f"  • {error}")
+            print()
+
+        if self.warnings:
+            print("⚠️  WARNINGS:")
+            for warning in self.warnings:
+                print(f"  • {warning}")
+            print()
+
+        if not self.errors and not self.warnings:
+            print("✅ No issues found!\n")
+        elif not self.errors:
+            print("✅ No errors (only warnings)\n")
+        else:
+            print(f"❌ Found {len(self.errors)} error(s)\n")
+
+        return len(self.errors) == 0
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: validate_tres.py <file.tres>")
+        sys.exit(1)
+
+    validator = TresValidator(sys.argv[1])
+    validator.validate()
+    success = validator.print_results()
+
+    sys.exit(0 if success else 1)
+
+
+if __name__ == "__main__":
+    main()

package/.claude/skills/godot/scripts/validate_tscn.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""
+Validates Godot .tscn (scene) files for common structural errors.
+
+Common mistakes this catches:
+- Missing ExtResource declarations for used resources
+- Invalid parent references
+- Malformed node entries
+- UID format issues
+"""
+
+import sys
+import re
+from pathlib import Path
+
+
+class TscnValidator:
+    def __init__(self, file_path):
+        self.file_path = Path(file_path)
+        self.errors = []
+        self.warnings = []
+
+    def validate(self):
+        """Run all validation checks."""
+        if not self.file_path.exists():
+            self.errors.append(f"File not found: {self.file_path}")
+            return False
+
+        content = self.file_path.read_text()
+
+        self._check_header(content)
+        self._check_resource_references(content)
+        self._check_node_structure(content)
+        self._check_parent_references(content)
+
+        return len(self.errors) == 0
+
+    def _check_header(self, content):
+        """Check for valid scene file header."""
+        lines = content.split('\n')
+        if not lines:
+            self.errors.append("Empty file")
+            return
+
+        first_line = lines[0].strip()
+        if not first_line.startswith('[gd_scene'):
+            self.errors.append(
+                "Invalid header - should start with [gd_scene load_steps=N format=3 ...]"
+            )
+
+        # Check for UID
+        if 'uid=' not in first_line:
+            self.warnings.append("Missing UID in header - may cause reference issues")
+
+    def _check_resource_references(self, content):
+        """Check that all ExtResource and SubResource references are declared."""
+        # Find all ExtResource usages
+        ext_usage_pattern = r'ExtResource\s*\(\s*"([^"]+)"\s*\)'
+        ext_usages = re.findall(ext_usage_pattern, content)
+
+        # Find all ExtResource declarations
+        ext_decl_pattern = r'\[ext_resource[^\]]*id\s*=\s*"([^"]+)"'
+        ext_declarations = re.findall(ext_decl_pattern, content)
+
+        # Check for undefined ExtResource references
+        for resource_id in set(ext_usages):
+            if resource_id not in ext_declarations:
+                self.errors.append(
+                    f"ExtResource('{resource_id}') used but not declared"
+                )
+
+        # Find all SubResource usages
+        sub_usage_pattern = r'SubResource\s*\(\s*"([^"]+)"\s*\)'
+        sub_usages = re.findall(sub_usage_pattern, content)
+
+        # Find all SubResource declarations
+        sub_decl_pattern = r'\[sub_resource[^\]]*id\s*=\s*"([^"]+)"'
+        sub_declarations = re.findall(sub_decl_pattern, content)
+
+        # Check for undefined SubResource references
+        for resource_id in set(sub_usages):
+            if resource_id not in sub_declarations:
+                self.errors.append(
+                    f"SubResource('{resource_id}') used but not declared"
+                )
+
+    def _check_node_structure(self, content):
+        """Check for valid node entries."""
+        lines = content.split('\n')
+        node_pattern = r'^\[node\s+name="([^"]+)"'
+
+        for i, line in enumerate(lines, 1):
+            match = re.match(node_pattern, line)
+            if match:
+                # Check if node has required attributes
+                if 'type=' not in line and 'instance=' not in line and 'parent=' in line:
+                    # Child nodes without type or instance might be invalid
+                    self.warnings.append(
+                        f"Line {i}: Node '{match.group(1)}' has parent but no type or instance"
+                    )
+
+    def _check_parent_references(self, content):
+        """Check that parent references are valid."""
+        lines = content.split('\n')
+
+        # Collect all node names
+        node_pattern = r'\[node\s+name="([^"]+)"'
+        nodes = []
+
+        for line in lines:
+            match = re.match(node_pattern, line)
+            if match:
+                nodes.append(match.group(1))
+
+        # Check parent references
+        parent_pattern = r'parent="([^"]+)"'
+        for i, line in enumerate(lines, 1):
+            match = re.search(parent_pattern, line)
+            if match:
+                parent = match.group(1)
+                # "." is valid (root), others should exist
+                if parent != "." and '/' not in parent:
+                    # Simple parent reference
+                    if parent not in nodes:
+                        self.warnings.append(
+                            f"Line {i}: Parent '{parent}' not found in scene"
+                        )
+
+    def print_results(self):
+        """Print validation results."""
+        print(f"\n{'='*60}")
+        print(f"Validating: {self.file_path}")
+        print(f"{'='*60}\n")
+
+        if self.errors:
+            print("❌ ERRORS:")
+            for error in self.errors:
+                print(f"  • {error}")
+            print()
+
+        if self.warnings:
+            print("⚠️  WARNINGS:")
+            for warning in self.warnings:
+                print(f"  • {warning}")
+            print()
+
+        if not self.errors and not self.warnings:
+            print("✅ No issues found!\n")
+        elif not self.errors:
+            print("✅ No errors (only warnings)\n")
+        else:
+            print(f"❌ Found {len(self.errors)} error(s)\n")
+
+        return len(self.errors) == 0
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: validate_tscn.py <file.tscn>")
+        sys.exit(1)
+
+    validator = TscnValidator(sys.argv[1])
+    validator.validate()
+    success = validator.print_results()
+
+    sys.exit(0 if success else 1)
+
+
+if __name__ == "__main__":
+    main()