Create entity database inspection devtool #134

New Issue

siennathesane · 2025-12-17T16:07:39Z

siennathesane commented

2025-12-17 16:07:39 +00:00

(Migrated from github.com)

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: #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.

## 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 ```gherkin 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: #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.

siennathesane self-assigned this 2026-03-20 21:14:58 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: studio/marathon#134