SillyTavern 扩展 ImmersiveWorlds：为聊天提供持久世界模拟

A city that keeps living between messages.

SillyTavern extension that gives a chat a persistent world:
clock, weather, places, people with routines, items, factions and open threads.

Install · Usage · Token cost · Settings · Status

Why it exists

A lorebook is a dump. A roleplay city is a simulation: time passes, weather shifts, people have jobs and routines, a shop exists once you mention it, and the next reply already knows the street you are standing on.

Immersive Worlds keeps that state in the chat and gives the model a short scene brief each turn. It never writes your character's words, thoughts or choices.

What you get

• Immersion HUD in the empty space beside the chat: the scene top-left (place, time, weather, what is happening right now), the people here top-right (2–3 state tags each; hover for body, mind and what they hold), items bottom-left, and a map of the places around you bottom-right
• Only what your character knows: strangers show as "a dock guard" until someone says their name; next door is seen through an open way, heard through a door ("two voices arguing") or blank behind a wall; Peek through a door; a setting widens it to everything nearby or everything (secrets too)
• World logic in code: every path has a walking time, moving follows the paths and costs that time, people walk instead of teleporting ("heading to the Waystone"), time only jumps when the story sleeps, waits or travels, and new things appear only where the story is
• Living world per chat, created only when you ask for one (chats without a world cost nothing)
• Build world: one background call drafts places, people, items, factions and threads from the character card, scenario and lorebook. Start seeds a minimal world with no model call
• Background director after each reply: clock, weather, ambient line, who moved where, new people/places/items the scene implied, chronicle notes
• Routines (dawn / day / dusk / night): people move with the clock, even off-screen
• Swipe-, regenerate- and delete-safe: every reply caches its own world patch, so browsing swipes re-applies the right state with no extra call, and deleting a reply rewinds the world
• Panel in SillyTavern's own style (MovingUI, theme colours, wand menu): World, People, Items, History, Manage
• Status strip above the chat input (day, time, weather, place) and an optional time-of-day tint
• Forge world-consistent people on demand; turn anyone into a character card with a world lorebook
• Export / import world JSON; slash command and macros
• Background calls run through a Connection Profile of your choice (a fast, cheap model is ideal), with reasoning switched off by default and a 120 s timeout

Built for adults. Any resemblance to real persons or places is coincidental.

Install

Requirements: SillyTavern ≥ 1.18.0 (tested on 1.19.0) and any API SillyTavern already speaks.

Extensions → Install extension → https://github.com/SenjuWoo/ImmersiveWorlds

or

cd SillyTavern/public/scripts/extensions/third-party
git clone https://github.com/SenjuWoo/ImmersiveWorlds.git

Optional companion: Immersive Adventures (RPG rules, combat, inventory). When both run, the world owns time and place and the adventure owns the hero.

Usage

1. Open a chat, then wand menu → Living World (or /iw).
2. Build world (AI draft) or Start (minimal, no call).
3. Roleplay. After each reply the director updates the world in the background; the HUD follows.
4. HUD: hover or click a face for the full card; click an item for its details; click a place on the map for Go (walks there, time passes) or Peek (through a door, 1 minute). Click the place name to open the panel. Arrivals glow green, departures fade with where they went.
5. Panel (wand menu): People: Inspect, Forge, Add, Make card. World: travel by clicking an exit. Manage: Update now, Edit identity, Rebuild, Export / Import, Remove.

The HUD needs free space beside the chat (wide windows, or a narrower Chat Width in User Settings). With little space it shrinks to faces and icons; on phones it steps aside for the status strip and panel. A side hides while SillyTavern's drawer on that side is open.

Macros: {{iwTime}} {{iwDay}} {{iwWeather}} {{iwLocation}} {{iwScene}}.

Token cost

Measured against v1.5.0 on the same world:

The scene brief sits at depth 1 (In-chat @ depth), so everything above it, including the whole chat history, stays prompt-cacheable.

Settings

Extensions → Immersive Worlds. The panel's Manage tab has the two most-used toggles.

Log

The browser console (F12 → Console) always shows [Immersive Worlds] v2.1.0 ready and every failure with its cause. Turn on Debug log in the settings for the resolved settings at startup, every director pass, and every move or change the world rules rejected (with the reason); it logs at the Verbose level, so enable that level in the console filter.

Project map

manifest.json   SillyTavern manifest (loading_order 6, activate hook)
index.js        host: settings, per-chat world, injection, director pipeline, panel, commands, macros
engine.js       pure world model: schema, patching under the rules, scene brief, prompts
rules.js        pure: paths with walking time and openness, shortest routes, time caps, people in transit
senses.js       pure: what the user's character perceives (the HUD's view), Peek
hud.js          the floating HUD
llm.js          background calls (Connection Profile → ChatCompletionService → generateRaw), JSON parsing
kit.js          shared panel kit (identical in Immersive Adventures)
settings.html   settings drawer
style.css       shared kit block + ambient tint + HUD
tests/          node tests/selftest.js

State lives in chat metadata key immersive_worlds_state_v1; v1 and v2 worlds load unchanged (paths get walking times, people already shown by name stay known).

Honest status

Verified:

• node tests/selftest.js — 55 tests: paths and walking time, rejected moves, people in transit, time caps, creation only where the story is, state only for people present, perception per path openness and reveal mode, names and threads hidden until known, Peek, migration, prompt sizes
• End-to-end in an isolated SillyTavern 1.19.0 against a mock model: HUD in all four corners at 1920, 1600, 1500 and 1280 px; hover cards; arrival glow and toast; a heard room, Peek and Go; a two-hop move charged its walking time; a bogus move rejected and logged; a person walking in over time; a drawer hiding its side; reveal modes; delete rewinding the HUD; no unknown name or secret in the default HUD; world note ~590 chars, director ~3,100 chars
• Reload persistence of the world and the HUD; Forge, Make card and swipe browsing were verified in 2.0.0 (their host code did not change; not re-run this round)

Not claimed:

• Director quality against every real model (it was exercised against a mock; the JSON parser is tolerant of fences and prose)
• SillyTavern 1.18 at runtime (the newer APIs used are feature-detected)
• The HUD re-laying itself on a live window resize was checked with a synthetic resize event (the test browser pane does not fire real ones)

License

MIT