convoy visualizer

[choccccy]

Overview

Implement a “Convoy Visualizer” for the DF Godot app, inspired by Pocket Trains, where a selected convoy is shown driving through a 2D side-scrolling landscape. The aim is to make convoys feel real and distinct, not just rows of data on the map screen.

Motivation

• Current convoys feel abstract from the map screen and do not feel visually distinct or tangible.
• We already track rich vehicle metadata (body type, paint color, etc.) that is currently unused visually, and this is a natural place to surface it.
• A simple 2D physics sim (similar in spirit to Spellist’s sim) can deliver a big “wow” factor without being technically heavy.
• This also supports the “MMO” fantasy by showing other convoys moving in the same world space.

Core Features

• 2D convoy side-scroller view for any selected convoy.
• Vehicles rendered with correct body type and paint color.
• Lightweight 2D physics so vehicles bounce/rumble over terrain.
• Optional playful interactivity: grabbing/flinging cars and letting them bounce around.
• Environment-dependent backgrounds/roads.
• Compact embedded view plus fullscreen mode, with the ability to completely collapse if not wanted.
• Future: show nearby player convoys in the same view to sell the MMO feel.
• Future: idle “screensaver” mode that cycles between active convoys when the user is inactive.

From @Aidan-Reese: originally envisioned as layered 2D sprites with background and road changing per environment, physics so cars bounce and rumble over terrain, and optionally allowing the user to grab and fling cars around.

---

UX / UI Behavior

• From the map/convoy list, when a convoy is selected, show a small 2D side-scroller preview window of that convoy traveling across the landscape.
• The preview should reflect convoy state:
  • Moving when traveling.
  • Stopped/idle when in a settlement.
• The user can:
  • Click to toggle the preview between embedded and fullscreen.
  • Collapse the preview entirely if they don’t want it visible.
• In fullscreen mode, if user inactivity is detected for some time, the app can automatically:
  • Cycle between in-progress convoys.
  • Act like a “screensaver” that idly shows different convoys moving through the world.

---

Multiplayer / World Feel (Future Work)

• Show other nearby convoys passing by in the scene to emphasize that this is a shared MMO-like world.
• Requires backend support to:
  • Query “nearby convoys” for a given convoy position.
  • Likely tie into or reuse the fog-of-war / visibility system previously discussed.
• Frontend should treat other convoys as non-interactive visual entities (at least in v1), but with correct vehicle compositions and colors for consistency.

---

Technical Implementation (Godot / Frontend)

Scene & Node Structure

• Create a dedicated ConvoyVisualizer scene, likely 2D:
  • Root: Node2D or Control (depending on whether we treat it as world-space or UI-embedded).
  • World:
    • ParallaxBackground for sky/horizon layers. youtube
    • One or more ParallaxLayer children for background, midground, and foreground. youtube
    • A “road” layer (e.g., Sprite2D / TileMap) that represents the terrain the convoy drives on.
  • Vehicles:
    • A parent Node2D holding each vehicle instance in the convoy.
    • Each vehicle as a RigidBody2D (or CharacterBody2D/KinematicBody2D if we prefer manual control) with:
      • Sprite2D configured based on vehicle body type.
      • Color modulation / material override based on paint color.
      • CollisionShape2D to interact with road/terrain colliders. kodeco
  • Camera:
    • Camera2D following the convoy root or a designated lead vehicle.
    • Optional slight camera lag / smoothing for more juice.

Physics & Motion

• Use Godot’s 2D physics:
  • Vehicles as RigidBody2D with tuned mass, friction, and bounce so they visually respond to road bumps and terrain features. [docs.godotengine](https://docs.godotengine.org/en/stable/tutorials/physics/physics_introduction.html)
  • The “road” can be mostly flat initially, with slight height variations or invisible colliders to create rumble.
• Movement:
  • Simplest: move the world past the camera at convoy speed, while vehicles maintain relative positions via joints or constraints.
  • Alternative: actually move the vehicles across a static road, but this may complicate infinite scrolling backgrounds.
• Interactivity:
  • On pointer input over a vehicle, allow a small impulse or force to be applied to the RigidBody2D to simulate grabbing/flinging. docs.godotengine

Data Integration (DF Game Data → Visualizer)

• Input: convoy ID or convoy data structure from the main game state.
• For each vehicle in that convoy:
  • Map body_type → sprite resource path (sprite atlas or individual textures).
  • Map paint_color → color modulation on the sprite.
  • Generate nodes dynamically from a template scene (e.g., Vehicle2D.tscn).
• The visualizer should:
  • Subscribe to convoy state updates (position, speed, environment, in-settlement vs traveling).
  • Update environment:
    • Environment/biome → selection of background + road tileset.
  • Update motion:
    • Convoy speed → scroll speed of background/road and base velocity for vehicles.

Embedding in UI

• Wrap ConvoyVisualizer in a reusable component that can be:
  • Embedded into a panel on the main map/convoy screen as a small viewport.
  • Popped out into fullscreen (e.g., toggling visibility of other UI layers, or swapping scenes while keeping shared game state). youtube
• Handle:
  • Resize and aspect ratio changes when toggling between embedded and fullscreen.
  • Input routing so fullscreen mode captures interactions (drag/fling) while not interfering with global input.

Screensaver / Idle Mode

• Add an inactivity timer at the app level:
  • On no input for N seconds while the visualizer is active or available, switch to fullscreen convoy visualizer.
  • Rotate through active convoys at an interval (e.g., every 20–60 seconds) using existing scene change or view-switching logic. youtube
• Ensure minimal overhead when idle:
  • Optionally reduce physics tick rate or detail if performance becomes an issue.

---

Backend / API Requirements (Future)

• “Nearby convoys” API:
  • Input: convoy ID or world coordinates; output: list of other convoys within radius, with enough data to render a simplified visual (vehicle list, colors).
  • Likely reuse fog-of-war visibility or introduce a dedicated read model for “visible convoys around X”.
• Frequency:
  • Periodic polling or server push to keep nearby convoy list reasonably up to date without overloading the backend.

---

Milestones

1. Prototype (Single Convoy, Offline)

   • Static background, simple road.
   • One convoy visualized with correct body types/paint colors.
   • Basic side-scrolling motion (no physics, or minimal).

2. Physics & Polish

   • Enable 2D physics on vehicles for bouncing/rumble.
   • Introduce environment-based backgrounds and roads.
   • Basic interactivity: flinging/grabbing vehicles.

3. UI Integration

   • Embed visualizer on convoy detail / map screen.
   • Implement fullscreen toggle and collapsible panel.
   • Show correct convoy state (moving vs settlement idle).

4. Screensaver Mode

   • Inactivity detection and automatic fullscreen visualizer.
   • Idle rotation between active convoys.

5. MMO Enhancements (Stretch)

   • Backend endpoint for nearby convoys.
   • Render passing convoys in the same scene.