Skip to content

Create entity database inspection devtool #134

Description

@siennathesane

Description

In order to debug entity persistence and inspect saved game state,
as a Marathon developer,
I need a CLI devtool that can read entity databases and display entity data in human-readable format.

This tool will help with debugging persistence issues, inspecting world state, and validating migrations.

Acceptance Criteria

Scenario: Devtool can list entities
  Given a world database exists
  When running the devtool list command
  Then all entities are displayed with basic metadata

Scenario: Devtool can inspect entity details
  Given a world database exists
  When running the devtool inspect command with entity ID
  Then entity metadata and deserialized component data is displayed

Scenario: Devtool can dump database statistics
  Given a world database exists
  When running the devtool stats command
  Then entity counts by type and database size are displayed

Features

Commands

  • inspect list [--type <entity_type>] - List all entities with basic metadata
  • inspect entity <id|network_id> - Show detailed entity data (deserialize and pretty-print components)
  • inspect stats - Database statistics (entity counts, size, schema version)
  • inspect verify - Verify all entities can be deserialized successfully
  • inspect export <entity_id> [--json|--ron] - Export entity to structured format

Display Format

  • Metadata: id, entity_type, network_id (as UUID string), timestamps
  • Components: Deserialized and pretty-printed using Debug or custom formatter
  • Optional JSON/RON export for external tools

Technical Notes

  • Dependencies: SQLite Schema Design and Migration System #128 (SQLite schema with rkyv serialization)
  • Approach:
    • CLI tool using clap for argument parsing
    • Read-only database access
    • Deserialize rkyv blobs and pretty-print component data
    • Support filtering/searching by entity_type, network_id
  • Files affected:
    • New: crates/devtools/src/bin/entity-inspector.rs (or similar)
    • Use existing persistence/serialization code

Additional Context

Since entity component data is stored as rkyv binary blobs for performance, we lose SQL queryability. This devtool fills that gap by providing human-readable inspection for debugging and development purposes.

Low priority - can be implemented after v0 core persistence is working.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/toolingBuild systems, CI/CD pipelines, development tools, code generation, testing infrastructure

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions