PROGRESS.md

Progress Log: Cars Clean Room Remaster

Memory Dump & Tech Intel (Important for Future)

Binary Formats

• .m2 (Track Data): Custom container. Part 0: Width (byte). Part 1: Map grid data (bytes). Part 2: Waypoint pathing data. Map width for Track 0 is 142. Tiles are rendered at 10x7 px.
• .img (Sprite Containers): A custom binary wrapper around standard PNG data. Use parseBinary (VarInt length-prefixed parts) to extract the raw PNG bytes.
• coords.bin: Contains the frame metadata for all sprites. Each frame is 6 bytes: [srcX, srcY, width, height, offsetX, offsetY].
• game_menu.bin / ms.bin: Likely contain menu structures and mission data (not yet parsed).

Coordinate Systems

• Standardized to Y-UP: The engine uses native LibGDX (0,0 is Bottom-Left).
• Sprite Mapping:
  • J2ME offsets are from Top-Left.
  • LibGDX_X = targetX - offsetX.
  • LibGDX_Y = targetY + offsetY - height.
• Car Physics: Player car uses frames 309 to 324 (16 frames). Original code had 48 but player car specific texture 12.png aligns with the 16-frame cycle.

Class Semantic Mapping

• class_10 -> GameCanvas / MenuScreen / GameScreen
• class_3 -> GameEngine / CarsGame
• class_8 -> SpriteManager / GameRenderer
• class_9 -> CarEntity
• class_2 -> Settings / ConfigParser

---

Phase 1: Reorganization & Setup [COMPLETE]

• Create project structure (qc.aeonis.cars)
• Migrate assets to remaster/assets/
• Set up root build.gradle and subprojects
• Initialize PROGRESS.md

Phase 2: Asset Pipeline & Engine Core [COMPLETE]

• Create base CarsGame and DesktopLauncher
• Create Screen management system (LoadingScreen, MenuScreen, GameScreen)
• Implement native LibGDX asset loading for PNGs
• Implement custom binary parser for .m2 and .bin files
• Implement initial InputHandler with Keyboard + Mouse mapping
• Enforce Nearest-Neighbor filtering for all textures (HD clarity)

Phase 3: Game Logic Extraction [IN PROGRESS]

• Reverse-engineer and implement TrackData loading
• Reverse-engineer and implement CarEntity physics (ACCEL/FRICTION)
• Implement SpriteManager with .img container support
• Implement GameRenderer for track/car drawing
• Implement rotation-to-frame mapping for cars (Fixed to 16 frames)
• Implement initial CarAI skeleton
• Implement collision detection (Track tiles & Borders)

Phase 4: Rendering & UI (Landscape) [COMPLETE]

• Implement camera follow logic
• Support landscape resolution scaling (ExtendViewport)
• Implement mouse-click car steering (Target-based rotation)
• Rebuild Menu system (MenuScreen with scene2d.ui)
• Implement Hybrid Font System (TrueType HD default)
• Implement SettingsScreen with GUI Scale and Language
• Implement PauseOverlay (ESC to pause)

Upcoming TODOs (Next Session)

• Audio Engine: Convert .mid to .ogg or implement MIDI synth to restore music.
• Entity Placement: Parse coords.bin/ms.bin to place coins, obstacles, and enemy cars.
• Story/Flow: Implement race logic (laps, countdown, finish line) and mission transitions.
• Physics Polish: Refine car handling (less "floaty") and add drift/skid effects.
• UI Refinement: Reduce HUD text size (currently too large) and add more vibrant race-day UI.

---

Updated on 2026-05-20 by Cdx CLI