Database

Database

Respoon uses MySQL or MariaDB for persistence. All tables are created and seeded automatically on first start.

---

Requirements

• MySQL 5.7+ or MariaDB 10.3+
• A database driver: either oxmysql (recommended) or a manual connection string

---

Driver detection

Respoon supports two database drivers and selects one automatically at startup:

Driver	When used	Notes
oxmysql (preferred)	If the oxmysql resource is started	Uses oxmysql's async exports -- no extra config needed
Bundled mysql2 (fallback)	If oxmysql is not available	Connects directly using the mysql_connection_string convar

Using oxmysql (recommended)

If you already have oxmysql running on your server, Respoon detects it automatically. No additional database configuration is required.

Make sure oxmysql starts before Respoon:

ensure oxmysql
ensure respoon

Using a connection string (fallback)

If you do not have oxmysql, add this to your server.cfg:

set mysql_connection_string "mysql://user:password@localhost:3306/database"

Replace user, password, localhost, 3306, and database with your actual database credentials.

---

Auto-initialization

On first startup, Respoon automatically:

1. Creates all tables -- no manual SQL required
2. Seeds the model catalogs -- populates props, peds, vehicles, animations, and particle effects
3. Runs any pending migrations -- when updating, schema changes are applied automatically

First boot takes approximately 30 seconds due to the catalog seeding. Subsequent starts are instant.

Migration validation

On every startup, Respoon verifies:

• Schema integrity -- confirms all expected tables exist. If a table is missing, the migration that created it will re-run.
• Seed completeness -- checks that seeded tables meet minimum row counts. If data is incomplete, the seed will re-run.

This self-repair mechanism prevents "migration applied but tables missing" issues.

---

Tables

All tables use the respoon_ prefix and are created in the database your driver is connected to.

Core tables

Table	Purpose
respoon_rooms	Room metadata (name, owner, routing bucket, home position, environment)
respoon_entities	Spawned entities -- props, peds, and vehicles (position, rotation, properties)
respoon_room_members	Room membership and access roles
respoon_models	Model catalog -- all known props, peds, and vehicles with metadata

Particle system

Table	Purpose
respoon_particles	Particle instances placed in rooms
respoon_particle_effects	Particle effect metadata (dictionary, effect name, category)

Scene director

Table	Purpose
respoon_frames	Named snapshots of entity configurations within a room
respoon_frame_entities	Per-entity overrides within each frame
respoon_scene_state	Room's current scene playback state

Task system

Table	Purpose
respoon_task_sequences	Reusable task sequences (movement, animation chains for peds)
respoon_entity_tasks	Assignments linking entities to task sequences

Animations

Table	Purpose
respoon_animation_dicts	Animation dictionaries (~1,000+ entries)
respoon_animation_clips	Individual animation clips within each dictionary

Entity library

Table	Purpose
respoon_entity_library	User-saved entity configurations (custom peds/vehicles) for reuse

System

Table	Purpose
respoon_migrations	Migration tracking -- records which migrations have been applied

---

Seed data

The model catalogs are seeded on first boot with approximately 317,000 rows of data:

Category	Approximate count
Animation clips	269,000
Props	21,000
Particle effects	2,800
Peds	1,100
Vehicles	921

This data powers the entity browser, animation picker, and particle effect selector in the editor UI.

---

Purging the database

If you need to completely remove all Respoon data, a purge.sql script is included in the data/ folder of the release. Run it manually against your database:

SOURCE /path/to/resources/respoon/data/purge.sql;

This drops all respoon_ tables. Use with caution -- all rooms, entities, and saved data will be permanently deleted.