DOCSEARCHbyAlgolia
Submit Docs

ADV.JS Text Adventure Game Engine

repository·dev·Indexed 43 days ago

https://github.com/yunyoujun/advjs

A Markdown-based text adventure game engine designed for the AI era, allowing Agents to generate projects that humans can refine in a local editor and deploy as Web games. Version 0.1.1 includes a Studio for project management, a Story Market powered by CloudBase, and support for iOS native templates via Capacitor.

Tokens
312.3K
Snippets
882
Records
1.5K
Agent score
56%

What's inside ADV.JS

  1. Overview of ADV.JS CLI commands

    dev

    The adv CLI provides a suite of tools for developing, building, exporting, and interacting with ADV.JS projects.

    Core Commands:

    • adv / adv dev: Start a local development server with hot reloading.
    • adv init: Initialize a new project from a template.
    • adv build: Build a production-ready Single Page Application (SPA).
    • adv export: Export the interactive experience as a video.
    • adv config: Merge configurations into a single JSON file.
    • adv play: Interactive narrative player (supports manual and AI Agent modes).
    • adv check: Validate scripts, characters, and scenes (includes auto-fix capabilities).
    • adv context: Export project context for AI usage.
    • adv debug: Perform branch graph and coverage analysis.

    Global Options:

    • -t, --theme: Override the theme.
    • --lang: Set language (en or zh-CN).
    • -v, --version: Show version.
    • -h, --help: Show help information.
    adv [command] [options]

  2. Overview of ADV.JS Studio Capabilities

    dev

    ADV.JS Studio is an interactive narrative creation platform designed to transform raw materials into playable scenarios. It provides a full suite of tools for managing, editing, and generating interactive content.

    Core Capabilities:

    • Project Management: Uses IndexedDB for offline-first persistence and supports cloud synchronization via COS.
    • Content Editing: Full CRUD operations for Characters, Chapters, Scenes, Audio, Locations, and Knowledge Bases using a Markdown editor.
    • AI Features: Supports streaming responses, memory, group chats, diaries, and timelines via multiple providers. Includes image generation, TTS (4 providers), and Embedding retrieval.
    • Material Import: A 'Source-to-Project Pipeline' that converts text, Markdown, chat logs, PDFs, or URLs into complete interactive projects.
    • Game Preview: Immediate playability via GamePlayer with touch-based page turning and chapter panels.
    • Distribution: One-click export to .advpkg format.
    • Multi-platform: Responsive design supporting Desktop, Mobile, Capacitor, and PWA (offline).

  3. Overview of Flow Demo

    dev

    Flow is a game demonstration built using a node-based format. It is designed to showcase how game logic or sequences can be constructed via nodes. Key features include:

    • Node Generation: Node information can be generated using a dedicated node editor.
    • Runtime Loading: The system supports loading these node configurations dynamically during runtime.

  4. Overview of available scenes in ADV.JS

    dev

    The ADV.JS engine uses scene files to define different environments or narrative settings. The following scenes are currently available in the template:

    SceneFilePurpose
    学校 (School)school.mdCH01 Main Scene
    学校天台 (School Rooftop)school-rooftop.mdCH02 Main Scene
    神社 (Shrine)shrine.mdCH03 Summer Festival Main Scene

    Note: This file is intended for AI context and is not read by the engine itself. To use a scene, reference its corresponding .md file in your project configuration.

  5. Overview of ADV.JS Design Architecture

    dev

    ADV.JS is designed around several specialized modular systems. The architecture is divided into core functional domains to handle different aspects of the engine's lifecycle. Developers can explore specific design implementations for the following modules:

    • Resource System: Manages assets used within the engine.
    • Audio & AI Voiceover System: Handles sound playback and AI-driven voice generation.
    • Storage System: Manages data persistence and state.
    • Character Management System: Handles character definitions and lifecycle.

    Note: As the project is in active development, design drafts are frequently updated. For architectural proposals or feedback, users are encouraged to participate in the project's Discussions or Discord.

  6. Overview of @advjs/flow

    dev
    The @advjs/flow package is designed to decouple the logic required for a flow editor. It provides the underlying logic and state management necessary to power visual flow-based editing interfaces, separating the core execution and structural logic from the UI implementation.

  7. Overview of ADV.JS Product Ecosystem

    dev

    ADV.JS is a Markdown-based text adventure game engine designed for the AI era. It allows Agents to generate standard projects, which developers can then refine, playtest, and build using a local Editor, before deploying them as shareable Web games.

    The ecosystem consists of four main components:

    • advjs: The core engine, compiler, and CLI.
    • @advjs/editor: A local or online editor optimized for PC creation. It supports integration with Skills, MCP (Model Context Protocol), and other Agents.
    • @advjs/studio: A mobile-optimized, account-based SaaS designed for lightweight creation and public AI credit usage.
    • ADV.JS Skills: Workflows for generation, debugging, review, art, and adaptation that can be installed by Agents (e.g., Codex, Claude Code, Cursor).

    Note: Both the Editor and Studio use the same Markdown project format and Runtime.

  8. Overview of the ADV.JS Ecosystem

    dev
    ADV.JS is envisioned as a modular ecosystem for ADV (Adventure) game development. The project is structured into several key categories: core NPM modules, plugins, editor tools, and themes. Developers can leverage the core modules for script parsing and client-side rendering, or extend functionality using specialized plugins like Babylon or Live2D.

  9. Overview of AI Creation File Formats

    dev

    ADV.JS uses a set of Markdown-based files to provide context for AI-driven storytelling. These files complement existing .adv.md and .character.md files to form a complete world-building system.

    Key Concept: These files are for creation context only. The engine does not depend on them (e.g., README.md, world.md) during runtime; they are intended for AI and human authors to maintain consistency.