Merge 5a2e21c66b into 5d4837d2d7

ASSET_ORGANIZATION_GUIDE.md

@@ -0,0 +1,204 @@
+# 📦 ASSET ORGANIZATION GUIDE
+
+This guide will help you organize your downloaded Kenney assets into the correct folders.
+
+---
+
+## 🎯 QUICK START
+
+1. **Check the folder structure** - All folders have been created for you!
+2. **Read the README.md** in each folder to understand what goes there
+3. **Drag and drop** your Kenney assets into the appropriate folders
+4. **Commit and push** to Git when done
+5. **Let me know** and I'll verify everything loaded correctly!
+
+---
+
+## 📂 FOLDER STRUCTURE OVERVIEW
+
+```
+Starter-Kit-3D-Platformer/
+│
+├── models/                          # 3D Models (.glb, .gltf)
+│   ├── characters/
+│   │   ├── player/                 # Player model (already exists)
+│   │   └── enemies/                # 📖 Enemy models → Read README
+│   │
+│   ├── platforms/                   # 📖 Platform models → Read README
+│   ├── collectibles/
+│   │   └── fruits/                 # 📖 Fruit models (Food Kit) → Read README
+│   │
+│   ├── obstacles/                   # 📖 Crates, spikes, springs → Read README
+│   └── environment/
+│       ├── jungle/                 # 📖 Trees, rocks, ruins → Read README
+│       └── props/                  # 📖 Checkpoints, flags → Read README
+│
+├── sprites/                         # 2D Images (.png)
+│   ├── ui/
+│   │   ├── icons/                  # 📖 Life, fruit, star icons → Read README
+│   │   ├── touch_controls/         # 📖 Mobile controls → Read README
+│   │   └── panels/                 # 📖 UI backgrounds → Read README
+│   └── effects/                    # Particle sprites
+│
+├── sounds/                          # Audio Files (.ogg)
+│   ├── player/                     # 📖 Spin, hurt, death → Read README
+│   ├── collectibles/               # 📖 Fruit collect, life gain → Read README
+│   ├── obstacles/                  # 📖 Crate break, spring → Read README
+│   ├── enemies/                    # 📖 Enemy sounds → Read README
+│   ├── ui/                         # 📖 Button clicks → Read README
+│   ├── level/                      # 📖 Checkpoint, victory → Read README
+│   └── music/                      # 📖 Background music (optional) → Read README
+│
+├── objects/                         # Godot Scenes (.tscn)
+│   └── (We'll create these together after assets are imported)
+│
+├── scenes/                          # Game Scenes
+│   └── (We'll create these together)
+│
+└── scripts/                         # GDScript Files
+    └── (We'll create these together)
+```
+
+---
+
+## ✅ ASSET CHECKLIST
+
+### 🔴 HIGH PRIORITY (Need these to start):
+
+#### From **FOOD KIT**:
+- [ ] 3-5 fruit models (.glb) → `models/collectibles/fruits/`
+  - apple.glb, orange.glb, banana.glb, etc.
+
+#### From **PLATFORMER KIT**:
+- [ ] Crate models (.glb) → `models/obstacles/`
+  - crate.glb (basic wooden crate)
+- [ ] Spring/bounce pad (.glb) → `models/obstacles/`
+  - spring_pad.glb or spring.glb
+- [ ] Spike trap (.glb) → `models/obstacles/`
+  - spike.glb or spike_trap.glb
+- [ ] Checkpoint model (.glb) → `models/environment/props/`
+  - checkpoint.glb or flag_checkpoint.glb
+
+#### From **UI PACK** (or Game Icons):
+- [ ] Life/heart icon (.png) → `sprites/ui/icons/`
+  - icon_life.png or icon_heart.png
+- [ ] Fruit icon (.png) → `sprites/ui/icons/`
+  - icon_fruit.png
+- [ ] Star icon (.png) → `sprites/ui/icons/`
+  - icon_star.png
+- [ ] Pause button (.png) → `sprites/ui/icons/`
+  - button_pause.png
+
+---
+
+### 🟡 MEDIUM PRIORITY (Good to have):
+
+#### From **CHARACTER PACK**:
+- [ ] 2-3 enemy models (.glb) → `models/characters/enemies/`
+  - Rename to: enemy_patroller.glb, enemy_spinner.glb
+
+#### From **PLATFORMER KIT**:
+- [ ] Additional platform variants → `models/platforms/`
+- [ ] More obstacle types → `models/obstacles/`
+
+#### From **NATURE KIT** (if downloaded):
+- [ ] Trees, rocks, plants → `models/environment/jungle/`
+
+---
+
+### 🟢 LOW PRIORITY (Polish & optional):
+
+#### Sound Effects:
+- [ ] Spin attack sound → `sounds/player/`
+- [ ] Hurt/death sounds → `sounds/player/`
+- [ ] Fruit collect sound → `sounds/collectibles/`
+- [ ] Checkpoint sound → `sounds/level/`
+- [ ] Victory fanfare → `sounds/level/`
+
+#### UI Assets:
+- [ ] Touch control sprites → `sprites/ui/touch_controls/`
+- [ ] Panel backgrounds → `sprites/ui/panels/`
+
+#### Environment:
+- [ ] Decorative props → `models/environment/`
+
+---
+
+## 🔧 GODOT IMPORT SETTINGS (AFTER copying files)
+
+Once you've copied assets into folders:
+
+1. **Open Godot 4.5**
+2. **Let it auto-import** (may take a few minutes)
+3. **Check 3D models**:
+   - Click on a `.glb` file in FileSystem
+   - Check "Import" tab
+   - Ensure scale looks correct (usually 1.0)
+4. **Check textures**:
+   - Icons should be "Lossy" or "Lossless" compression
+   - Enable "Mipmaps" for 3D textures
+5. **Check audio**:
+   - Format: OggVorbis
+   - Loop: OFF (for sound effects), ON (for music)
+
+---
+
+## 📝 FILE NAMING TIPS
+
+When copying files from Kenney packs, rename them to be clear:
+
+### Good naming:
+- `apple.glb` ✓
+- `crate.glb` ✓
+- `enemy_patroller.glb` ✓
+- `icon_life.png` ✓
+
+### Bad naming:
+- `food_03.glb` ✗ (unclear)
+- `obj_45.glb` ✗ (unclear)
+- `asset.glb` ✗ (too generic)
+
+**Use lowercase with underscores!**
+
+---
+
+## 🚀 NEXT STEPS
+
+### After organizing assets:
+
+1. **Commit to Git:**
+   ```bash
+   git add models/ sprites/ sounds/
+   git commit -m "Add Kenney asset packs (Platformer, Food, Character, UI)"
+   git push -u origin claude/godot-crash-platformer-011CUjb3gBpfQk8UcwrEPXaX
+   ```
+
+2. **Tell Claude:** "Assets synced!"
+
+3. **Claude will:**
+   - Verify all assets imported correctly
+   - Start building game systems
+   - Create scene files (.tscn) for each asset
+   - Build the complete Level 1 experience!
+
+---
+
+## ❓ QUESTIONS?
+
+- **Don't have a specific asset?** → Skip it! We can work around it or use placeholders
+- **Unsure which file to use?** → Check the README.md in each folder
+- **Multiple variants of same asset?** → Pick one, or include all variants!
+- **Can't find Kenney sounds?** → We can use free sounds from freesound.org later
+
+---
+
+## 📄 LICENSE & ATTRIBUTION
+
+All Kenney assets are **CC0 1.0 Universal (Public Domain)**
+Source: https://kenney.nl/
+
+You can use them freely in your game, commercial or not!
+
+---
+
+**Ready to start? Open your Kenney asset downloads and start dragging files into the folders!** 🎮

models/characters/enemies/README.md

@@ -0,0 +1,28 @@
+# Enemy Character Models
+
+**Source:** Kenney Animated Characters or Character Pack
+
+## What to put here:
+
+Pick 2-3 simple enemy models from the Character Pack:
+
+### Recommended:
+- `enemy_patroller.glb` - Basic enemy that walks back and forth
+- `enemy_spinner.glb` - Spinning/rotating enemy
+- `enemy_jumper.glb` - Hopping enemy (optional)
+
+### Good Enemy Types:
+- Small blob/slime creatures
+- Simple robots
+- Generic monsters
+- Animal characters
+
+## Naming Convention:
+Rename downloaded models to:
+- `enemy_TYPE.glb` (e.g., `enemy_blob.glb`, `enemy_robot.glb`)
+
+This keeps naming consistent and clear!
+
+## Animation:
+If the models have animations, Godot will auto-import them.
+We'll set up simple patrol AI for these enemies.

models/collectibles/fruits/README.md

@@ -0,0 +1,18 @@
+# Fruit Models (Collectibles)
+
+**Source:** Kenney Food Kit (https://kenney.nl/assets/food-kit)
+
+## What to put here:
+- `apple.glb` - Main collectible fruit
+- `orange.glb` - Alternative fruit
+- `banana.glb` - Alternative fruit
+- `cherry.glb` - Small bonus fruit (worth more points)
+- `watermelon.glb` - Rare fruit (worth 5+ fruits)
+
+## Usage:
+These will be the main collectibles in the game (like Wumpa fruit in Crash Bandicoot).
+Collect 100 fruits = 1 extra life!
+
+## File Format:
+- `.glb` or `.gltf` 3D models
+- Kenney assets are usually scaled correctly (1 unit = 1 meter)

models/environment/jungle/README.md

@@ -0,0 +1,27 @@
+# Jungle Environment Assets
+
+**Source:** Kenney Nature Kit (https://kenney.nl/assets/nature-kit)
+
+## What to put here:
+
+### Trees & Plants:
+- `tree_palm.glb` - Palm tree
+- `tree_jungle.glb` - Generic jungle tree
+- `bush_large.glb` - Large bush
+- `plant_tropical.glb` - Tropical plants
+- `vine.glb` - Hanging vines (if available)
+
+### Rocks & Terrain:
+- `rock_large.glb` - Large rock
+- `rock_small.glb` - Small rock
+- `stone_*.glb` - Various stone props
+
+### Ruins (for "Jungle Ruins" theme):
+- `pillar_*.glb` - Ancient pillars
+- `arch_*.glb` - Archways
+- `ruins_*.glb` - Broken structures
+- `statue_*.glb` - Ancient statues (if available)
+
+## Usage:
+These are DECORATIVE assets for visual polish.
+They don't need collision unless you want them to be obstacles.

models/environment/props/README.md

@@ -0,0 +1,22 @@
+# Environment Props
+
+**Source:** Kenney Platformer Kit
+
+## What to put here:
+
+### Checkpoint & Goal:
+- `checkpoint.glb` - Checkpoint flag/marker (IMPORTANT!)
+- `goal_flag.glb` - Level finish flag
+- `sign_*.glb` - Direction signs (optional)
+
+### Decorative:
+- `flower_*.glb` - Flowers
+- `mushroom_*.glb` - Mushrooms
+- Any other small decorative props
+
+## Note:
+You already have:
+- `cloud.glb` ✓
+- `flag.glb` ✓
+
+Only add NEW props here!

models/obstacles/README.md

@@ -0,0 +1,24 @@
+# Obstacle Models
+
+**Source:** Kenney Platformer Kit (https://kenney.nl/assets/platformer-kit)
+
+## What to put here:
+
+### Breakable Objects:
+- `crate.glb` - Wooden crate (breakable)
+- `crate_metal.glb` - Metal crate variant
+- `crate_tnt.glb` - Explosive crate (optional)
+
+### Hazards:
+- `spike_trap.glb` - Spike hazard (instant damage)
+- `spike_floor.glb` - Floor spikes
+- `saw_blade.glb` - Rotating saw (if available)
+
+### Interactive:
+- `spring_pad.glb` - Bounce pad (launches player upward)
+- `hammer_rotating.glb` - Rotating obstacle (if available)
+
+## Usage:
+- **Crates**: Player can break with spin attack or jump
+- **Spikes**: Instant damage on contact
+- **Springs**: Launches player to higher platforms

models/platforms/README.md

@@ -0,0 +1,26 @@
+# Platform Models
+
+**Source:** Kenney Platformer Kit (https://kenney.nl/assets/platformer-kit)
+
+## What to put here:
+
+### Additional Platform Types:
+- `platform_small.glb` - Small platform for precision jumps
+- `platform_large.glb` - Large platform
+- `platform_long.glb` - Long rectangular platform
+- `platform_round.glb` - Circular platform
+- `platform_moving.glb` - Moving platform variant
+
+### Theme Variants (if available):
+- `platform_jungle_*.glb` - Jungle-themed platforms
+- `platform_stone_*.glb` - Stone/ruins platforms
+- `platform_wood_*.glb` - Wooden platforms
+
+## Note:
+You already have these existing platforms:
+- `platform.glb` ✓
+- `platform_medium.glb` ✓
+- `platform_grass_large_round.glb` ✓
+- `platform_falling.glb` ✓
+
+Only add NEW platform variants here!

sounds/collectibles/README.md

@@ -0,0 +1,21 @@
+# Collectible Sound Effects
+
+## What to put here:
+
+### NEW Sounds Needed:
+- `fruit_collect.ogg` - Picking up fruit (can be similar to coin sound)
+- `life_gain.ogg` - Gaining extra life (special, celebratory sound!)
+- `gem_collect.ogg` - Special collectible (optional)
+- `fruit_bundle.ogg` - Collecting multiple fruits at once (optional)
+
+## Already Exists:
+- `coin.ogg` ✓ (can be reused for fruits if needed)
+
+## Sound Design Tips:
+- Fruit collect: Bright, positive, short (~0.2-0.5 sec)
+- Life gain: Longer, celebratory (~1-2 sec) with ascending tones
+- Make it satisfying! This is key to "one more try" psychology
+
+## File Format:
+- `.ogg` format
+- Keep file sizes small

sounds/enemies/README.md

@@ -0,0 +1,21 @@
+# Enemy Sound Effects
+
+## What to put here:
+
+### NEW Sounds Needed:
+- `enemy_hit.ogg` - Player hits enemy (spin attack)
+- `enemy_death.ogg` - Enemy defeated
+- `enemy_alert.ogg` - Enemy notices player (optional)
+- `enemy_attack.ogg` - Enemy attacks (optional)
+
+## Sound Design:
+- Hit: Impact sound, punch/kick
+- Death: Defeat sound (can be comedic/cartoonish)
+- Alert: Surprise sound effect
+
+## File Format:
+- `.ogg` format
+- Keep sounds distinct from player sounds
+
+## Variation:
+Can have different sounds for different enemy types!

sounds/level/README.md

@@ -0,0 +1,21 @@
+# Level Sound Effects
+
+## What to put here:
+
+### IMPORTANT Sounds:
+- `checkpoint.ogg` - Checkpoint activation (satisfying chime/bell)
+- `level_complete.ogg` - Level finish (victory fanfare!)
+- `game_over.ogg` - Game over (sad trombone or dramatic sound)
+
+### Optional:
+- `level_start.ogg` - Level begins countdown (3, 2, 1, GO!)
+- `countdown.ogg` - Timer warning (when time running out)
+
+## Sound Design:
+- **Checkpoint**: Positive, reassuring sound
+- **Level complete**: Big, celebratory (2-3 seconds)
+- **Game over**: Clear ending sound
+
+## File Format:
+- `.ogg` format
+- These can be slightly larger files (victory music ~2-5 sec)

sounds/music/README.md

@@ -0,0 +1,26 @@
+# Background Music
+
+## What to put here:
+
+### Optional Music Tracks:
+- `menu_theme.ogg` - Main menu background music
+- `level_jungle_theme.ogg` - Level 1 background music
+- `level_complete_jingle.ogg` - Short victory jingle
+
+## Music Source:
+- Kenney may not have music
+- Free options:
+  - Incompetech (royalty-free music)
+  - FreePD.com (public domain)
+  - OpenGameArt.org
+  - Make your own with tools like Bosca Ceoil
+
+## File Format:
+- `.ogg` format
+- Loop enabled in Godot import settings
+- Keep file size reasonable for web (<2MB per track)
+
+## Note:
+**Music is OPTIONAL for initial version!**
+We can add it later for polish.
+Focus on sound effects first!

sounds/obstacles/README.md

@@ -0,0 +1,22 @@
+# Obstacle Sound Effects
+
+## What to put here:
+
+### NEW Sounds Needed:
+- `crate_break.ogg` - Breaking wooden crate
+- `explosion.ogg` - TNT crate explosion
+- `spike_hit.ogg` - Hitting spikes (hurt sound)
+- `spring_bounce.ogg` - Bounce pad activation
+
+## Already Exists:
+- `break.ogg` ✓ (can be reused for crates)
+- `fall.ogg` ✓
+
+## Usage:
+- Crate break: Wood cracking/splintering
+- Explosion: Big impact sound
+- Spring bounce: Boing/spring sound
+- Spike hit: Sharp impact
+
+## File Format:
+- `.ogg` format

sounds/player/README.md

@@ -0,0 +1,25 @@
+# Player Sound Effects
+
+## What to put here:
+
+### NEW Sounds Needed:
+- `spin_attack.ogg` - Spin attack whoosh sound
+- `hurt.ogg` - Player takes damage
+- `death.ogg` or `fall_death.ogg` - Player dies
+- `slide.ogg` - Sliding sound (optional)
+- `double_jump.ogg` - Second jump sound (optional, can reuse jump.ogg)
+
+## Already Exists:
+- `jump.ogg` ✓
+- `land.ogg` ✓
+- `walking.ogg` ✓
+
+## File Format:
+- `.ogg` format (best for Godot/web)
+- Mono or stereo
+- Keep file sizes small (<100KB each for web performance)
+
+## Where to Find:
+- Kenney may have some sound effects
+- Or use free sites like freesound.org, sonniss.com
+- Can also generate simple sounds with tools like Bfxr or ChipTone

sounds/ui/README.md

@@ -0,0 +1,22 @@
+# UI Sound Effects
+
+## What to put here:
+
+### NEW Sounds Needed:
+- `button_click.ogg` - Generic button press
+- `menu_select.ogg` - Menu option selection
+- `menu_navigate.ogg` - Moving between menu options
+- `pause.ogg` - Opening pause menu
+- `unpause.ogg` - Closing pause menu
+
+## Sound Design:
+- Keep UI sounds subtle and not annoying
+- Short duration (~0.1-0.3 sec)
+- Clean, professional sound
+
+## File Format:
+- `.ogg` format
+- Very small file size
+
+## Optional:
+These can wait until we build the UI!

sprites/ui/icons/README.md

@@ -0,0 +1,28 @@
+# UI Icons
+
+**Source:** Kenney Game Icons or UI Pack
+
+## What to put here:
+
+### ESSENTIAL Icons (high priority):
+- `icon_life.png` or `icon_heart.png` - Life/health indicator
+- `icon_fruit.png` - Fruit counter icon (for HUD)
+- `icon_star.png` - Star rating icon
+- `icon_timer.png` or `icon_clock.png` - Timer/clock icon
+
+### Button Icons:
+- `button_pause.png` - Pause button
+- `button_play.png` - Play/resume button
+- `button_restart.png` - Restart button
+- `button_home.png` - Main menu button
+- `button_settings.png` - Settings button
+
+### Optional:
+- `icon_trophy.png` - Achievement/completion
+- `icon_star_empty.png` - Empty star (for ratings)
+- `icon_star_filled.png` - Filled star
+
+## File Format:
+- PNG format (transparent background preferred)
+- Recommended size: 64x64 or 128x128 pixels
+- Will be used in HUD and menus

sprites/ui/panels/README.md

@@ -0,0 +1,23 @@
+# UI Panels & Backgrounds
+
+**Source:** Kenney UI Pack
+
+## What to put here:
+
+### Panel Backgrounds:
+- `panel_menu.png` - Main menu background panel
+- `panel_popup.png` - Popup/dialog background
+- `panel_hud.png` - HUD background (optional)
+- `panel_dark.png` - Dark overlay for pause screen
+
+### Button Backgrounds:
+- `button_normal.png` - Normal button state
+- `button_hover.png` - Hover/pressed state
+- `button_disabled.png` - Disabled state
+
+## Usage:
+These create the visual style for menus and UI elements.
+9-slice scaling works great for panels of different sizes.
+
+## Optional:
+If Kenney doesn't have these, we can create simple colored rectangles in Godot!

sprites/ui/touch_controls/README.md

@@ -0,0 +1,23 @@
+# Touch Control Sprites (Mobile)
+
+**Source:** Kenney UI Pack or Game Icons
+
+## What to put here:
+
+### Virtual Joystick:
+- `joystick_base.png` - Base circle (background)
+- `joystick_thumb.png` - Thumb/stick (moves with input)
+
+### Action Buttons:
+- `button_jump.png` - Jump button (e.g., "A" or up arrow icon)
+- `button_spin.png` - Spin attack button (e.g., rotation icon)
+- `button_sprint.png` - Sprint button (optional)
+
+## Recommended Style:
+- Semi-transparent (alpha ~0.5-0.7)
+- Circular buttons work best
+- Size: 128x128 or 256x256 pixels
+
+## Usage:
+These will overlay on the screen for mobile/touch devices.
+Desktop players won't see them.