[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?