[G1-Sync] Manual knowledge update

2026-04-24 23:24:07 +09:00
parent ce1cc160d7
commit 53a986efda
9 changed files with 1078 additions and 0 deletions
@@ -0,0 +1,125 @@
+# Skybound Code Structure Audit and Stabilization Plan
+
+**Date**: 2026-04-24  
+**Project**: Skybound Protocol  
+**Author**: Codex  
+**Status**: Raw analysis logged before implementation  
+
+## 1. Overview
+
+This document records the first code-level audit after reviewing Skybound-related wiki documents. The goal was to compare the documented architecture with the actual code path in `/Volumes/Data/project/Antigravity/Skybound`, identify design and feature risks, and define the first stabilization pass.
+
+## 2. Documents Reviewed
+
+- `Topics/Skybound/Skybound-Knowledge-Hub.md`
+- `Topics/Skybound/01_Core_Engine/Skybound-Modular-Game-Architecture.md`
+- `Topics/Skybound/01_Core_Engine/Game-Engine-Loop-and-System-Orchestration.md`
+- `Topics/Skybound/05_Project_Issues/2026-04-22_Engine_Stability_Audit.md`
+- `Topics/Skybound/02_Combat_AI/Combat-System-and-Bullet-Interaction-Pipeline.md`
+- `Topics/Skybound/04_Mechanics_Progression/Campaign_and_Dual_Loop_System.md`
+- `Topics/Skybound/04_Mechanics_Progression/InGame_Progression_System.md`
+- `Technical_Reports/2026-04-22_Boss_Battle_System_Implementation.md`
+
+## 3. Code Structure Observations
+
+Skybound's actual runtime center is `src/features/game/hooks/useGameEngine.ts`. It directly instantiates and updates `EntityManager`, `StageDirectorSystem`, `SpawnerSystem`, `CombatSystem`, `ProgressionSystem`, `ModularWeaponSystem`, `TacticalSystem`, `HazardSystem`, `BossSystem`, `EffectSystem`, and `GameRenderer`.
+
+`SystemManager.ts` exists and documents a centralized orchestration pattern, but the active engine path does not use it. This is not inherently broken, but it creates a mismatch between the documented orchestrator and the actual execution path.
+
+React is primarily responsible for scene composition and modal/UI handling through `GameSceneRenderer.tsx`, while Zustand state is centralized in `useGameStore.ts`.
+
+## 4. Confirmed Problems
+
+### 4.1 Build Gate Is Broken
+
+`npm run build` fails. Representative causes:
+
+- `App.tsx` imports `useGameEngine` but does not use it.
+- Legacy `src/features/game/combatSystem.ts` is still included in TypeScript compilation and has type drift against current domain models.
+- `useSceneAudio.ts` does not include `HANGAR` in `SCENE_AUDIO`, despite `Scene` including `HANGAR`.
+- `SystemBoss.phase` is typed as `1 | 2 | 3`, while `bossRegistry.ts` contains a 4-phase boss.
+- `GameRenderer.ts` calls `CanvasRenderingContext2D.close()`, which should be `closePath()`.
+- `EntityManager` initializes enemies with `movePattern: 'NONE'`, which is not part of the current `Enemy.movePattern` union.
+
+### 4.2 Timeline Spawn Intents Are Not Wired
+
+`StageDirectorSystem` dispatches `SCRIPTED_SPAWN` and `SPAWN_MODE` intents, but `useGameEngine.ts` does not route those intents to `SpawnerSystem`.
+
+`SpawnerSystem` already provides `notifyScriptedSpawn()` and `activateSwarmBurst()`, so the design exists but the active dispatch wiring is missing.
+
+Expected impact: scripted waves and burst events may not appear as designed, leaving procedural spawning to carry too much of the combat pacing.
+
+### 4.3 Campaign Stage State Is Not a Single Source of Truth
+
+`StageDirectorSystem` receives `campaignStageIndex` when created, but `GameState.currentStage` still defaults to `1` and is not initialized from the selected campaign stage.
+
+Expected impact: Standard campaign can show stage progression in UI while the engine continues to evaluate boss selection, damage curves, backgrounds, rewards, and tech-part rolls as Stage 1.
+
+### 4.4 StageManager Mode Can Drift from Store Mode
+
+`StageManager` has its own internal `mode`, defaulting to `BLITZ`. The UI updates Zustand `stageMode`, but `stageManager.setMode()` is not called from the store action.
+
+Expected impact: Standard campaign clear can call `stageManager.onStageClear()` while the singleton still believes it is in Blitz mode, preventing next-stage campaign progression.
+
+### 4.5 COMMS Events Are Not Rendered
+
+`COMMS` events are emitted by engine systems, and `CommsOverlay.tsx` exists, but `useGameEngine.ts` does not map `COMMS` events to `useGameStore.setComms()`. `CommsOverlay` is also not rendered by `App.tsx`.
+
+Expected impact: mission dialogue, warning text, and tactical pacing messages are silently dropped.
+
+### 4.6 Starter Weapon Timer Is Not Cleaned Up
+
+`useGameEngine.ts` starts a `setTimeout()` for starter weapon selection, but cleanup does not clear the timer.
+
+Expected impact: if the engine unmounts quickly, a stale timer can emit a level-up modal or pause signal from an old engine instance.
+
+### 4.7 Skill Sync Boundary Is Fragile
+
+`GameSceneRenderer.tsx` calls store `addSkill()` and then engine `applySkill()`. `ProgressionSystem.applySkillSelection()` says Zustand owns skill increments, but also mutates `state.skills` as a fallback.
+
+Expected impact: this usually works because of the store subscription bridge, but the ownership boundary is not clean and may cause missed or inconsistent skill levels under timing stress.
+
+## 5. Stabilization Plan
+
+Priority order:
+
+1. Restore TypeScript build by removing obvious compile blockers and isolating legacy drift.
+2. Wire `SCRIPTED_SPAWN` and `SPAWN_MODE` intents from `StageDirectorSystem` into `SpawnerSystem`.
+3. Initialize engine `currentStage` from `stageMode` and `campaignStageIndex`.
+4. Keep `StageManager` mode synchronized with Zustand `stageMode`.
+5. Route `COMMS` events into the store and render `CommsOverlay`.
+6. Clear the starter weapon timer during engine cleanup.
+
+## 6. Verification Targets
+
+- `npm run build`
+- `npm run lint` as a visibility check, with the expectation that broad historical lint debt may remain after the first stabilization pass.
+
+## 7. Implementation Result
+
+The first stabilization pass was applied immediately after this raw audit.
+
+### 7.1 Build Recovery
+
+- Removed an unused `useGameEngine` import from `App.tsx`.
+- Added `HANGAR` to `SCENE_AUDIO` in `useSceneAudio.ts`.
+- Excluded legacy `src/features/game/combatSystem.ts` from `tsconfig.app.json` because the active runtime path uses `src/features/game/systems/CombatSystem.ts`.
+- Expanded boss phase typing from `1 | 2 | 3` to `number` so 4-phase registry bosses are valid.
+- Fixed `EntityManager` default enemy `movePattern` from invalid `NONE` to `SIDE_TO_SIDE`.
+- Fixed `CanvasRenderingContext2D.close()` to `closePath()`.
+- Removed compile-blocking unused locals from active systems.
+
+### 7.2 Runtime Wiring Recovery
+
+- `SCRIPTED_SPAWN` intents now call `SpawnerSystem.notifyScriptedSpawn()`.
+- `SPAWN_MODE` intents now activate `SWARM_BURST` or enqueue `MINI_BOSS` spawns.
+- Engine `currentStage` now initializes from `campaignStageIndex + 1` in Standard mode.
+- Zustand `setStageMode()` now synchronizes the `StageManager` singleton mode.
+- `COMMS` engine events now populate `useGameStore.activeComms`.
+- `CommsOverlay` is rendered while playing.
+- Starter weapon selection timer is cleared during engine cleanup.
+
+### 7.3 Verification Result
+
+- `npm run build`: passed.
+- `npm run lint`: still fails due broad pre-existing lint debt, mostly `@typescript-eslint/no-explicit-any`, older helper files, and React hook lint findings. The first pass reduced the functional blockers but did not attempt a large-scale type cleanup.
@@ -0,0 +1,149 @@
+# Skybound Final Stylized Casual Magitech Redirection
+
+**Date**: 2026-04-24  
+**Project**: Skybound Protocol  
+**Author**: Codex  
+**Status**: Raw art direction correction after final concept change  
+
+## 1. Reason for Redirection
+
+The previous pass moved Skybound toward **Semirealistic Magitech Fantasy**, but the latest direction returns the project to a clearer and more immediately readable mobile-survival style.
+
+The new target is **Stylized Casual Magitech** for a top-down survival shooter inspired by Survivor.io.
+
+This direction prioritizes:
+
+- maximum in-game visibility
+- bold silhouettes
+- thick readable outlines
+- flat lighting
+- vivid magical accents
+- consistent UI language from intro to mission result
+
+## 2. Core Concept
+
+Skybound should feel like a polished casual magitech action game rather than a dark semirealistic fantasy title.
+
+Primary gameplay readability goals:
+
+- player vehicle must be instantly identifiable
+- enemies must remain readable in dense hordes
+- pickups and weapon icons must be recognizable at small sizes
+- background grid must support movement clarity without competing with combat
+- every exposed screen should share the same playful magitech frame language
+
+## 3. Tone and Manner
+
+### Stylized Casual Magitech
+
+Visual language:
+
+- bold navy outlines
+- clean top-down silhouettes
+- flat color blocks
+- minimal material noise
+- bright arcane cyan
+- gold/orange mechanical accents
+- purple and pink enemy/corruption accents
+- chunky UI frames
+- high contrast buttons and progress bars
+
+Avoid:
+
+- gritty brushed metal
+- heavy realistic shadows
+- low-contrast dark UI
+- thin semireal linework
+- noisy texture detail
+- external non-project image dependencies
+
+## 4. Palette
+
+Base colors:
+
+- deep navy outline
+- saturated royal blue panels
+- readable sapphire floor tiles
+- bright brass and gold trim
+
+Magic accents:
+
+- arcane cyan for player and positive energy
+- crystal white-blue for highlights
+- vivid purple for advanced magic
+- hot pink for danger and enemy cores
+- mint green for healing and positive pickups
+- orange/gold for calls to action
+
+## 5. Screen Coverage
+
+The exposed user-facing screens were reviewed and targeted by the final theme pass:
+
+- Intro title screen
+- Airframe select screen
+- Hangar / upgrade overlay
+- In-game HUD
+- Quick start overlay
+- Tutorial overlay
+- Comms overlay
+- Level up modal
+- Mission success / failed / complete result screen
+
+## 6. Asset Coverage
+
+The procedural asset generator now outputs the final Stylized Casual Magitech library while preserving runtime file paths.
+
+Generated categories:
+
+- Magitech player airframes
+- normal enemies
+- elite enemies
+- bosses
+- modular stage tiles
+- title and result local backdrops
+- item drop sprite sheet
+- turret sheet
+- weapon and skill icons
+- projectiles
+- shield and currency icons
+- muzzle flash, impact, explosion, and laser VFX
+- commander and pilot portraits
+- contact sheet preview
+
+## 7. Implementation Notes
+
+The generator was redirected away from semirealistic material rendering and toward flat, readable shapes.
+
+Main implementation choices:
+
+- palette updated to bright casual magitech colors
+- default shape helpers now draw bold navy outlines
+- material texture strength reduced to keep assets flat
+- background tiles use readable grid blocks and low-competition arcane circuitry
+- local title and result background images were generated
+- title and result screens no longer depend on external Google image URLs
+- global magitech CSS override was rewritten for the final casual tone
+
+## 8. Changed Runtime Paths
+
+Important changed or generated paths:
+
+- `/Volumes/Data/project/Antigravity/Skybound/scripts/generate_magitech_assets.py`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/styles/magitechArt.css`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/TitleScreen.tsx`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/ResultCard.tsx`
+- `/Volumes/Data/project/Antigravity/Skybound/public/sprites/magitech_art_contact_sheet.png`
+- `/Volumes/Data/project/Antigravity/Skybound/public/sprites/background/title_magitech.png`
+- `/Volumes/Data/project/Antigravity/Skybound/public/sprites/background/result_magitech.png`
+
+## 9. Verification
+
+Asset generation completed successfully.
+
+Production build completed successfully with:
+
+```bash
+npm run build
+```
+
+The build still reports that `/sprites/player.png` is left unresolved at build time, which is a Vite static asset warning and was already non-blocking. The production bundle was generated successfully.
@@ -0,0 +1,74 @@
+# Skybound HUD and TAC Level Up Stylized Casual Magitech Fix
+
+**Date**: 2026-04-24  
+**Project**: Skybound Protocol  
+**Author**: Codex  
+**Status**: Raw follow-up fix from gameplay HUD screenshot review  
+
+## 1. Screenshot Issues
+
+The reviewed gameplay screenshots showed that the HUD and TAC Level Up modal still leaned heavily into the previous cyber-terminal style.
+
+Observed issues:
+
+- side HUD panels used thin cyan lines and transparent glass styling
+- top TAC level widget looked like a cold terminal module
+- control buttons were dark monochrome blocks
+- TAC Level Up modal used glitch text and blue terminal cards
+- skill cards did not share the bold casual magitech frame language
+
+## 2. Cause
+
+The global `magitechArt.css` provided the broad art direction, but component-level CSS files still applied later or more specific styles.
+
+Main affected files:
+
+- `HUDOverlay.css`
+- `LevelUpModal.css`
+
+These files preserved the original Stitch/cyber UI look and overrode parts of the new tone.
+
+## 3. Fixes Applied
+
+### HUD
+
+HUD styling was redirected to Stylized Casual Magitech:
+
+- chunky navy outlines
+- rounded blue magitech panels
+- gold active highlights
+- mint/cyan resource bars
+- less transparent glass
+- stronger mobile-game button affordance
+- side modules grouped into readable cards
+- top TAC level widget converted to a framed casual panel
+
+### TAC Level Up Modal
+
+The level-up modal was restyled:
+
+- removed glitch pseudo text
+- removed aggressive terminal skew animation
+- converted the modal into a rounded blue magitech reward panel
+- added thick dark outline and drop-shadow depth
+- changed skill cards to chunky selectable cards
+- changed icon boxes to framed magitech sockets
+- converted level dots into brighter readable pips
+- kept EVO cards gold/orange for special hierarchy
+
+## 4. Changed Runtime Paths
+
+Important changed paths:
+
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/HUDOverlay.css`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/LevelUpModal.css`
+
+## 5. Verification
+
+Production build completed successfully with:
+
+```bash
+npm run build
+```
+
+The existing `/sprites/player.png` static path warning remains non-blocking.
@@ -0,0 +1,83 @@
+# Skybound Nova Burst Icon and Effect Fix
+
+**Date**: 2026-04-24  
+**Project**: Skybound Protocol  
+**Author**: Codex  
+**Status**: Raw follow-up fix for skill-specific visual mismatch  
+
+## 1. Screenshot Issue
+
+`Nova Burst` looked like a lemon-shaped projectile icon.
+
+This did not match the actual skill behavior.
+
+## 2. Skill Meaning
+
+`Nova Burst` is not a missile, crystal shard, or thrown projectile.
+
+Actual gameplay behavior:
+
+- automatic radial AoE shockwave
+- triggers around the player
+- damages enemies inside the radius
+- knocks enemies outward
+- cooldown-based burst every few seconds
+- evolves into `Nova Guardian`, which adds stronger golden guardian behavior
+
+## 3. Art Direction Correction
+
+The icon should communicate:
+
+- central arcane core
+- circular shockwave expansion
+- radial force
+- rune-like magitech energy
+- area control around the player
+
+It should not communicate:
+
+- lemon
+- fruit
+- single projectile
+- gem pickup
+- missile tip
+
+## 4. Fixes Applied
+
+The procedural generator now creates `Nova Burst.png` with a dedicated `nova` icon shape.
+
+New visual structure:
+
+- cyan circular shockwave rings
+- central navy magitech core
+- arcane core light
+- radial spokes showing outward force
+- subtle purple secondary energy ring
+
+The in-game Nova Burst renderer was also adjusted:
+
+- center sprite is smaller and treated as a rune core
+- expanding shockwave ring is now the main visual read
+- added translucent pressure disk
+- added segmented rune ring
+- kept Guardian variant as gold/orange
+
+## 5. Changed Runtime Paths
+
+Important changed paths:
+
+- `/Volumes/Data/project/Antigravity/Skybound/scripts/generate_magitech_assets.py`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/GameRenderer.ts`
+- `/Volumes/Data/project/Antigravity/Skybound/public/sprites/missiles/Nova Burst.png`
+
+## 6. Verification
+
+Asset generation completed successfully.
+
+Production build completed successfully with:
+
+```bash
+npm run build
+```
+
+The existing `/sprites/player.png` static asset warning remains non-blocking.
@@ -0,0 +1,74 @@
+# Skybound Particle and Supply Readability Fix
+
+**Date**: 2026-04-24  
+**Project**: Skybound Protocol  
+**Author**: Codex  
+**Status**: Raw follow-up fix from gameplay screenshot review  
+
+## 1. Screenshot Issues
+
+The reviewed screenshot exposed two readability problems.
+
+Observed issues:
+
+- Mint/cyan square particles were scattered across the floor and looked like items even though they could not be collected.
+- The supply crate asset looked good, but it was not clear whether it was a player pickup or an enemy projectile/debris object.
+
+## 2. Cause
+
+### Mint Floor Squares
+
+The mint squares were runtime particles from `EffectSystem`.
+
+They were rendered in `GameRenderer.renderEffects()` using `fillRect()`, so every spark appeared as a small collectible-looking square.
+
+These particles can come from combat hits, skill effects, EMP interactions, exp pickup feedback, or other short-lived feedback systems.
+
+### Supply Ambiguity
+
+The supply crate sprite itself was readable as an object, but the gameplay affordance was weak.
+
+It needed explicit pickup language:
+
+- pickup color
+- capture ring
+- directional marker
+- short label
+
+## 3. Fixes Applied
+
+### Particle Shape
+
+Runtime particles now render as small rotated diamond sparks instead of square floor blocks.
+
+This keeps the magical spark feedback while reducing item confusion.
+
+Normal shard fragments were also changed from square blocks to triangular fragments.
+
+### Supply Pickup Readability
+
+Supply drops now render with:
+
+- mint-green dashed pickup ring
+- soft pickup fill
+- bobbing downward arrow
+- retained supply crate sprite
+- `PICK UP` label
+
+This separates supply drops from enemy bullets, hazards, and cosmetic particles.
+
+## 4. Changed Runtime Paths
+
+Important changed path:
+
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/GameRenderer.ts`
+
+## 5. Verification
+
+Production build completed successfully with:
+
+```bash
+npm run build
+```
+
+The existing `/sprites/player.png` static path warning remains non-blocking.
@@ -0,0 +1,141 @@
+# Skybound Semirealistic Magitech Fantasy Redirection
+
+**Date**: 2026-04-24  
+**Project**: Skybound Protocol  
+**Author**: Codex  
+**Status**: Raw art direction correction before second asset pass  
+
+## 1. Reason for Redirection
+
+The first generated art pack leaned too far into childish cartoon readability: thick outlines, flat toy-like shapes, and simplified symbolic silhouettes.
+
+The new target is **Semirealistic Magitech Fantasy** for a top-down horde survival-shmup inspired by Survivor.io, aimed at players aged 12-18 and casual adults.
+
+## 2. Core Concept
+
+The visual library should feel detailed, grounded, and cool rather than cute.
+
+Primary references by feel:
+
+- League of Legends-like readable fantasy detail
+- Warhammer-like dark material weight
+- Survivor.io-like top-down clarity and grid readability
+
+This is still a game with high enemy density, so readability remains critical, but contrast should come from lighting, value, and energy color rather than thick black outlines.
+
+## 3. Tone and Manner
+
+### Semirealistic Magitech
+
+Visual language:
+
+- dark iron
+- aged brass
+- brushed metal
+- weathered stone
+- glowing crystals
+- engraved runes
+- arcane circuitry
+- controlled deep shadows
+- focused magical highlights
+
+Avoid:
+
+- childish cartoon shapes
+- toy-like flat icons
+- heavy black outlines
+- overly bright candy palettes
+- large simplified emblem-only designs
+
+## 4. Palette
+
+Base colors:
+
+- dark sapphire
+- dark iron
+- forest green
+- weathered brass
+- basalt gray
+- deep crimson
+
+Magic accents:
+
+- arcane blue for player energy
+- neon purple for corruption
+- plasma red for enemy/boss danger
+- molten orange for forge/lava accents
+
+## 5. Asset Rules
+
+### Player Vehicle
+
+The player vehicle should read as a Magitech airship rather than a simple airplane.
+
+Required traits:
+
+- complex symmetrical or slightly asymmetrical hull
+- dark iron and brass material mix
+- intense crystalline power core
+- smaller gun turrets
+- visible engine components, gears, vents, and rune plates
+- subtle energy glow readable from top-down view
+
+### Enemies
+
+Enemies should be threatening corrupted creatures or ancient mechanical horrors.
+
+Examples:
+
+- clockwork spiders with poison sacks
+- rune golems made of dark stone
+- corrupted winged drakes
+- ancient mechanical horrors with plasma-red cores
+
+### Background
+
+Background should preserve Survivor.io-style grid readability but feel like an immersive fantasy environment.
+
+Target environments:
+
+- ancient overgrown Magitech city ruin
+- subterranean magma forge
+
+Rules:
+
+- weathered stone pavement
+- broken magitech circuitry embedded in the floor
+- basalt structures
+- subtle lava or arcane channels
+- background contrast lower than enemies and player
+
+### Effects
+
+Player effects should be arcane blue or crystal cyan.
+
+Enemy effects should lean plasma red, purple, or corrupted crimson.
+
+Death effects should be optimized and satisfying:
+
+- scrap metal shards
+- dark crystal fragments
+- arcane dust
+- controlled flashes, not full-screen clutter
+
+### UI
+
+UI should use Survivor.io-like directness with a refined dark iron and crystal shell.
+
+Required traits:
+
+- heavy dark iron frames
+- crystal level bar
+- rune and gear details
+- minimal but detailed HUD
+- clean modern gothic / steampunk-inspired readability
+
+## 6. Implementation Notes
+
+The next pass should replace the first cartoony art pack with a darker semirealistic procedural raster set while preserving runtime file paths.
+
+The existing generator should be rewritten so future iterations can adjust palette, materials, and silhouettes consistently.
+
@@ -0,0 +1,153 @@
+# Skybound Semirealistic Magitech Fantasy Art Pack
+
+**Date**: 2026-04-24  
+**Project**: Skybound Protocol  
+**Author**: Codex  
+**Status**: Superseded by semirealistic second pass  
+
+## 1. Direction
+
+Skybound's 2D visual identity was first redirected toward **Stylized Casual Magitech**, then corrected into **Semirealistic Magitech Fantasy** after visual review.
+
+The corrected target tone is a top-down survival shooter inspired by clear mobile action readability, but with more mature fantasy material treatment:
+
+- reduced outlines
+- dark iron and brass material language
+- controlled lighting
+- glowing crystalline cores
+- corrupted magical enemies
+- ancient magitech ruin backgrounds
+- high contrast at small gameplay sizes
+- color-coded enemy and weapon readability
+- playful magitech forms instead of realistic military hardware
+
+## 2. Core Art Rules
+
+### Silhouette
+
+Every gameplay object must remain readable at 36-72px on canvas.
+
+- Player vehicles use triangular forward-facing silhouettes.
+- Normal enemies use compact diamond/bug-like silhouettes.
+- Elite enemies use wider, more decorated silhouettes.
+- Bosses use tall central hulls with visible side modules and glowing cores.
+- Weapons and drops use symbolic icons instead of detailed illustrations.
+
+### Linework
+
+Use value contrast and glow separation instead of heavy cartoon outlines.
+
+Purpose:
+
+- separates sprites from busy scrolling backgrounds through lighting
+- keeps bullets, drops, and enemies visible during VFX-heavy combat
+- supports a grounded semirealistic style
+
+### Lighting
+
+Lighting is controlled and directional. Avoid noisy photorealism, but use subtle brushed metal, stone, and crystal texture.
+
+Allowed:
+
+- small inner highlights
+- soft magical glow behind important objects
+- subtle bevels
+- material grain
+- controlled shadow
+
+Avoid:
+
+- toy-like flat panels
+- low-contrast smoke
+- tiny greeble details
+
+### Palette
+
+Corrected palette:
+
+- Void: `#080a12`
+- Dark iron: `#1c2029`
+- Aged brass: `#a57a37`
+- Dark sapphire: `#102a52`
+- Forest green: `#164535`
+- Crimson: `#671a20`
+- Arcane blue: `#36cdff`
+- Neon purple: `#b03eff`
+- Plasma red: `#ff4149`
+- Molten orange: `#ff7a21`
+
+## 3. Generated Asset Coverage
+
+The following runtime assets were regenerated in-place under `public/sprites`:
+
+- player airframes: `Falcon.png`, `rayce.png`
+- charge shot: `chargeshot.png`
+- normal enemies: `normal_enemy/enemy01.png` through `enemy09.png`
+- elite enemies: `elite_enemy/elite01.png` through `elite16.png`
+- bosses: `boss/tile000.png` through `tile010.png`
+- turret atlas: `turret/turret_sprites.png`
+- item drops: `item_drops_sprite.png`
+- stage backgrounds: `background/stage_tile_1.png` through `stage_tile_8.png`
+- weapon and skill icons under `sprites/missiles`
+- core bullet, shield, currency, VFX sprites
+- comms portraits: `portraits/hq_commander.png`, `portraits/pilot_standard.png`
+
+## 4. UI Skin Coverage
+
+The UI skin was added through:
+
+- `src/features/game/styles/magitechArt.css`
+- imported from `src/App.css`
+
+The skin aligns:
+
+- HUD panels
+- level-up cards
+- comms overlay
+- hangar/action buttons
+- warning text
+- canvas saturation/contrast
+
+## 5. Generator
+
+The art pack is reproducible through:
+
+`scripts/generate_magitech_assets.py`
+
+This script uses the bundled Python runtime with Pillow and generates vector-like raster PNGs. It intentionally avoids relying on one-off manual image files so future palette or silhouette changes can be regenerated consistently.
+
+## 6. Preview Sheet
+
+Generated preview sheet:
+
+`public/sprites/magitech_art_contact_sheet.png`
+
+The preview sheet is for art review only and is not currently consumed by the game runtime.
+
+## 7. Follow-up Art Tasks
+
+Recommended next art pass:
+
+1. Add animation frame variants for normal and elite enemies.
+2. Split skill icons into a formal UI icon atlas instead of relying on individual PNGs.
+3. Add boss-specific silhouettes matching the narrative names in `bossRegistry.ts`.
+4. Add projectile color language documentation for player, enemy, boss, and gimmick bullets.
+5. Replace remaining CSS vocabulary from older cyber-neon UI with magitech naming over time.
+
+## 8. Second Pass Correction
+
+After user review, the first art pack was judged too childish/cartoon-like. The generator and UI skin were rewritten.
+
+Second pass changes:
+
+- removed thick outlines
+- added brushed metal / stone noise
+- added stronger shadows and glow-based separation
+- changed vehicles into darker magitech airships
+- changed enemies into corrupted mechanical/stone silhouettes
+- changed backgrounds into darker stone grid ruins with broken circuitry
+- changed UI from bright toy-card framing to dark iron/crystal framing
+
+The reproducible generator remains:
+
+`scripts/generate_magitech_assets.py`
@@ -0,0 +1,102 @@
+# Skybound Stylized Casual Magitech Ingame Asset Fix
+
+**Date**: 2026-04-24  
+**Project**: Skybound Protocol  
+**Author**: Codex  
+**Status**: Raw follow-up fix from gameplay screenshot review  
+
+## 1. Screenshot Issues
+
+The reviewed screenshots exposed three in-game visual problems.
+
+Observed issues:
+
+- `SUPPLY` air drop was rendered as a simple cyan ring and text label instead of a proper magitech supply crate.
+- Enemy sprites showed a faint rectangular transparency box around the aircraft body.
+- Large falling translucent circular hazards were rendered as plain gray circles and did not match the Stylized Casual Magitech tone.
+
+## 2. Cause
+
+### Supply Drop
+
+The supply drop was not using an image asset.
+
+It was drawn directly in `GameRenderer.renderAirDrops()` as:
+
+- animated circle stroke
+- translucent cyan fill
+- white `SUPPLY` text
+
+### Enemy Rectangle Artifact
+
+The procedural generator used glow layers and Lanczos downsampling.
+
+This left very low alpha pixels across the image canvas. In gameplay, those tiny alpha values became visible as a faint rectangular box around enemies.
+
+### Falling Circular Hazard
+
+The falling translucent circle was an `EMP_CLOUD` hazard.
+
+It was drawn directly in `GameRenderer.renderHazards()` as a generic gray filled circle.
+
+## 3. Fixes Applied
+
+### Supply Drop Asset
+
+A new stylized magitech crate sprite was generated:
+
+- `/Volumes/Data/project/Antigravity/Skybound/public/sprites/supply_crate.png`
+
+The renderer now draws this crate for air drops while preserving a small dashed cyan capture ring.
+
+### Alpha Cleanup
+
+The procedural asset generator now clamps very low alpha values to `0` during PNG export.
+
+This removes transparent rectangle artifacts while keeping intended outlines, glow, and silhouettes.
+
+Verified enemy sprite alpha:
+
+- normal enemy corner alpha: `0`
+- elite enemy corner alpha: `0`
+- boss corner alpha: `0`
+- no alpha values below the cleanup threshold remain
+
+### Hazard Assets
+
+New hazard sprites were generated:
+
+- `/Volumes/Data/project/Antigravity/Skybound/public/sprites/vfx/vfx_hazard_emp.png`
+- `/Volumes/Data/project/Antigravity/Skybound/public/sprites/vfx/vfx_hazard_asteroid.png`
+- `/Volumes/Data/project/Antigravity/Skybound/public/sprites/vfx/vfx_hazard_debris.png`
+
+`EMP_CLOUD` now renders as an arcane rune-field instead of a plain gray circle.
+
+`ASTEROID` and `DEBRIS` can render as stylized magitech rock fragments instead of fallback circles.
+
+## 4. Changed Runtime Paths
+
+Important changed or generated paths:
+
+- `/Volumes/Data/project/Antigravity/Skybound/scripts/generate_magitech_assets.py`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/hooks/useGameAssets.ts`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/GameRenderer.ts`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/utils/SpriteUtils.ts`
+- `/Volumes/Data/project/Antigravity/Skybound/public/sprites/supply_crate.png`
+- `/Volumes/Data/project/Antigravity/Skybound/public/sprites/vfx/vfx_hazard_emp.png`
+- `/Volumes/Data/project/Antigravity/Skybound/public/sprites/vfx/vfx_hazard_asteroid.png`
+- `/Volumes/Data/project/Antigravity/Skybound/public/sprites/vfx/vfx_hazard_debris.png`
+
+## 5. Verification
+
+Asset generation completed successfully.
+
+Alpha inspection confirmed transparent corners and no low-alpha rectangle residue for the checked enemy/boss/supply/hazard sprites.
+
+Production build completed successfully with:
+
+```bash
+npm run build
+```
+
+The build still reports the existing `/sprites/player.png` static path warning, but it remains non-blocking and the production bundle was generated successfully.
@@ -0,0 +1,177 @@
+# Skybound Survivor-Like Balance Curve Pass
+
+**Date**: 2026-04-24  
+**Project**: Skybound Protocol  
+**Author**: Codex  
+**Status**: Raw gameplay balance pass from user playtest feedback  
+
+## 1. Playtest Feedback
+
+The game shell looked close to Survivor.io / Vampire Survivors, but the actual gameplay did not feel like that genre.
+
+Reported issues:
+
+- gameplay did not deliver enough horde-survival pressure
+- stage balance felt uneven
+- TAC Level Up pacing felt unbalanced
+- growth did not form a satisfying user-facing curve
+
+## 2. Diagnosis
+
+The previous balance leaned closer to a shmup / tactical shooter.
+
+Main causes found in code:
+
+- simultaneous enemy cap was too low for a horde-survival feel
+- procedural spawn did not fully use the timeline `spawnIntervalMult`
+- early EXP requirement was too high
+- EXP growth multiplier was too steep
+- stage difficulty scaled enemy/bullet stats too aggressively
+- stage scripted events were compressed too early in the timeline
+- TAC Level Up card offers were weighted but not structured, so the user could receive awkward choices
+- starter skill offers could omit key horde-survival archetypes
+
+## 3. Target Curve
+
+New target:
+
+- first meaningful upgrade should arrive quickly
+- player should see more enemies on screen
+- enemies should be individually weaker
+- danger should come from density and positioning, not bullet stat spikes
+- level-up choices should consistently support build formation
+- stage progression should rise smoothly rather than jump sharply
+
+## 4. Applied Balance Changes
+
+### EXP and Level-Up
+
+Changes:
+
+- initial required EXP lowered from `100` to `45`
+- normal enemy EXP increased from `5` to `7`
+- elite EXP increased from `25` to `32`
+- level-up EXP multiplier changed from steep `1.60 / 1.72 / 1.85` to smoother `1.24 / 1.30 / 1.36 / 1.42`
+
+Expected result:
+
+- early TAC Level Ups arrive faster
+- the player can form a build before the first spike
+- later progression still slows down without becoming a wall
+
+### TAC Level Up Card Structure
+
+The card generator now tries to offer:
+
+- one owned skill upgrade
+- one synergy / spike-counter / EVO-supporting option
+- one flexible option
+
+Expected result:
+
+- fewer dead-choice screens
+- higher chance of completing coherent builds
+- less frustration from random-only card pools
+
+### Starter Selection
+
+Starter cards now come from three archetype buckets:
+
+- primary damage
+- area / crowd control
+- utility / defense
+
+Expected result:
+
+- every run begins with a usable horde-survival foundation
+- the first choice feels strategic without becoming punishing
+
+### Enemy Density and Spawning
+
+Changes:
+
+- hard enemy cap increased from `30` to `90`
+- timeline phase caps increased by stage and phase
+- procedural spawn interval now uses `spawnIntervalMult`
+- procedural spawns can arrive in small batches
+- formation spawns now occur more often
+- individual enemy HP and speed were reduced to support higher density
+- elite chance is now a gradual probability instead of flipping too hard by difficulty
+
+Expected result:
+
+- more screen-filling horde pressure
+- less empty movement time
+- more satisfying weapon-clearing moments
+
+### Stage Curve
+
+Changes:
+
+- stage duration curve changed from `120 + stage * 30s` to `150 + stage * 18s`
+- stage difficulty scaling reduced from steep `+0.4 per stage` to smoother `+0.18 per stage`
+- phase difficulty multipliers were lowered
+- phase enemy caps were increased
+- scripted wave events are distributed across the stage instead of firing too early
+
+Expected result:
+
+- stages feel less spiky and more readable
+- difficulty rises through density and phase rhythm
+- player has time to grow before major pressure events
+
+### Enemy Bullet and Damage Pressure
+
+Changes:
+
+- enemy bullet speed curves were reduced
+- damage curves were reduced
+- bullet caps were reduced
+- global enemy bullet speed multiplier reduced
+- enemy projectile damage multipliers reduced
+
+Expected result:
+
+- gameplay moves away from bullet-hell punishment
+- movement pressure still exists, but horde positioning becomes the main focus
+
+### Weapon Rhythm
+
+Several weapon cooldowns were shortened so early picks feel active sooner.
+
+Nova Burst was also adjusted to trigger sooner and scale more clearly as an AoE crowd-control tool.
+
+## 5. Changed Runtime Paths
+
+Important changed paths:
+
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/config/balance.ts`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/config/CombatTimeline.ts`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/config/weaponBehaviors.ts`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/SpawnerSystem.ts`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/ProgressionSystem.ts`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/CombatSystem.ts`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/ModularWeaponSystem.ts`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/types.ts`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/hooks/useGameEngine.ts`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/store/useGameStore.ts`
+
+## 6. Verification
+
+Production build completed successfully with:
+
+```bash
+npm run build
+```
+
+The existing `/sprites/player.png` static path warning remains non-blocking.
+
+## 7. Next Playtest Questions
+
+Recommended next playtest checks:
+
+- Does the first level-up happen within a satisfying time window?
+- Does the screen feel populated without becoming unreadable?
+- Do weapons feel like they clear hordes?
+- Do stage spikes feel earned rather than sudden?
+- Does TAC Level Up usually offer at least one desirable choice?