heartmorrow

Heartmorrow — Local-First AI-Powered Dating Simulator 💞

Heartmorrow is a fully local dating + world simulator powered by your own language model. You build the cast and the world they live in, then live a relationship sim in your browser: go on dates with streamed, in-character dialogue, text back and forth on an in-game phone, play minigames, shop for gifts, and watch relationships grow, drift, define themselves, or fall apart across a living in-game calendar.

Everything runs on your machine. The browser never talks to the model — it talks to a small local server, and that server talks to the endpoint you point it at: any OpenAI-API-compatible server (LM Studio, Ollama, llama.cpp, vLLM, etc.), one of the native LM Studio / Ollama / KoboldCpp connections, or hosted Anthropic with an API key. Your characters, saves, art, and API keys never leave your computer.

No model? No problem to start. You can install, seed, create characters, upload art, and explore the entire UI without an LLM connected. You only need one running to actually talk to characters and simulate the world.

Hop in the Discord if you want to share your characters, get pro-tips, and discuss the game with others.

Why you’d want to play

It’s a dating sim where the people feel authored by humans and improvised by a model - not a rigid, branching script. You write who they are; the model gives them a voice; and a strict rules engine turns every conversation into real, persistent consequences. Charm someone and their friends warm to you. Neglect them and they cool, text you “we need to talk,” and eventually leave. Make it official and the whole social web reacts. Then keep playing - there’s no forced ending.

What you can do

🗓️ Live an in-game life

A repeating 112-day year (4 seasons × 28 days, each season starting on a Monday) with morning → afternoon → evening → night phases, a day-of-week, and four fixed annual holidays — First Bloom (Spring), Midsummer Night (Summer), the Lantern Festival (Autumn, the most romantic night of the year), and the Long Night (Winter) — that color the calendar, the social feed, and your dates.

• Energy economy. Each day gives you a small action pool — 3 actions (4 on weekends). A date, a hangout, a work shift, time spent with someone (Together), and a minigame each spend one — the heaviest shift takes two — while texting is always free. Time-of-day phases aren’t just decor — they advance as you spend energy, get pinned as hard facts in date scenes, and gate when characters’ texts arrive. When you’re out of energy, Sleep to end the day: you get a written recap, the day’s events around town, and a fresh morning with new weather. Money isn’t handed out — you earn it from work and minigames (or from wealth holdings you own).
• Deterministic weather + moods. Every world day has forecastable weather (browse a 5-day forecast in the Weather app), and every character has a mood of the day plus weather they love or hate — which nudges how a date goes.

💬 Go on dates

Pick a character and a place, then have a real, streamed conversation, one message at a time. The model stays in character (no chatbot tics, no “happy to help”), and on a genuine first date they break the ice instead of making you message a stranger.

• Read the room. Optional intent chips (Flirt, Tease, Open Up — plus Reassure and Apologize when there’s tension) let you signal how you mean a line. They never move a stat by themselves; they make the moment land — or backfire if you misread it.
• See how it’s landing. A live rapport trajectory bar (“warming to you,” “a bit awkward,” “losing interest”) and a reactive portrait that shifts expression in real time tell you, without numbers, exactly how you’re doing.
• Real stakes. Each character secretly wants something from the evening; read it well and you’re rewarded. Be hostile or proposition crudely and they can walk out; let the vibe crater and they’ll quietly make an excuse and leave early.
• Save-safe scoring. When you end a date, a separate validated pass turns the whole evening into relationship changes, a mood, and memories — and a flat or hurtful date won’t help you. Start a date but never speak and it simply doesn’t count.
• Or take the stakes off. A hangout is the same live conversation with the date apparatus switched off — no turn-by-turn scoring, no walkouts, no defining the relationship. It still ends with an honest read: memories form and the quiet stats (comfort, trust) grow, because people fall for each other on dates, not by killing an afternoon.
• Pick your difficulty. A Gentle / Normal / Harsh setting scales how hard consequences land — never what characters say or where a date opens, only how far your wins and missteps move things.

Dates are server-truth: refresh or switch tabs and the exact conversation auto-resumes.

❤️ Grow (or break) relationships

Every bond tracks seven dimensions — affection, trust, chemistry, comfort, respect, curiosity, and tension. Five of them average into warmth (closeness), which climbs through six stages: near-strangers → acquaintances → warming up → getting close → close → sweethearts.

• Define the Relationship. A player-driven ladder — Ask them out (Dating) → Become exclusive (Exclusive) → Move in together (Living together) — unlocked at rising warmth. The character actually decides: they can accept, deflect, or backfire on a badly-timed ask.
• Milestones fire when you cross into a new band - a banner, a keepsake memory, a next-morning text, and a ripple through their social circle.
• Breakups & reconciliation. A committed relationship that’s neglected, too tense, or hit by a catastrophic date goes “on the rocks” (a warning and a few days to fix it) and can break up. You can also end things yourself (with a confirmation, so a joke doesn’t blow up your relationship). A broken-up partner goes cold but can be won back on a deliberate reconciliation date — though every breakup scars the bond.
• Happy endings. Take a romance all the way (living together, sweethearts-level, calm) and earn a once-per-relationship epilogue in the Endings gallery. It’s a soft win - you keep playing and can pursue others if you want!

📱 Use the in-game phone

A whole home screen of apps:

• Messages — text anyone you’ve actually dated; they text you between dates (and rarely send a gift to claim). You can start texts, attach a photo (read by a vision model), or attach a gift from your bag.
• Faces — a living social feed where the whole cast posts about their day and big news, comments on and reacts to each other based on who likes whom, and where you can post too.
• Mail — a read-only inbox of in-world mail from companies and strangers — though someone you’ve dated may send a postcard home while they’re away.
• Almanac — a season calendar with weather, holidays, and a per-day record of what happened.
• Weather — today’s sky, a forecast, and how each character feels about it.
• Constellation — a touch star-map of every relationship in the world: you at the warm center, threads out to everyone you’ve met, colored by the kind of tie.
• Moments — a polaroid scrapbook of your relationship highlights.
• Endings — your gallery of earned epilogues.
• Work — a job board of flat shifts and playable skill jobs; four career skills (Service, Hustle, Craft, Knowledge) level up with use, raising pay and unlocking heavier work.
• Together — give an afternoon to someone: time spent grows a bond, but who they are (fit), how bold the outing is (risk), and how often you’ve leaned on them that day (a daily cap) all shape it — and casual time alone never reaches the romantic bands, only a real date does.
• Settings — accent colors, wallpaper, play/creator mode, and a total reset.
• Plus optional, world-gated money apps (Property, Market, Casino — see below) and quick access to Shop, Games, and your Bag.

🎮 Play nine minigames

Six bonding games grow your bond while earning a little money: Memory Match, Timing Meter, Lore Quiz, Sweet & Sour, Read Between the Lines, and Heartbeat Serenade. Each is graded S → F, and the grade scales your payout (relationship stats, dating stats, and money). They’re built from the character’s actual likes, goals, and boundaries - so you’re literally testing how well you know them - and a good play leaves a real reaction and a remembered moment. (Memory Match’s board even grows as you get closer, and playing someone’s favorite game — picked by their strongest trait — lands warmer.)

Three more are skill jobs in the Work app, paid purely in coin: swing on the beat at the Woodlot, transcribe the day’s dispatch cleanly at the Copy Desk, and haggle scrounged goods at the Flip — where buyers hide a walk-away price, their tells honestly hint at it, and you pocket only the margin above what a piece is worth.

🛍️ Shop, gifts & inventory

Buy gifts, consumables, and trinkets from the world’s catalog with your per-world purse. Items can boost a relationship stat, permanently raise a character’s base dating stat, grant a temporary buff, set a story flag, or give/cost money. Your Bag is a viewer — you give gifts in person on a date or by text, and the character reacts in their own voice based on their authored likes, dislikes, and love language. The same rare gift can delight one person and bore another.

🧠 A world with memory

Dates produce memories that roll up into a per-relationship narrative chronicle the character references later. A hand-authored social graph (friends, rivals, exes, family, partners) plus an off-screen world-sim means the cast knows each other:

• Gossip spreads. Word about you and about the cast travels NPC-to-NPC (getting a little garbled each retelling) and reaches you as gossip texts and feed posts.
• Named jealousy. A monogamous partner can find out you’ve been seeing someone else — and if that someone is their own ex or rival, it stings far more.
• Recognition & vouching. A friend you meet later might recognize you (“wait, you’re the one Mara mentioned?”), and making things official ripples warmth through that person’s friends and family — and chills their rivals.
• Anniversaries are remembered. A full season after a first date — or the commitment that replaced it — the character texts you that morning, the Almanac marks the day with a heart, and taking them out that evening is worth extra.

💰 Optional money systems

Work and Together (time spent with people) are always on. Each world’s creator can also switch on three richer, opt-in systems (all OFF by default) — and, the other way around, can switch Mail or Faces off for a world where they don’t fit: the app vanishes from the phone and nothing is generated (or spends tokens) for it.

• Property — lease in-world places (rent comes due on a real schedule; come up short and the landlord’s eviction clock starts) or buy them outright, then date somewhere you hold for a relationship buff — a free venue, with owned places giving the full lift and leased ones half.
• Stock Market — trade shares of fictional in-world companies whose prices drift daily — and a company linked to a character even reacts to your relationship with them.
• Casino — four games of chance (Slots, Blackjack, Roulette, and Video Poker), kept honest by a real house edge and strict per-bet and per-day wager caps so it can’t become a money engine.

Every money move and every random draw is computed on the server — the client can never grant itself a cent.

🎨 Bring your own art & author your cast

• Upload portraits plus per-expression face variants (happy, shy, hurt, etc.) so the right face shows during a date.
• Author characters and worlds in full editors: identity, personality, likes/goals/ boundaries, dating stats, connections, employment, weather tastes, locations, lore, and content/feature flags.
• Let the model help. Roll a set of dating stats, draft the narrative profile, or — with a vision-capable model - draft an entire character from an uploaded portrait, fitted to your world’s tone. You review and edit every field before saving. (Image → text only; Heartmorrow does not currently generate images.)

Requirements

Using the self-contained installer or Docker? You can skip the Node and pnpm requirements below — install.sh / install.ps1 download a pinned, local Node and activate the right pnpm for you, and the Docker build brings its own. The only thing you’d still want is an LLM server to actually play.

• Node.js 24+ — the server uses Node’s built-in node:sqlite (stable, flag-free on Node 24), so installation never compiles a native C addon.
• pnpm — the repo pins [email protected] via packageManager, so running corepack enable once will fetch the right version automatically (or npm i -g pnpm).
• (Optional, but basically needed to actually play) an OpenAI-API-compatible LLM server, either local or a cloud API.

Quick start

The fastest way in is the self-contained installer. It needs no prerequisites — not even Node or pnpm. It downloads a pinned, official Node.js into a local ./.runtime/node folder (verified against nodejs.org’s SHA-256 checksums, nothing installed system-wide), activates the exact pnpm pinned in package.json via corepack, installs dependencies, and seeds the sample database. Then a matching run script starts the app.

macOS / Linux

./install.sh      # one-time setup (downloads Node locally, installs, seeds)
./run.sh          # start the server + web client

Windows

powershell -ExecutionPolicy Bypass -File .\install.ps1   # one-time setup
.\run.bat                                                # start the app

Unattended/CI? Pass -y/--yes to install.sh (or -Yes to install.ps1), or set HEARTMORROW_YES=1, to skip the Node-download confirmation prompt.

📱 Works on Termux, too. The Linux installer runs as-is under Termux on Android — ./install.sh then ./run.sh — so you can host Heartmorrow right on your phone and play it from the device’s browser. (Point it at a local or remote LLM the same way you would anywhere else.)

Both installers are idempotent — re-run them anytime; they skip the Node download if the vendored copy is already present.

Then open http://localhost:5173.

Manual install

Already have Node.js 24+ and pnpm? Skip the installer and run the steps yourself:

# 1. Install everything
pnpm install

# 2. (optional) create a config file — sane defaults apply without it
cp .env.example .env

# 3. Seed sample data (1 world + notes, 3 characters, shop items, properties, companies)
pnpm seed

# 4. Run the server + web client together
pnpm dev

Then open http://localhost:5173.

Next steps in the app:

1. Open Settings (or the phone’s Settings app) and point Heartmorrow at your LLM — base URL, model name, etc. Use Test connection to confirm it works.
2. Tweak your player persona (name, pronouns) while you’re there.
3. Go to Date, pick a character and a location, and start talking. (First-use walkthroughs introduce the big systems as you meet them.)
4. Stuck on anything? The in-app Help tab is a full how-to-play field guide.

The Vite dev server proxies /api and /uploads to the API server on http://localhost:8787, so you only ever need to open the one URL.

Want a furnished demo? pnpm mock builds an isolated showcase world in data/mock (a separate save), and pnpm dev:mock runs against it — handy for screenshots without touching your real game.

Run only the API (no frontend)

If you just want the backend — to drive it from your own client, hit the HTTP API directly, or run headless — start the server package on its own:

# API with auto-reload (tsx watch), the way `pnpm dev` runs it
pnpm --filter @dsim/server run dev

# API once, no file watching (good for scripts / production-ish runs)
pnpm --filter @dsim/server run start

# Against the mock showcase world
pnpm --filter @dsim/server run dev:mock     # watch
pnpm --filter @dsim/server run start:mock   # no watch

The API listens on http://localhost:8787 by default (PORT / HOST in .env). No build step is needed — everything runs straight from TypeScript source via tsx. Without the Vite dev server you won’t get its /api and /uploads proxy, so call the API at its own origin and set CORS_ORIGINS to match wherever your client is served from.

Run in Docker

Prefer containers? A Dockerfile and docker-compose.yml are included. This needs no local Node or pnpm — only Docker — and bundles everything into a single container that builds the web client and serves it and the API from one process on one port.

docker compose up --build

Then open http://localhost:8787. (In Docker the API server serves the web client itself, so there’s just the one port — no separate :5173 like in dev.)

A few things worth knowing:

• Point it at your model. Your LLM runs on the host, not inside the container, so localhost from within the container is the container itself. docker-compose.yml pre-wires host.docker.internal — just set LLM_BASE_URL there to your provider’s port (LM Studio 1234, Ollama 11434, etc.). You can still change every LLM setting live in Settings afterward.
• Your save persists. The SQLite DB and uploaded art live in a named heartmorrow-data volume mounted at /data, so rebuilding the image keeps your game. Back up that volume (or swap it for a bind mount like ./data:/data) to back up your save.
• (Optional) seed sample data. A fresh container starts with an empty database. To load the sample world + characters into the volume:

  docker compose run --rm heartmorrow apps/server/node_modules/.bin/tsx apps/server/src/seed.ts
  

🔒 It’s bound to localhost on purpose. Heartmorrow has no authentication — anything that can reach the API can drive your game and read its data. The compose file publishes the port on 127.0.0.1 only, while the app listens on 0.0.0.0 inside the container. That is intentional: the container bind is not the same as the host bind; the published host port is the external boundary. Do not change the mapping to 8787:8787 unless you fully trust the machine and network. On Linux, Docker-published ports can bypass normal UFW/firewalld expectations, so do not rely on the host firewall alone to protect a published unauthenticated service.

Connecting your model

Heartmorrow works with any endpoint that speaks the OpenAI Chat Completions API, and ships native connections for a few favorites. Common choices and their default URLs:

Beyond the OpenAI-compatible mode, Settings offers native connections for LM Studio (richer model details and per-response speed stats), Ollama (a Thinking control — turn a model’s reasoning on or off, or set its depth), and KoboldCpp (a raw text engine; pick the instruction template that matches your loaded model — Alpaca, ChatML, Llama 3, and so on) — plus hosted Anthropic with an API key.

Configure it once in Settings — base URL, API key (usually a dummy for local servers), model name, an optional separate vision model, temperature, max tokens, the structured-output mode, and the live date-feedback cadence. API keys stay server-side and are never sent to the browser.

Tip: Reasoning models spend tokens “thinking” before answering. Give them room — 2048+ max tokens — or structured steps may run out mid-response.

How the rules & restrictions work

Heartmorrow is built so a small or unreliable local model can never corrupt your save or break the rules — and so heavier content is strictly opt-in.

The server owns every rule

Plain dialogue streams as free text. But every change to game state - relationship deltas, mood/expression, memories, summaries, minigame content - comes from a separate structured call that is validated before anything is persisted. The model and the client can only ever propose; the server computes and clamps the result.

The central callStructuredLlm helper:

1. Asks the model for JSON in your configured structured-output mode.
2. Parses strictly with JSON.parse - no regex extraction, no partial-JSON repair, no prose stripping.
3. Validates the result against a Zod schema.
4. On failure, re-prompts the model with a stricter repair prompt (the task, the schema, the validation errors, and its own bad output), lowering temperature each retry — and auto-downgrades the output mode (json_schema → json_object → prompt_only) if your endpoint rejects the format.
5. After the retry budget is exhausted, it fails safely — the caller does not mutate your save.

All stat changes clamp to 0–100, money is debited only when you can afford it, and prices, item effects, and minigame rewards are all computed server-side.

Content & safety gating

• Everyone is an adult. Characters must be 18+; the game refuses to save anyone younger, and AI-drafted characters are clamped to 18+. There is no in-game minor. Any PRs to change this will be rejected for obvious reasons.
• Orientation-aware romance (opt-in). If you set fully-specified, clearly incompatible orientations on both sides, romance simply won’t deepen past “acquaintances” — you can stay friendly, but dating, milestones, and intimacy won’t unlock, and the character gently says so. Anyone bisexual, non-binary, or unspecified is never gated.
• Intimacy gate. Intimate content is only permissible once you’re genuinely close (high warmth) and calm (low tension) — and only if you’ve turned on the adult-content setting and are using a capable model. Character boundaries always apply.
• Optional adult content (off by default). Yes, this can support adult content. But it is gated behind an explicit toggle, and the evaluator will still be active if you try to do this on dates… so your skills will still be evaluated.
• No AI image generation. You bring your own art, currently. A vision model can read an uploaded portrait to draft text; nothing in the app currently synthesizes pictures.

Recommended models

Any model that can reliably follow structured-output (JSON) instructions will work — since the endpoint is OpenAI-API-compatible, you can plug in almost anything. Modern instruct/chat models in the ~7B–30B range (Qwen, Llama, Mistral, Gemma families, etc.) are a good fit. For the optional adult content, an abliterated / uncensored model is recommended. Give reasoning models plenty of max tokens (2048+) so structured steps don’t get cut off.

My personal recommendation is Gemma 4 26B A4B. It works quite well for this and is fast if you have a modern rig. The Qwen 3.X series is also, of course, great, I have tested both Qwen 3.6 9B and Qwen 3.6 27B and they worked acceptably. Be careful with smaller models, though, the more likely they are to start providing nonsense. In the future, it would be interesting to try this with DiffusionGemma due to its high level of speed, but I haven’t personally tested it.

I also recommend turning OFF reasoning. Reasoning, in my experience with Gemma 4 and Qwen, seemingly has no improvement to this particular use case but makes responses take way longer.

Commands

Per-package: pnpm --filter @dsim/server run dev|start|seed|test|typecheck, pnpm --filter @dsim/web run dev|build|preview.

Configuration (.env)

All values are optional — defaults apply when unset, and LLM settings can be changed live from the in-app Settings page afterward. The .env only seeds the initial settings row. See .env.example for the annotated full list.

# Server
PORT=8787
HOST=127.0.0.1
DATA_DIR=./data
UPLOADS_DIR=./data/uploads
CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173

# Default LLM provider (seeds the initial settings row only)
LLM_BASE_URL=                       # blank until configured in Settings
LLM_API_KEY=lm-studio            # optional / dummy for local servers
LLM_MODEL=local-model
LLM_VISION_MODEL=                # optional; blank reuses the main model
LLM_TEMPERATURE=0.8
LLM_MAX_TOKENS=2048              # reasoning models need plenty of room
LLM_OUTPUT_LANGUAGE=auto         # e.g. ja, ko, zh-Hans, es, fr, de, ar, he, fa, ur
LLM_STRUCTURED_MODE=json_schema  # json_schema | json_object | prompt_only
LLM_ENDPOINT_MODE=chat_completions
LLM_MAX_RETRIES=3

# Web (Vite dev proxy target)
VITE_API_PROXY_TARGET=http://127.0.0.1:8787

Your save lives in DATA_DIR/dsim.sqlite and uploaded art in UPLOADS_DIR (both under ./data by default, created at runtime). Back up that folder to back up your game.

Make it your own

• Add a character → docs/ADDING_CHARACTERS.md
• Add art → docs/ADDING_ART.md
• Add a minigame → docs/ADDING_MINIGAMES.md
• Add a shop item → docs/ADDING_SHOP_ITEMS.md

The character and world editors can also ask the LLM to draft a profile, roll a set of dating stats, or build a whole character from a portrait — so you can go from idea to dateable character in a couple of clicks.

Project layout

packages/shared   Zod schemas, game types, stat defs, LLM/minigame/item contracts
apps/server       Fastify API, LLM adapters + structured caller, SQLite, game logic
apps/web          Vite + React client (responsive)
docs              Architecture + how-to guides
data/             Local SQLite DB + uploads (gitignored, created at runtime)

Why did I make this?

So many LLM games I see try to do too much (have the LLM drive the whole game state, which is fragile) or do too little (LLMs can only provide maybe some flavor text, but not much else) or just really aren’t much of a game and are just glorified chat interfaces.

I wanted to see if I could create something that is satisfying to play and actually provides enough fun side content that isn’t just chatting with AI. Plus, I just wanted to see how realistic I could get it feeling. I think I got something feeling pretty good here, I am regularly surprised by how well even weak models like Gemma 4 26B A4B can generate engaging and fun dates, even if it is brutally critical of your dating skills when it acts as the turn evaluator, lol. Additionally the living breathing world, while still a heavy WIP with rough edges, is pretty cool.

What is coming in the future?

I would like to continue improving the “world sim” aspect. Ideally the end state of this will be something so realistic you cannot really tell is actually just AI, let alone cheap local models. I think that will naturally happen as models improve, but I think there is a lot we can do to achieve that in the meantime.

Additionally, I would like to integrate image gen, video gen, TTS, etc. It would be really cool if it could generate images of the date as they play out, and have characters send you voice messages and what not. It’s all possible to do, I have just never wired any of it up.

Why am I an anonymous dev?

To be honest, I just do not want anyone to know that I made an AI dating simulator, especially not one that explicitly allows NSFW.

If you are interested in directly reaching out to me, please send me an email, which is on my GitHub profile.