{"id":29269036,"url":"https://github.com/kingyosun/gestaloka","last_synced_at":"2026-05-19T06:03:07.656Z","repository":{"id":299642775,"uuid":"1003104808","full_name":"KingYoSun/gestaloka","owner":"KingYoSun","description":"🎭 GESTALOKA - Auto-updating Shared World Text MMO | LLM-based dynamic narrative generation system where   player action histories (logs) appear as NPCs in other players' worlds","archived":false,"fork":false,"pushed_at":"2025-06-28T12:10:41.000Z","size":3541,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-28T12:23:26.720Z","etag":null,"topics":["ai-story-generation","dynamic-narrative","fastapi","graph-database","llm-game","multiplayer-rpg","react-typescript","text-game","text-mmorpg"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KingYoSun.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-16T16:20:38.000Z","updated_at":"2025-06-28T12:10:44.000Z","dependencies_parsed_at":"2025-06-18T10:33:11.607Z","dependency_job_id":null,"html_url":"https://github.com/KingYoSun/gestaloka","commit_stats":null,"previous_names":["kingyosun/logverse","kingyosun/gestaloka"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/KingYoSun/gestaloka","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KingYoSun%2Fgestaloka","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KingYoSun%2Fgestaloka/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KingYoSun%2Fgestaloka/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KingYoSun%2Fgestaloka/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KingYoSun","download_url":"https://codeload.github.com/KingYoSun/gestaloka/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KingYoSun%2Fgestaloka/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263611900,"owners_count":23488429,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-story-generation","dynamic-narrative","fastapi","graph-database","llm-game","multiplayer-rpg","react-typescript","text-game","text-mmorpg"],"created_at":"2025-07-04T20:07:00.907Z","updated_at":"2026-05-19T06:03:07.650Z","avatar_url":"https://github.com/KingYoSun.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GESTALOKA v2\n\nGESTALOKA v2 is a same-world narrative MMO rebuild. The canonical store is PostgreSQL, world memory is retrieved through vector-friendly search, graph updates flow through an outbox projection pipeline, and every player/NPC action lives inside one `world_id` namespace.\n\nThe runtime is now being cut over from a single built-in setting to an engine/core plus declarative world packs model. The repo ships with one bundled shared-world reference pack (`gestaloka_reference` / `nexus_foundation`).\n\n## Repository layout\n\n- `backend/` FastAPI modular monolith for the v2 slice\n- `frontend/` player React client for login, world start, and turn play\n- `admin-frontend/` separate React admin client for pack, user, LLM, prompt, SP, and release management\n- `documents/` v2-only docs and ADRs\n- `packs/` bundled declarative world packs and templates\n- `prompts/` prompt registry inputs for the model router\n- `tests/` backend and E2E coverage for the new slice\n- `rebuild_plan_v2.md` current rebuild plan and design reference\n\n## Quick start\n\n1. Copy `.env.example` to `.env`.\n2. Start the stack with `docker compose up --build`. The default stack does not run the Playwright E2E service, so manual play state stays isolated from automated smoke runs.\n3. Open `http://localhost:5173`.\n4. Open `http://localhost:5174` for the admin surface after login.\n5. Open `http://localhost:3001` for Langfuse trace browsing.\n6. Sign in with the demo Keycloak user:\n\n```text\nusername: demo\npassword: demo-password\n```\n\n## Verification\n\n- `PYTHONPATH=backend pytest tests/backend` verifies the backend slice directly.\n- `make build-frontend` is the official frontend build path. It runs inside Docker/Compose instead of the host shell.\n- `make frontend-e2e` is the official full-stack Playwright smoke path. It enables the Compose `e2e` profile, runs the Playwright smoke specs under `tests/e2e/`, waits for `backend` / `player-frontend` / `keycloak` readiness, and cleans the stack afterward.\n- `make verify-v2` is the canonical local and CI verification entrypoint. It runs backend tests, v1 terminology checks, pack checks, shared-world regressions, the containerized frontend build, and the containerized E2E smoke in order.\n- `GET /worlds/packs` exposes the bundled pack and template catalog used by the session bootstrap UI.\n- `make pack-export` and `make pack-import` move validated external world packs as `.tar.gz` artifacts; see [World Pack Operations](documents/world-pack-operations.md).\n- Host `npm run build` remains a convenience path only. In mixed WSL/Windows environments it is non-authoritative and may fail even when the Compose verification path is healthy.\n\n## Initial public interfaces\n\n- `GET /health`\n- `GET /auth/me`\n- `GET /economy/sp/me`\n- `GET /worlds/packs`\n- `POST /sessions`\n- `POST /turns`\n- `GET /worlds/{world_id}/events`\n- `GET /worlds/{world_id}/memories`\n- `WS /ws/sessions/{session_id}?token=\u003caccess_token\u003e`\n\n## Internal ops interfaces\n\n- `GET /ops/projection/status`\n- `POST /ops/projection/rebuild`\n- `GET /ops/worlds/{world_id}/graph-summary`\n- `GET /ops/sp/overview`\n- `GET /ops/sp/ledger`\n- `POST /ops/sp/adjustments`\n\n## Admin interfaces\n\n- `GET /admin/overview`\n- `GET /admin/packs`\n- `GET /admin/world-templates`\n- `GET /admin/users`\n- `GET /admin/settings/llm`\n- `GET /admin/model-lanes`\n- `GET /admin/prompts`\n- `GET /admin/sp/overview`\n- `GET /admin/release`\n\n## Notes\n\n- The graph projection path is outbox-driven. The standard compose stack now targets NebulaGraph, while lightweight test settings still use the recording backend.\n- Runtime stabilization for NebulaGraph includes an init step that registers the storage host before backend and projection worker start.\n- LLM observability uses self-hosted Langfuse for prompt/generation/retrieval/eval traces, while OpenTelemetry remains the infra/metrics layer.\n- The container-first verification targets (`make frontend-e2e`, `make verify-v2`) override model execution to the local `stub` provider and disable telemetry exports so verification does not depend on external AI or observability runtimes.\n- The canonical embedding policy is fixed in [ADR-001](documents/adr/ADR-001-embedding-policy.md).\n- Sessions start from a selected `pack_id` and `world_template_id`, then bootstrap a pack-defined starter location and projected `KNOWS` relation between the player and guide NPC.\n- SP is an execution-budget ledger for API/runtime cost only. It is not an in-world currency and does not buy quest, faction, or item power.\n- Successful requests consume SP, business-failed requests refund in-request, and the admin frontend inspects execution budget separately from world progression.\n- Reward items stay inside world progression through deterministic pack-defined world rules instead of purchase mechanics.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkingyosun%2Fgestaloka","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkingyosun%2Fgestaloka","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkingyosun%2Fgestaloka/lists"}