source-engine/opencode.md

OpenCode Loop Prompt

You are working in a repo whose goal is to build a Rust Source-compatible runtime alongside or from this Source Engine codebase.

Project goal: Create a Rust engine/runtime that can load Source Engine content well enough to run maps with compatible BSP geometry, VPK-mounted assets, VMT/VTF materials, simple game entities, a Source-like console/CVar system, and a menu/VGUI-like UI.

You must work incrementally. Do not attempt broad rewrites. Do not invent large systems unless the current task requires them.

State Files

Use these files as persistent memory between runs:

• PROJECT_STATE.md: current status, architecture decisions, known limitations.
• ROADMAP.md: ordered milestones and task backlog.
• COMPATIBILITY.md: supported Source formats/entities/features.
• TASKS.md: active, queued, blocked, and completed tasks.
• DEVLOG.md: append-only progress log.
• DECISIONS.md: append-only architectural decisions.
• TESTING.md: how to run tests and what currently passes/fails.

Before Doing Any Work

1. Read all state files if they exist.
2. Inspect the repo structure.
3. Identify the next smallest unblocked task from TASKS.md or ROADMAP.md.
4. If no state files exist, create them with an initial plan.

Work Loop

1. Pick exactly one small task.
2. State the selected task in DEVLOG.md.
3. Implement only that task.
4. Add or update tests/fixtures where practical.
5. Run formatting and relevant tests.
6. Update PROJECT_STATE.md, TASKS.md, COMPATIBILITY.md, and TESTING.md.
7. Append a short DEVLOG.md entry with:
   • task completed
   • files changed
   • commands run
   • tests passing/failing
   • next recommended task
8. Stop.

Engineering Rules

• Prefer small, testable crates/modules.
• Prefer parsing/dump tools before runtime features.
• Use Rust 2021 or newer.
• Avoid unsafe unless absolutely necessary and documented in DECISIONS.md.
• Do not fake compatibility. If something is placeholder, mark it clearly in COMPATIBILITY.md.
• Do not implement unrelated features.
• Do not delete user work.
• Do not make sweeping formatting changes outside files touched for the task.
• Treat the original Source Engine code and tools as reference material, not as something to port wholesale in one pass.

Suggested Architecture

• crates/source_math
• crates/source_bsp
• crates/source_vpk
• crates/source_vmt
• crates/source_vtf
• crates/source_entity
• crates/source_render
• crates/source_vgui
• crates/source_console
• crates/source_app

Preferred Libraries

• glam for math
• wgpu for rendering
• winit for window/input
• egui for early menu/debug UI
• serde for structured dumps/tests
• clap for CLI tools
• tracing for logging
• insta or JSON fixtures for snapshot-style parser tests

Initial Milestone Order

1. Workspace/crate layout.
2. BSP header and lump directory parser.
3. BSP entity lump parser.
4. BSP planes, vertices, edges, surfedges, faces.
5. Basic map dump CLI.
6. VPK filesystem mounting.
7. VMT KeyValues parser.
8. VTF loading or placeholder texture path.
9. Render BSP world geometry.
10. Free camera.
11. info_player_start and worldspawn support.
12. Console and CVar registry.
13. Basic Source-like menu.
14. Player controller with BSP collision.
15. trigger_once / trigger_multiple.
16. Entity I/O outputs.
17. func_button / func_door.
18. HUD basics.

Task Size Rule

A task should usually be completable in under 1-2 hours and should leave the repo in a runnable or testable state.

If uncertain:

• Prefer adding a dump/inspection tool.
• Prefer parser tests over runtime guesses.
• Prefer documenting a limitation over pretending it works.

Starter TASKS.md

If TASKS.md does not exist, create this:

# Tasks

## Active
- [ ] Create Rust workspace layout for Source-compatible runtime.

## Queue
- [ ] Add `source_math` crate with `Vec3`, `QAngle`, planes, bounds helpers using `glam`.
- [ ] Add `source_bsp` crate and parse BSP header.
- [ ] Parse BSP lump directory.
- [ ] Add `bsp_dump` CLI that prints header/lump metadata as JSON.
- [ ] Parse BSP entity lump as KeyValues-style entities.
- [ ] Add entity dump command.
- [ ] Parse planes lump.
- [ ] Parse vertices lump.
- [ ] Parse edges and surfedges.
- [ ] Parse faces.
- [ ] Resolve texinfo and texdata.
- [ ] Add placeholder renderer with `wgpu`.
- [ ] Render untextured BSP world geometry.
- [ ] Add VMT parser.
- [ ] Add VTF texture path/loading placeholder.
- [ ] Render textured BSP faces.
- [ ] Add free camera.
- [ ] Add console and CVar registry.
- [ ] Add Source-like main menu.
- [ ] Implement `worldspawn`.
- [ ] Implement `info_player_start`.
- [ ] Implement basic player movement.
- [ ] Implement BSP collision traces.
- [ ] Implement `trigger_once`.
- [ ] Implement Source-style entity output dispatch.

## Blocked

## Done

Starter PROJECT_STATE.md

If PROJECT_STATE.md does not exist, create this:

# Project State

## Goal
Build a Rust Source-compatible runtime capable of loading and running Source maps with compatible assets, basic entities, menu UI, console/CVars, and game-layer behavior.

## Current Focus
Early engine foundation: workspace, parsers, dump tools, tests.

## Architecture
The project is split into small crates for formats, rendering, entity/game logic, UI, and application runtime.

## Compatibility Target
Initial target: Source SDK 2013 Singleplayer-style BSP maps and assets.

## Non-Goals For Now
- Full Source multiplayer networking
- Full NPC AI
- Full Source shader parity
- Save/load
- Demo playback
- Complete VGUI port
- Direct C++ game DLL compatibility

## Current Limitations
Everything is initially incomplete until implemented and tested.

Agent Instruction

Now begin the loop.