Getting Started

Getting Started

Tutorial. For new players. You need Node.js 20+ and an MCP client. By the end, you'll be running your own game server — freeform roleplay, or the rulebook of your choice.

How it works

You type what you want to do. The AI narrates the result. The engine enforces the rules behind the scenes. You never need to know what a tool is called. You say "go north" or "look at the altar" and the world model resolves where you are and what you can see. Build a ruleset and you add dice, combat, and character mechanics on top.

Prerequisites

1. Node.js 20 or newer.

   node --version

   Get it at nodejs.org if you don't have it.

2. An MCP client. Opencode, Claude Desktop, Continue.dev, or Cursor. Holonovel is built and tested with DeepSeek on Opencode Go.

3. This repository. Clone it or download it — you need the holonovel/ directory.

   git clone ssh://git@git.gay/flukeatzerocool/Holonovel.git

Source: README.md §1, §2 (install and how it works).

Install the holonovel server

cd Holonovel/holonovel
npm install
npm run start

That's it. The server is running. It gives you the world model — rooms, things, exits, parser commands — plus narrative tools and campaign persistence. No rulebook required: you can start freeform roleplay right now.

To play a specific system, run the Build workflow from your rulebook — D&D 5e, Starfinder, or any game you own. See Building a Server.

Connect your MCP client

Add this to your MCP client's config. For Opencode, that's ~/.config/opencode/opencode.json:

"holonovel": {
  "type": "local",
  "command": ["npx", "tsx", "src/index.ts"],
  "cwd": "/path/to/Holonovel/holonovel",
  "environment": {
    "TTRPG_NOVEL": "default"
  },
  "enabled": true
}

Replace /path/to/Holonovel/holonovel with the actual path on your machine.

Restart your MCP client. The server's tools, resources, and prompts should appear in your client's tool list. If you don't see them, check the client's connection logs — the server logs handshake details on startup.

Source: README.md §1 (config example verified against live holonovel server).

Your first session

Open a fresh conversation. Your AI now has access to the world model and narrative tools. Here's what you say:

"Start a new game called the Dragon Tomb."

The AI creates a Novel — a persistent save file on disk. Everything that happens next — characters, scenes, NPCs, combat — lives in that file and survives every server restart and rebuild.

"Create a character. A half-elf rogue."

The AI walks you through character creation step by step. Answer the prompts. When it's done, your character is permanent — stored in the roster, importable into any future game.

"Put on my Player badge. Let's play."

The Game Master badge is the AI narrator. The Player badge is you. Badges are enforced server-side — switch to Player and GM secrets vanish. You can always switch back to GM with "Put on the Game Master badge" if you need to fix something. Or switch to Observer badge to let the AI run the whole table while you watch.

Your AI Game Master answers. You're playing.

Source: spec §1 (play model), spec §5.5 (badges and access), README.md §2 (Novel, Character, Badge).

What next

• Playing the Game — dice, combat, looking up rules, character sheets
• Game Mastering — building worlds, running encounters, NPCs and lore
• What Holonovel Is — the architecture and why it doesn't break

See also

• FAQ — common setup problems and solutions

Last updated: 2026-10-12.