summer-engine 0.0.1 → 1.0.0

package/skills/3d-lighting/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: 3d-lighting
+description: Lighting setup, environment, sky, and shadows for 3D scenes. Use when setting up a 3D scene, adding lights, configuring WorldEnvironment, or adjusting shadows.
+license: MIT
+compatibility:
+  - Cursor
+  - Claude Code
+  - Windsurf
+---
+
+# 3D Lighting for Summer Engine
+
+Set up lighting and environment for 3D scenes. Follow these patterns for outdoor and indoor setups.
+
+## Light Types
+
+| Type | Use case |
+|------|----------|
+| DirectionalLight3D | Sun, moon, outdoor primary light |
+| OmniLight3D | Point lights (lamps, torches) |
+| SpotLight3D | Flashlights, stage lights |
+
+## Basic Outdoor Setup
+
+### 1. Directional Light (Sun)
+
+```
+summer_add_node(parent="./World", type="DirectionalLight3D", name="Sun")
+summer_set_prop(path="./World/Sun", key="rotation_degrees", value="Vector3(-45, 30, 0)")
+summer_set_prop(path="./World/Sun", key="light_energy", value="1.0")
+summer_set_prop(path="./World/Sun", key="shadow_enabled", value="true")
+summer_set_prop(path="./World/Sun", key="light_color", value="Color(1, 0.95, 0.9, 1)")
+```
+
+Warm sunlight: `Color(1, 0.95, 0.9, 1)`. Cool moonlight: `Color(0.8, 0.85, 1, 1)`.
+
+### 2. WorldEnvironment (Sky + Ambient)
+
+```
+summer_add_node(parent="./World", type="WorldEnvironment", name="WorldEnvironment")
+summer_set_prop(path="./World/WorldEnvironment", key="environment", value="Environment")
+```
+
+Then configure the Environment's sub-properties. The Environment resource has:
+- `background_mode` — 2 for sky, 1 for color, 3 for canvas
+- `sky` — Sky resource (ProceduralSkyMaterial or PhysicalSkyMaterial)
+- `ambient_light_source` — AMBIENT_SOURCE_SKY or AMBIENT_SOURCE_COLOR
+- `ambient_light_color`
+- `tonemap_mode`
+
+For a simple procedural sky:
+
+```
+summer_set_resource_property(nodePath="./World/WorldEnvironment", resourceProperty="environment", subProperty="background_mode", value="2")
+```
+
+You may need to create a Sky resource and assign it. In the editor this is done via the inspector; via MCP, SetResourceProperty on nested resources may require the resource to exist first. If `environment` is "Environment", the engine creates a default. For `sky`, you might set `sky` to "ProceduralSkyMaterial" or similar—check Godot docs for the exact property chain.
+
+**Simpler path:** Use the 3d-basic template which already has a sky. Copy that structure.
+
+### 3. Fill Light (Optional)
+
+A second, weaker directional or omni for shadow fill:
+
+```
+summer_add_node(parent="./World", type="DirectionalLight3D", name="FillLight")
+summer_set_prop(path="./World/FillLight", key="rotation_degrees", value="Vector3(-30, -120, 0)")
+summer_set_prop(path="./World/FillLight", key="light_energy", value="0.3")
+summer_set_prop(path="./World/FillLight", key="shadow_enabled", value="false")
+summer_set_prop(path="./World/FillLight", key="light_color", value="Color(0.7, 0.8, 1, 1)")
+```
+
+## Indoor / Point Lights
+
+```
+summer_add_node(parent="./World", type="OmniLight3D", name="Lamp")
+summer_set_prop(path="./World/Lamp", key="position", value="Vector3(2, 3, 2)")
+summer_set_prop(path="./World/Lamp", key="light_energy", value="0.8")
+summer_set_prop(path="./World/Lamp", key="light_color", value="Color(1, 0.9, 0.7, 1)")
+summer_set_prop(path="./World/Lamp", key="omni_range", value="8")
+```
+
+## Property Reference
+
+| Property | Type | Example |
+|----------|------|---------|
+| light_energy | float | `1.0`, `1.5` |
+| light_color | Color | `"Color(1, 0.95, 0.9, 1)"` |
+| shadow_enabled | bool | `true` |
+| rotation_degrees | Vector3 | `"Vector3(-45, 30, 0)"` |
+| position | Vector3 | `"Vector3(0, 10, 0)"` |
+| omni_range | float | `10` (OmniLight3D) |
+| spot_range | float | `10` (SpotLight3D) |
+| spot_angle | float | `45` (degrees, SpotLight3D) |
+
+## Color Format
+
+Always use `Color(r, g, b, a)` with values 0.0–1.0:
+
+- Warm white: `Color(1, 0.95, 0.9, 1)`
+- Cool white: `Color(0.9, 0.95, 1, 1)`
+- Orange (torch): `Color(1, 0.6, 0.2, 1)`
+- Green (alien): `Color(0.5, 1, 0.5, 1)`

package/skills/fps-controller/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: fps-controller
+description: First-person character controller with movement, camera, and physics. Use when building an FPS game, first-person movement, or a 3D character that moves with WASD and looks with mouse.
+license: MIT
+compatibility:
+  - Cursor
+  - Claude Code
+  - Windsurf
+---
+
+# FPS Controller for Summer Engine
+
+Build a first-person character controller using CharacterBody3D, Camera3D, and proper collision. Follow this structure for reliable movement and camera behavior.
+
+## Scene Structure
+
+```
+Player (CharacterBody3D)
+├── CollisionShape3D          # Capsule for body
+├── Camera3D                  # At head height
+└── RayCast3D                 # Optional: ground detection
+```
+
+## Step-by-Step Setup via MCP
+
+### 1. Add the Player Root
+
+```
+summer_add_node(parent="./World", type="CharacterBody3D", name="Player")
+summer_set_prop(path="./World/Player", key="position", value="Vector3(0, 1, 0)")
+```
+
+### 2. Add Collision Shape
+
+```
+summer_add_node(parent="./World/Player", type="CollisionShape3D", name="CollisionShape3D")
+summer_set_prop(path="./World/Player/CollisionShape3D", key="shape", value="CapsuleShape3D")
+```
+
+Configure capsule size (radius ~0.4, height ~1.6 for typical human):
+
+```
+summer_set_resource_property(nodePath="./World/Player/CollisionShape3D", resourceProperty="shape", subProperty="radius", value="0.4")
+summer_set_resource_property(nodePath="./World/Player/CollisionShape3D", resourceProperty="shape", subProperty="height", value="1.6")
+```
+
+### 3. Add Camera
+
+```
+summer_add_node(parent="./World/Player", type="Camera3D", name="Camera3D")
+summer_set_prop(path="./World/Player/Camera3D", key="position", value="Vector3(0, 1.6, 0)")
+```
+
+Camera at y=1.6 puts the view at roughly eye level (capsule center is at 0.8, so 0.8 + 0.8 = 1.6 for eyes).
+
+### 4. InputMap Actions
+
+Create movement and look actions:
+
+```
+summer_input_map_bind(name="move_forward", events=[{type:"key", key:"W"}])
+summer_input_map_bind(name="move_back", events=[{type:"key", key:"S"}])
+summer_input_map_bind(name="move_left", events=[{type:"key", key:"A"}])
+summer_input_map_bind(name="move_right", events=[{type:"key", key:"D"}])
+summer_input_map_bind(name="jump", events=[{type:"key", key:"Space"}])
+```
+
+For mouse look, you need a script. The script will use `Input.get_vector` for movement and `InputEventMouseMotion` for look. Attach a script and implement:
+
+### 5. GDScript Pattern
+
+```gdscript
+extends CharacterBody3D
+
+@export var move_speed: float = 5.0
+@export var jump_velocity: float = 4.5
+@export var mouse_sensitivity: float = 0.002
+
+func _physics_process(_delta: float) -> void:
+    # Movement
+    var input_dir = Input.get_vector("move_left", "move_right", "move_forward", "move_back")
+    var direction = (transform.basis * Vector3(input_dir.x, 0, input_dir.y)).normalized()
+    if direction:
+        velocity.x = direction.x * move_speed
+        velocity.z = direction.z * move_speed
+    else:
+        velocity.x = move_toward(velocity.x, 0, move_speed)
+        velocity.z = move_toward(velocity.z, 0, move_speed)
+
+    # Jump
+    if is_on_floor() and Input.is_action_just_pressed("jump"):
+        velocity.y = jump_velocity
+
+    # Gravity
+    if not is_on_floor():
+        velocity.y -= 9.8 * _delta
+
+    move_and_slide()
+```
+
+For mouse look, add to a script attached to the Player or Camera:
+
+```gdscript
+func _input(event: InputEvent) -> void:
+    if event is InputEventMouseMotion:
+        rotate_y(-event.relative.x * mouse_sensitivity)
+        $Camera3D.rotate_x(-event.relative.y * mouse_sensitivity)
+        $Camera3D.rotation.x = clamp($Camera3D.rotation.x, -1.2, 1.2)
+```
+
+## Property Values (Godot Format)
+
+When using `summer_set_prop`, use these string formats:
+
+| Property | Value |
+|----------|-------|
+| position | `"Vector3(0, 1, 0)"` |
+| rotation_degrees | `"Vector3(0, 0, 0)"` |
+| shape | `"CapsuleShape3D"` |
+
+For `summer_set_resource_property` on CapsuleShape3D:
+| subProperty | value |
+|-------------|-------|
+| radius | `"0.4"` |
+| height | `"1.6"` |
+
+## Common Issues
+
+- **Falling through floor:** Ensure the floor has a StaticBody3D or similar with a CollisionShape3D
+- **Camera clipping:** If the camera goes inside geometry, enable `near` on the Camera3D or add collision exception
+- **Mouse capture:** For FPS, you typically need `Input.mouse_mode = Input.MOUSE_MODE_CAPTURED` in `_ready()` and a way to release (e.g., Escape)

package/skills/gdscript-patterns/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: gdscript-patterns
+description: Common GDScript idioms, signals, exports, and type hints. Use when writing GDScript, attaching scripts to nodes, connecting signals, or defining exported variables.
+license: MIT
+compatibility:
+  - Cursor
+  - Claude Code
+  - Windsurf
+---
+
+# GDScript Patterns for Summer Engine
+
+When writing GDScript for Summer Engine projects, follow these patterns. They align with Godot 4.x conventions and work well with MCP scene operations.
+
+## Type Hints
+
+Always use type hints for clarity and editor support:
+
+```gdscript
+var health: int = 100
+var speed: float = 5.0
+var player_name: String = ""
+var velocity: Vector3 = Vector3.ZERO
+var is_alive: bool = true
+```
+
+For nodes, use typed references:
+
+```gdscript
+@onready var collision_shape: CollisionShape3D = $CollisionShape3D
+@onready var camera: Camera3D = $Camera3D
+```
+
+## Signals
+
+Define signals at the top of the script, then emit them:
+
+```gdscript
+signal died
+signal health_changed(new_health: int)
+signal item_collected(item_name: String)
+
+func take_damage(amount: int) -> void:
+    health -= amount
+    health_changed.emit(health)
+    if health <= 0:
+        died.emit()
+```
+
+When connecting via MCP, use `summer_connect_signal` with the emitter path, signal name, receiver path, and method name. The receiver script must have the method defined.
+
+## Exports
+
+Use `@export` for inspector-editable properties:
+
+```gdscript
+@export var move_speed: float = 5.0
+@export var jump_force: float = 10.0
+@export var max_health: int = 100
+@export var can_double_jump: bool = false
+```
+
+Exports appear in the inspector. MCP can set initial values via `summer_set_prop` after the node exists, but exports are best for values the designer tweaks.
+
+## Lifecycle Methods
+
+| Method | When it runs | Use for |
+|--------|--------------|---------|
+| `_ready()` | Once when node enters tree | Initialization, getting node references |
+| `_process(delta: float)` | Every frame | UI, non-physics logic |
+| `_physics_process(delta: float)` | Every physics frame (fixed) | Movement, physics, collision |
+
+For character movement, use `_physics_process` and `move_and_slide()`.
+
+## Node Access
+
+```gdscript
+# Prefer $ for direct children
+var camera = $Camera3D
+
+# get_node() for dynamic paths
+var target = get_node("../Enemy/HealthBar")
+
+# get_parent() / get_children() when needed
+var siblings = get_parent().get_children()
+```
+
+## Common Patterns
+
+For health systems, input handling, and state machines, see [reference.md](reference.md).
+
+## MCP Integration
+
+When the AI adds a script via `summer_add_node` and attaches a script, the script path is set via `summer_set_prop(path, "script", "res://path/to/script.gd")`. The script file must exist—use `summer_write_file` to create it first.
+
+For signal connections, the receiver must have the handler method. Create the script with the method stub before calling `summer_connect_signal`.

package/skills/gdscript-patterns/reference.md

@@ -0,0 +1,55 @@
+# GDScript Patterns — Reference
+
+Detailed patterns for common game systems. Load this when implementing health, input, or state logic.
+
+## Health System
+
+```gdscript
+signal died
+
+var health: int = 100
+var max_health: int = 100
+
+func take_damage(amount: int) -> void:
+    health = maxi(0, health - amount)
+    if health <= 0:
+        died.emit()
+
+func heal(amount: int) -> void:
+    health = mini(max_health, health + amount)
+```
+
+## Input Handling
+
+Use `Input.get_axis()` for movement, `Input.is_action_just_pressed()` for discrete actions:
+
+```gdscript
+func _physics_process(_delta: float) -> void:
+    var input_dir = Input.get_vector("move_left", "move_right", "move_forward", "move_back")
+    velocity.x = input_dir.x * move_speed
+    velocity.z = input_dir.y * move_speed
+
+    if Input.is_action_just_pressed("jump"):
+        velocity.y = jump_force
+
+    move_and_slide()
+```
+
+Ensure InputMap actions exist via `summer_input_map_bind` before the game runs.
+
+## State Machine (Simple)
+
+```gdscript
+enum State { IDLE, WALKING, JUMPING, FALLING }
+var current_state: State = State.IDLE
+
+func _physics_process(delta: float) -> void:
+    match current_state:
+        State.IDLE:
+            if Input.is_action_just_pressed("jump"):
+                current_state = State.JUMPING
+            elif input_dir != Vector2.ZERO:
+                current_state = State.WALKING
+        State.WALKING:
+            # ...
+```

package/skills/scene-composition/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: scene-composition
+description: How to structure scenes, when to use sub-scenes, and node hierarchy conventions. Use when building scenes, organizing nodes, or creating reusable prefabs.
+license: MIT
+compatibility:
+  - Cursor
+  - Claude Code
+  - Windsurf
+---
+
+# Scene Composition for Summer Engine
+
+Organize scenes for clarity, reuse, and MCP compatibility. Follow these conventions when building levels, characters, and UI.
+
+## Node Hierarchy Conventions
+
+### 3D Scenes
+
+```
+World (Node3D)                    # Root or main container
+├── Camera3D                      # Main camera
+├── DirectionalLight3D            # Sun / primary light
+├── WorldEnvironment              # Sky, ambient, fog
+├── Level (Node3D)                # Level geometry
+│   ├── Ground
+│   ├── Walls
+│   └── Platforms
+├── Props (Node3D)                # Placed objects (trees, crates)
+├── Enemies (Node3D)              # Enemy instances
+└── Player                        # Player instance (or instantiated)
+```
+
+### 2D Scenes
+
+```
+Level (Node2D)
+├── TileMapLayer                  # Or TileMap
+├── Characters
+├── Props
+└── Effects
+```
+
+### UI Scenes
+
+```
+CanvasLayer or Control
+├── MarginContainer
+│   ├── VBoxContainer
+│   │   ├── Label
+│   │   ├── Button
+│   │   └── Button
+```
+
+## Parent Paths for MCP
+
+Use `./` for paths relative to the scene root:
+
+| Path | Meaning |
+|------|---------|
+| `./` | Scene root |
+| `./World` | Child named "World" of root |
+| `./World/Player` | Player under World |
+| `./World/Props/Tree1` | Tree1 under Props under World |
+
+**Never use** `/World` (absolute) or `World` (missing `./`). The engine expects `./` prefix.
+
+## When to Use Sub-Scenes
+
+**Use sub-scenes (separate .tscn files) when:**
+- The same setup appears in multiple places (player, enemy, pickup)
+- The setup has many nodes and would clutter the main scene
+- You want to edit a prefab in isolation
+
+**Use inline nodes when:**
+- The node is unique to this scene (main camera, level-specific light)
+- It's a simple one-off (single MeshInstance3D)
+
+### Creating a Sub-Scene
+
+1. Build the hierarchy in the main scene
+2. Select the root of what you want to extract
+3. Save as scene: `summer_save_scene(path="res://scenes/player.tscn")` — but note: SaveScene saves the *current* scene. To save a branch, you typically save the open scene first, then in the editor you'd use "Save Branch as Scene." MCP doesn't have a direct "save branch" op—so for now, create the sub-scene as its own file via `summer_write_file` or build it in a separate scene and save.
+4. In the main scene, add it with `summer_instantiate_scene(parent="./World", scene="res://scenes/player.tscn", name="Player")`
+
+**Practical approach:** Create reusable scenes (player.tscn, enemy.tscn) as separate scene files, then instantiate them into levels.
+
+## InstantiateScene vs AddNode
+
+| Use | Tool | Example |
+|-----|------|---------|
+| Built-in mesh (Box, Sphere) | AddNode + SetProp | `summer_add_node` type=MeshInstance3D, then `summer_set_prop` mesh=BoxMesh |
+| Existing .tscn prefab | InstantiateScene | `summer_instantiate_scene` scene=res://player.tscn |
+| Imported .glb model | ImportFromUrl then InstantiateScene | Import first, then instantiate |
+
+**Do not** use `summer_set_prop` with `mesh` for a .glb path. Use `summer_instantiate_scene` for .tscn and .glb files.
+
+## Save Conventions
+
+- Always call `summer_save_scene` after changes you want to keep
+- For new scenes: `summer_save_scene(path="res://scenes/level1.tscn")`
+- For existing scenes: `summer_save_scene` (no path, uses current scene path)
+
+## Common Mistakes
+
+1. **Wrong parent path:** `./NonExistent` fails. Ensure the parent exists before adding children.
+2. **Unnamed scene:** Saving without a path fails if the scene was never saved. Use `path` for new scenes.
+3. **Duplicate names:** Godot auto-renames (Node, Node2, etc.). Use descriptive unique names.
+4. **Mixing 2D and 3D:** Don't put Node2D under Node3D or vice versa in the same hierarchy.

package/skills/ui-basics/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: ui-basics
+description: HUD, menus, health bars, and responsive UI layout. Use when building menus, HUDs, health bars, or Control-based UI in Summer Engine.
+license: MIT
+compatibility:
+  - Cursor
+  - Claude Code
+  - Windsurf
+---
+
+# UI Basics for Summer Engine
+
+Build menus and HUDs using Godot's Control nodes. Follow these patterns for layout, buttons, and responsive design.
+
+## Control Hierarchy
+
+Use containers for layout, then add content nodes:
+
+```
+Control or CanvasLayer (root)
+└── MarginContainer
+    └── VBoxContainer (or HBoxContainer)
+        ├── Label
+        ├── Button
+        ├── Button
+        └── ProgressBar
+```
+
+## Common Containers
+
+| Container | Use |
+|-----------|-----|
+| MarginContainer | Padding from edges |
+| VBoxContainer | Stack vertically |
+| HBoxContainer | Stack horizontally |
+| CenterContainer | Center child |
+| GridContainer | Grid layout |
+
+## Basic Menu
+
+```
+summer_add_node(parent="./", type="Control", name="MainMenu")
+summer_add_node(parent="./MainMenu", type="MarginContainer", name="Margin")
+summer_set_prop(path="./MainMenu/Margin", key="anchors_preset", value="15")  # Full rect
+summer_set_prop(path="./MainMenu/Margin", key="theme_override_constants/margin_left", value="50")
+summer_set_prop(path="./MainMenu/Margin", key="theme_override_constants/margin_right", value="50")
+summer_set_prop(path="./MainMenu/Margin", key="theme_override_constants/margin_top", value="50")
+summer_set_prop(path="./MainMenu/Margin", key="theme_override_constants/margin_bottom", value="50")
+
+summer_add_node(parent="./MainMenu/Margin", type="VBoxContainer", name="VBox")
+summer_add_node(parent="./MainMenu/Margin/VBox", type="Label", name="Title")
+summer_set_prop(path="./MainMenu/Margin/VBox/Title", key="text", value="My Game")
+summer_add_node(parent="./MainMenu/Margin/VBox", type="Button", name="StartButton")
+summer_set_prop(path="./MainMenu/Margin/VBox/StartButton", key="text", value="Start Game")
+summer_add_node(parent="./MainMenu/Margin/VBox", type="Button", name="QuitButton")
+summer_set_prop(path="./MainMenu/Margin/VBox/QuitButton", key="text", value="Quit")
+```
+
+For nested theme overrides, use `summer_set_resource_property` if the property is on a resource. For `theme_override_constants/margin_left`, it may be a direct node property—check Godot docs. Some constants are set via `add_theme_constant_override`. If `summer_set_prop` accepts `theme_override_constants/margin_left`, use it; otherwise the UI may need a script or theme resource.
+
+## HUD (Health Bar)
+
+```
+summer_add_node(parent="./", type="CanvasLayer", name="HUD")
+summer_add_node(parent="./HUD", type="MarginContainer", name="TopLeft")
+summer_set_prop(path="./HUD/TopLeft", key="anchors_preset", value="1")  # Top-left
+summer_add_node(parent="./HUD/TopLeft", type="HBoxContainer", name="HealthContainer")
+summer_add_node(parent="./HUD/TopLeft/HealthContainer", type="Label", name="HealthLabel")
+summer_set_prop(path="./HUD/TopLeft/HealthContainer/HealthLabel", key="text", value="Health:")
+summer_add_node(parent="./HUD/TopLeft/HealthContainer", type="ProgressBar", name="HealthBar")
+summer_set_prop(path="./HUD/TopLeft/HealthContainer/HealthBar", key="max_value", value="100")
+summer_set_prop(path="./HUD/TopLeft/HealthContainer/HealthBar", key="value", value="100")
+summer_set_prop(path="./HUD/TopLeft/HealthContainer/HealthBar", key="size", value="Vector2(200, 20)")
+```
+
+ProgressBar uses `value` and `max_value` for the fill. Update `value` from a script when health changes.
+
+## Anchors Preset
+
+Common preset values (Godot 4):
+
+| Preset | Value | Description |
+|--------|-------|-------------|
+| Top Left | 0 | Anchor to top-left |
+| Top Right | 1 | Anchor to top-right |
+| Bottom Left | 2 | Anchor to bottom-left |
+| Bottom Right | 3 | Anchor to bottom-right |
+| Full Rect | 15 | Stretch to fill parent |
+
+Set via `summer_set_prop(path, key="anchors_preset", value="15")`.
+
+## Connecting Buttons
+
+Wire the `pressed` signal to a handler:
+
+```
+summer_connect_signal(emitter="./MainMenu/Margin/VBox/StartButton", signal="pressed", receiver="./MainMenu", method="_on_start_pressed")
+```
+
+The receiver node must have a script with `func _on_start_pressed() -> void:`.
+
+## Property Reference
+
+| Node | Property | Example |
+|------|----------|---------|
+| Label | text | `"Score: 0"` |
+| Button | text | `"Start"` |
+| ProgressBar | value | `75` |
+| ProgressBar | max_value | `100` |
+| Control | size | `"Vector2(200, 50)"` |
+| Control | anchors_preset | `15` |
+| Control | custom_minimum_size | `"Vector2(100, 30)"` |
+
+## Responsive Layout
+
+For UI that scales with window size:
+1. Use `anchors_preset` to anchor to corners or edges
+2. Use `size_flags_horizontal` and `size_flags_vertical` on children (SIZE_EXPAND_FILL, etc.)
+3. MarginContainer with percentage-based margins (may need theme or script)
+
+For simple cases, CenterContainer + fixed-size children works. For complex layouts, a Theme resource or script may be needed.

package/bin/summer.js

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-console.log("Summer Engine CLI is coming soon. Visit https://summerengine.com to get started.");
-process.exit(0);