[Batch 3] Save/load UI + world list screen

[MichaelFisher1997]

Summary

Add in-game UI for loading saved worlds and creating new worlds that persist. This is the player-facing half of the persistence system.

Depends on: #377 (chunk serialization API) — needs SaveManager.loadChunk() to exist

Current Behavior

The SingleplayerScreen has:

• Seed text input (keyboard typing)
• RANDOM button for random seed
• World type selector (cycles through registered generators)
• CREATE button → creates new WorldScreen with seed → generates fresh world

There is no "load existing world" option. No save directory is scanned.

Target Behavior

SingleplayerScreen changes

• Split into two sections: "CREATE NEW WORLD" and "LOAD WORLD"
• "LOAD WORLD" button → navigates to new WorldListScreen

WorldListScreen (new)

• Scans ~/.config/zigcraft/saves/ directory
• Lists each world as a row:
  • World name (from directory name or level.dat)
  • Seed (from level.dat)
  • Last played (timestamp from level.dat)
  • Generator type (from level.dat)
• Click a world → load it → navigate to WorldScreen
• Delete button with confirmation
• Back button returns to singleplayer

GameSession changes

• GameSession.init() currently always generates a fresh world
• Add path for loading from save: init() takes optional save_dir parameter
• If save_dir provided: World uses SaveManager to load chunks instead of generating
• If no save_dir: current behavior (fresh generation)

Implementation Plan

Step 1: WorldListScreen

// src/game/screens/world_list.zig
const WorldListScreen = struct {
    worlds: []WorldEntry,
    selected: ?usize,
    scroll_offset: f32,

    const WorldEntry = struct {
        name: []const u8,
        seed: u64,
        last_played: i64,
        generator: []const u8,
        dir_path: []const u8,
    };
};

• onEnter(): scan save directory, read each level.dat, populate list
• update(): handle scroll, selection, click
• draw(): render list with UISystem (same pattern as other screens)
• Back button, Load button, Delete button

Step 2: SingleplayerScreen modifications

• Add "LOAD WORLD" button below "CREATE"
• On click → screen_manager.push(WorldListScreen)
• Keep existing create flow unchanged

Step 3: GameSession load path

• Add save_dir: ?[]const u8 to session init params
• When save_dir != null: create SaveManager, pass to World/WorldStreamer
• WorldStreamer.generateChunk() tries load before generate (see [Batch 3] Integrate GPU frustum culling into WorldRenderer #379 integration)
• World name displayed in HUD or debug overlay

Step 4: Delete world

• Confirmation dialog: "Delete world ''? This cannot be undone."
• On confirm: recursively delete save directory
• Refresh world list

Files to Create

• src/game/screens/world_list.zig — new screen

Files to Modify

• src/game/screens/singleplayer.zig — add "LOAD WORLD" button
• src/game/session.zig — load path, save_dir parameter
• src/game/screen.zig — register new screen type (if needed)
• src/tests.zig or src/game/screen_tests.zig — tests for WorldListScreen

Testing

• Create world → close → load world → blocks are where you left them
• World list shows all saves with correct info
• Delete world removes directory and refreshes list
• Cancel delete does nothing
• Loading invalid/corrupt save shows error, doesn't crash
• Empty save directory shows helpful message
• Back button returns to singleplayer screen

Roadmap: docs/PERFORMANCE_ROADMAP.md — Batch 3, Issue 2C

[opencode-agent]

Looking at this issue, here's my analysis:

Classification: Feature Request

Dependency Status: ✅ Properly noted - depends on #377 for SaveManager.loadChunk() API

Scope Assessment: This is a substantial feature spanning UI, file I/O, and game session management. While the implementation plan is well-structured, this should be broken into 4 separate sub-issues/PRs for manageable review:

1. WorldListScreen UI (src/game/screens/world_list.zig) - Screen implementation and save directory scanning
2. SingleplayerScreen integration - Add "LOAD WORLD" button and navigation
3. GameSession load path - save_dir parameter and SaveManager integration
4. Delete world functionality - Confirmation dialog and directory cleanup

Technical Feedback:

• Good use of existing patterns (UISystem, screen manager)
• Consider using std.fs.cwd().makePath() for cross-platform save directory creation
• For level.dat parsing, ensure you handle schema versioning early
• The WorldStreamer.generateChunk() load-before-generate logic should coordinate with [Batch 3] Integrate GPU frustum culling into WorldRenderer #379

Ready for work once #377 is merged. The breakdown into 4 PRs will make reviews faster and reduce risk of conflicts given this touches session initialization code.

Would you like me to create the sub-issues, or do you prefer to keep this as a single tracking issue?

opencode session  |  github run