Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tuturuuu.com/llms.txt

Use this file to discover all available pages before exploring further.

Hive is the Tuturuuu research satellite app at https://hive.tuturuuu.com. It uses the centralized Tuturuuu login handoff and keeps protected product APIs inside apps/web under /api/v1/hive/*.

​
Access Model

  • Production access requires a row in hive_members with enabled = true.
  • Platform admins are users whose platform_user_roles.allow_role_management value is true; they can create and manage Hive servers and Hive members.
  • V1 server policy is intentionally broad: every enabled Hive member can join every enabled Hive server.

​
Data Model

Hive stores shared world state as revisioned snapshots and events:
  • hive_servers
  • hive_world_states
  • hive_world_events
  • hive_npcs
  • hive_npc_memories
  • hive_npc_runs
  • hive_members
World edits should be persisted through apply_hive_world_event(...) so stale revision writes are rejected consistently. The actor-accepting RPC is a server-mediated write path only: direct browser roles must call the apps/web Hive API or Hive realtime service, and database grants should keep apply_hive_world_event(uuid, uuid, bigint, text, jsonb, jsonb) executable only by service_role. The function still derives auth.uid() for non-service execution and rejects actor mismatches as a defense-in-depth guard. The API maps RPC failures into explicit response codes, including hive_revision_conflict, hive_access_denied, and hive_server_not_found, so clients can distinguish sync conflicts from invalid edit payloads.

​
Editor Surface

apps/hive is a hidden-locale Next.js satellite app. The editor uses a full-bleed React Three Fiber viewport, a left server navigator, a bottom tool dock, a right inspector, and an NPC Lab panel for manual research runs. The editor is built on the shared @tuturuuu/satellite workspace shell. Hive uses that shell for collapsible left/right rails, top research overlays, and the bottom tool dock so satellite apps can share layout mechanics while keeping Hive-specific tool density and viewport behavior. Hive V1 keeps one editable world per server. Admins manage that world through server controls: creating a server creates its world, deleting a server deletes the world through database cascade, and clear/reseed actions persist typed world events against the current server snapshot. The 3D editor treats the voxel grid as the source of truth. Perspective comes from the camera and controls, not from rotating the editable world group. World edits should commit only after click/drag threshold handling so orbit, pan, zoom, placement, erasing, moving, and rotating do not conflict with each other. The toolbar opens with build tools only; block, object, system, and agent catalogs appear only while the Build tool is active. Gapless tile rendering is enabled by default and lives with time-of-day controls in the Settings dock tab. Manual morning, noon, afternoon, evening, and midnight modes use authored scene backdrops rather than a generic sky preset. Auto 24h mode advances a fast simulated day, shows the in-world clock in the summary overlay, and smoothly lerps scene lighting, fog, background, and cloud tint between themes. When a world edit fails because the local revision is stale, the Hive editor refetches the latest snapshot, rebases the intended edit once, and then either advances the revision from the successful response or shows a non-blocking sync notice. Client data access must go through @tuturuuu/internal-api helpers and TanStack Query. Do not add raw client fetch() calls in the satellite app.

​
NPC Research Runs

V1 supports manual NPC decision runs only. A run captures the current world, nearby entities, selected prompt mode, optional backstory, and active memories. The API persists the decision in hive_npc_runs, appends a typed npc.decision event, and lets realtime clients broadcast the result. Autonomous simulation ticks are intentionally deferred to a later phase.