{"id":51319993,"url":"https://github.com/study8677/dameng-qiangu","last_synced_at":"2026-07-01T12:03:40.595Z","repository":{"id":363538995,"uuid":"1263798520","full_name":"study8677/dameng-qiangu","owner":"study8677","description":"AI-native historical interactive fiction game about pre-Qing figures, built with Vite, React, TypeScript, Zod, and OpenAI structured generation.","archived":false,"fork":false,"pushed_at":"2026-06-09T11:06:02.000Z","size":73,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T11:12:48.704Z","etag":null,"topics":["ai-game","branching-narrative","chinese","chinese-history","github-pages","historical-game","history","interactive-fiction","openai","react","story-game","typescript","vercel","visual-novel","vite","zod"],"latest_commit_sha":null,"homepage":"https://study8677.github.io/dameng-qiangu/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/study8677.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-09T09:22:17.000Z","updated_at":"2026-06-09T11:06:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/study8677/dameng-qiangu","commit_stats":null,"previous_names":["study8677/dameng-qiangu"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/study8677/dameng-qiangu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/study8677%2Fdameng-qiangu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/study8677%2Fdameng-qiangu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/study8677%2Fdameng-qiangu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/study8677%2Fdameng-qiangu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/study8677","download_url":"https://codeload.github.com/study8677/dameng-qiangu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/study8677%2Fdameng-qiangu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35005413,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-game","branching-narrative","chinese","chinese-history","github-pages","historical-game","history","interactive-fiction","openai","react","story-game","typescript","vercel","visual-novel","vite","zod"],"created_at":"2026-07-01T12:03:39.735Z","updated_at":"2026-07-01T12:03:40.587Z","avatar_url":"https://github.com/study8677.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Dameng Qiangu\n\n[English](README.md) | [简体中文](README.zh-CN.md)\n\n[![Deploy GitHub Pages](https://github.com/study8677/dameng-qiangu/actions/workflows/deploy.yml/badge.svg)](https://github.com/study8677/dameng-qiangu/actions/workflows/deploy.yml)\n[![CI](https://github.com/study8677/dameng-qiangu/actions/workflows/ci.yml/badge.svg)](https://github.com/study8677/dameng-qiangu/actions/workflows/ci.yml)\n![License](https://img.shields.io/badge/license-MIT-1c524c)\n![React](https://img.shields.io/badge/React-19-61DAFB?logo=react\u0026logoColor=white)\n![TypeScript](https://img.shields.io/badge/TypeScript-6-3178C6?logo=typescript\u0026logoColor=white)\n![OpenAI](https://img.shields.io/badge/OpenAI-Structured%20Outputs-111827)\n\n**AI-native historical interactive fiction.** Enter the dreams of great pre-Qing historical figures, make hard choices at the turning points of their lives, and create your own shareable dream levels with AI. Creators can start from the official cast or define a custom pre-Qing historical figure.\n\n[Play the live demo](https://study8677.github.io/dameng-qiangu/) · [Read the architecture](docs/ARCHITECTURE.md) · [View the roadmap](docs/ROADMAP.md)\n\n![Dameng Qiangu preview](docs/assets/social-preview.svg)\n\n## Why It Is Different\n\nMost AI story products feel like chat. Most interactive fiction tools require a lot of authoring work. Dameng Qiangu sits between them:\n\n- AI generates structured `DreamLevel` data, not executable code.\n- A deterministic game engine owns nodes, choices, stats, endings, and sharing.\n- Official dreams are hand-authored, so the game is playable without any AI proxy.\n- User-created dreams stay in `localStorage` by default and can be shared through compressed URL links.\n- The theme is intentionally focused: great historical figures before the Qing dynasty.\n\n## Gameplay\n\nThe MVP ships with six official dreams:\n\n| Figure | Era | Official dream |\n| --- | --- | --- |\n| Confucius | Spring and Autumn | `Apricot Altar: Asking Ritual` |\n| Qu Yuan | Warring States | `The Waking Soul at Miluo` |\n| Zhuge Liang | Three Kingdoms | `The Last Lamp at Wuzhang Plains` |\n| Li Bai | Tang | `Drunken Moon over Chang'an` |\n| Yue Fei | Song | `Iron Cavalry at Wind-Wave Pavilion` |\n| Wang Yangming | Ming | `The Heart-Lamp at Longchang` |\n\nEach dream has 5-7 nodes, 2-4 choices per node, five mutable stats, and at least three reachable endings. Every choice now produces an immediate story consequence called **Echo of the Last Thought**, so different routes feel more dramatic even before the final ending.\n\n## AI Dream Creator\n\nCreators choose an official figure or define a custom pre-Qing historical figure, then set the theme, tone, length, and extra notes. The Vercel API proxy asks OpenAI for strict JSON and the frontend validates the result with Zod before saving it.\n\nThe AI is limited to:\n\n- pre-Qing historical figure dreams,\n- official or custom historical figures,\n- structured `DreamLevel` JSON,\n- playable branching nodes and endings,\n- narrative text only, never executable logic.\n\nWithout a configured AI proxy, players can still play official dreams and save a local sample dream.\n\n## Tech Stack\n\n- **Frontend:** Vite, React, TypeScript, Tailwind CSS\n- **Validation:** Zod schemas for all dream data\n- **Sharing:** `lz-string` compressed URL hash payloads\n- **AI proxy:** Vercel Serverless Function + OpenAI Responses API Structured Outputs\n- **Testing:** Vitest and Playwright\n- **Hosting:** GitHub Pages for the static app\n\n## Quick Start\n\n```bash\nnpm install\nnpm run dev\n```\n\nRun the main checks:\n\n```bash\nnpm run build\nnpm run test\nnpm run lint\nnpm run test:e2e\n```\n\n## AI Proxy Setup\n\nThe frontend never stores an OpenAI API key. Deploy `api/generate-dream.ts` to Vercel and configure:\n\n```bash\nOPENAI_API_KEY=your_openai_key\nOPENAI_MODEL=gpt-4o-mini\nALLOWED_ORIGIN=https://your-github-username.github.io\n```\n\nThen set the frontend variable:\n\n```bash\nVITE_AI_PROXY_URL=https://your-vercel-project.vercel.app/api/generate-dream\n```\n\nFor GitHub Pages, add `VITE_AI_PROXY_URL` as a repository variable so the deploy workflow can inject it during build.\n\n## Project Structure\n\n```text\napi/generate-dream.ts        # Vercel AI proxy\npublic/covers/               # Official SVG cover art\nsrc/App.tsx                  # Hash-routed app shell\nsrc/data/dreams.ts           # Official dream levels\nsrc/data/figures.ts          # Historical figure catalog\nsrc/lib/game.ts              # Deterministic game engine\nsrc/lib/schemas.ts           # Zod schema contracts\nsrc/lib/share.ts             # URL sharing codec\nsrc/lib/storage.ts           # localStorage persistence\ntests/unit/game.test.ts      # Engine/schema/share tests\ntests/e2e/app.spec.ts        # Core browser flows\n```\n\n## Roadmap\n\n- **V1:** Supabase login, public dream plaza, likes, collections, moderation states.\n- **V1.5:** Creator pages, remix flow, graph editor, quality scoring.\n- **V2:** More pre-Qing figures, hidden endings, achievements, figure traits.\n- **V3:** Creator marketplace, monetization experiments, full moderation workflow.\n\n## Contributing\n\nGood first contributions:\n\n- Add a new pre-Qing official dream.\n- Improve the mobile reading experience.\n- Add validation for edge-case dream graphs.\n- Expand Playwright coverage for sharing and creation flows.\n- Improve English translations for the official dreams.\n\nRead [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.\n\n## Community\n\n- [Roadmap](docs/ROADMAP.md)\n- [Architecture](docs/ARCHITECTURE.md)\n- [Changelog](CHANGELOG.md)\n- [Security](SECURITY.md)\n- [Code of Conduct](CODE_OF_CONDUCT.md)\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstudy8677%2Fdameng-qiangu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstudy8677%2Fdameng-qiangu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstudy8677%2Fdameng-qiangu/lists"}