Questions, answered
by lamplight.

Heartmorrow is a single-player dating & life simulator that runs on your own computer. You step into a world (a small town full of original characters) and grow relationships by going on dates, texting on an in-game phone, hanging out, giving gifts, working, and watching the town's social life unfold around you.

What makes it unusual: the characters are powered by an AI language model you connect yourself. Every line they speak and every read on how a date is going is generated live, so you type whatever you want instead of picking from a menu. Underneath, a strict rules engine turns those conversations 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.

Heartmorrow is entirely single-player and local-first. It runs on your machine with a local database; there's no multiplayer and no account. By default, your data never leaves your machine.

There are only two exceptions, and both happen when you choose them: connecting a third-party LLM provider sends that provider the game content needed to generate replies, and exporting your worlds or characters creates files you can share with other people. Exported files stay on your machine unless you send or upload them yourself. If you use a local model and don't share your exports, your characters, saves, conversations, art, and API keys all stay on your computer.

It's a grounded, character-driven, slow-burn romance: warm, hopeful, and low-stakes, with no magic or sci-fi. The built-in example worlds are a cozy arts district (“The Lumen Quarter”) and a coastal university town with an annual Star Festival (“Asterfall Bay”). Characters are diverse, original adults (the game refuses to save anyone under 18).

Adult content is an optional toggle that's off by default, and even when it's on it depends on your chosen model being willing to write it.

Three things:

• It's fully conversational. You talk in your own words and characters respond live and in-voice, not from a branching script.
• Dates are judged on two layers. A live “vibe” warms or cools turn by turn as you talk, and a separate end-of-date pass weighs the moments that actually mattered. Effort and attentiveness count, and a bad date can cost you ground.
• It's a creator tool too. You can author your own characters and whole worlds, share them as files, and run everything locally.

There's no forced ending; you can keep living in a world as long as you like. Taking a romance all the way (living together, deeply close, and calm) earns a once-per-relationship epilogue in the Endings gallery, but it's a soft win: you keep playing afterward and can pursue others if you want.

Nothing, if you use the self-contained installer: it sets up its own official Node.js and the right tools automatically, all kept in one folder with nothing added to your system. If you'd rather use your own tools, you need Node.js 20+ and pnpm.

To actually talk to characters you'll also want a language model (local or a cloud API), but you don't need one just to install, explore the UI, and create characters.

Easiest path (no prerequisites). Windows: run the installer once, then run the app.

# Windows
powershell -ExecutionPolicy Bypass -File .\install.ps1
.\run.bat

# macOS / Linux
./install.sh
./run.sh

Manual path (if you already have Node 20+ and pnpm):

pnpm install
pnpm seed     # creates the sample world
pnpm dev

Either way, open http://localhost:5173 in your browser. The installers are safe to re-run anytime.

Not today. It runs as a local web app: a small local server plus a page that opens in your browser. The installer sets that up and launches it for you. A true standalone desktop installer is a future idea, not something that ships yet.

No, not at this time. Heartmorrow currently runs on your own machine rather than on a hosted website. A hosted version that you can play online might be available in the future.

Heartmorrow has been tested on Windows, macOS, Linux, and Android (via Termux). It will run on any operating system or platform with a compatible Node.js environment. On Windows use install.ps1 / run.bat; on macOS and Linux use install.sh / run.sh. For Android, run the Linux installer in Termux, then play in the phone's browser. On these tested platforms, the installer fetches the matching Node build automatically.

Everything lives in a single data folder, created the first time you run, with your save and any uploaded art inside it. All your worlds live in there, and each world keeps its own money, inventory, and persona. To back up your game, copy the whole data folder.

If you ran the seed, you land on the World Selector with one ready-made sample world. Click Enter to jump in, or Start new to build your own. Starting a new world walks you through four quick steps: set the scene (blank, clone an existing save, or let the AI conjure a whole world), create your persona (name, pronouns, gender, sexuality, and an “about you” note, saved per world), optionally import people from your other worlds, and a welcome screen. Then you're in: head to Date (or Around Town to meet people first) and start talking.

You need some working model, and that part is mandatory, because Heartmorrow has no brain of its own. Until a working model is connected, dates and texts won't generate at all. But you do not need a top-tier one. Heartmorrow includes adapters for a variety of local servers and hosted providers, and ships configured for a free local model.

Think of model quality as a spectrum, not a gate:

• A stronger model writes characters who feel more like themselves, avoids chatbot tics and repetition, and judges your dates more sharply (in both directions).
• A smaller / local model still works, but is likelier to loop, repeat itself, misjudge a moment, or occasionally fail to produce valid output.

If dates ever feel too easy, too generous, or “off,” connecting a better model is the most direct fix.

Choose the adapter that matches your model server or hosted provider:

• OpenAI-compatible: services that expose the OpenAI Chat Completions API, including llama.cpp, vLLM, and compatible hosted APIs.
• LM Studio (native): LM Studio's own API, with richer model listing and real speed stats.
• Ollama (native): Ollama's own API, with an in-app switch for the model's thinking (including its depth, on models with levels).
• KoboldCpp (native): KoboldCpp's text-completion API, with a chat-template picker (Alpaca, ChatML, Llama 3, Vicuna, Mistral, or plain) to match the loaded model.
• Anthropic: Claude (needs an API key).

Some servers work through more than one adapter. Their native adapters expose extra controls and richer diagnostics when available.

Yes, but only through each provider's API (a pay-as-you-go API key), not a consumer subscription. A ChatGPT Plus, Gemini Advanced, or Claude Pro plan won't work, because those don't grant API access. Choose the appropriate supported adapter in Model & diagnostics and enter that provider's API key.

One caveat: these hosted models are safety-tuned, so they won't write adult/NSFW content and will refuse it even with the adult-content setting on. For that, use a local uncensored model instead.

Yes. Run a model locally with LM Studio, Ollama, llama.cpp, or vLLM and point Heartmorrow's server address at it. Local servers usually need no API key, it's free, and all content stays on your machine. The trade-off is that quality and speed depend on your hardware: smaller models are more likely to repeat themselves or judge oddly.

Open Settings (you can reach it from the World Selector, before you even enter a world) → Model & diagnostics. Pick a provider, set the server address, paste an API key if it's a hosted service (a dummy value is fine for local servers), choose a model (type it or press Load models), then press Test connection. A green result means you're ready. Your API key stays private on your own machine.

Any modern instruct/chat model in roughly the 7B-30B range (Qwen, Llama, Mistral, Gemma families, etc.) is a good fit. Our personal pick is Gemma 4 26B A4B (it punches above its weight and is fast on a modern rig), and the Qwen 3.x series works well too. Smaller models can start producing nonsense, so be careful below that range. That said, if you're low on resources, we've tested it with models as small as Gemma 4 E4B Q8 and it still works.

Two tips:

• Give reasoning models room. Raise the response length (max tokens 2048 or higher) so replies don't get cut off mid-response.
• Turn reasoning OFF if your model supports it. In practice it doesn't improve results here and makes every reply much slower. (On the native Ollama option there's a switch for this right in Settings.)
• For adult content, an abliterated / uncensored model is recommended; a safety-tuned one may refuse even with the setting on.

Yes. In Settings you can give certain jobs their own model: the Judge (relationship scoring) and Vision (reading uploaded portraits) can each use a different model, while everything players read uses your main one. A common setup is a small fast local model for the judges and a premium model for the dialogue.

It's a testing tool (Settings → Bench) that runs about 40 sample scenarios through the game's real prompts with your model: dialogue tests watch for looping and repetition, judge tests compare the model's verdict to a known-good answer, and generator tests check the output is valid. It shows speed and quality stats, and you can save runs to compare models side by side. It's a great way to pick a model without playing through the game.

No. The AI writes the words and proposes small, bounded changes, but the game engine owns all the actual numbers (rapport, affection, money, energy, the clock, stock prices, who-met-whom in the background) and works them out consistently. The AI is not allowed to invent stats or outcomes, and nothing touches your save until it has been double-checked. So a weak model can't “cheat” your progression; it only shapes tone and judgment within limits the engine clamps.

If the server is unreachable you'll get a clear message like “Couldn't reach the AI endpoint… make sure your model server is running, then check Settings → LLM,” and the date/text won't go through; nothing in your save changes.

Garbled or failing dates are usually a smaller model struggling to format its responses the way the game needs. Heartmorrow already retries and auto-adjusts the output format to fit pickier servers, but a weak model can still fail; try a larger model, run it through the Bench to see where it trips, and make sure max tokens is high enough.

Each in-world day you spend a small budget of energy on activities (go on a date or a casual hangout, spend low-key Together time, play a minigame, or work a shift) while texting people for free. You meet people Around Town, build relationships toward dating and commitment, earn and spend money, and when your energy runs out you Sleep to start the next day and read a recap.

Energy is your daily action budget: 3 actions on a weekday, 4 on a weekend. Anything that's a real, in-person event spends it: a date, a hangout, a Together outing, a minigame, or a work shift (most cost 1; the heavy outdoor day-labor shift costs 2; stepping into a place Around Town costs 1). Texting is always free. When energy hits zero, sleep to refill.

There's no real-time clock. The time of day (morning → afternoon → evening → night) moves forward as you spend energy, so the world visibly darkens as your day fills up. To advance, press the day button in the status bar: it reads End day while you still have energy and Sleep once it's spent. Either way it carries you to the next morning, refills energy, and shows a recap of the day plus what happened around town. (You can't end the day mid-date or mid-hangout; finish or leave it first.)

Starting broke is intended; there's no allowance or daily handout. Open the Work app and take a shift: a steady reliable shift, swingy “odd jobs,” or the big day-labor payday (2 actions, priced by the weather, unlocks after you've built some skill). Two jobs are played as quick skill minigames (The Woodlot and The Copy Desk) and pay you for how well you play. The more you repeat a kind of work, the better you get and the more it pays. The only money that arrives on its own is stock dividends, in worlds that have a stock market.

By default a new world starts you as strangers, so unmet people appear as “???” in your People list. Go to the Around Town tab (it lists the places in town and who's out right now), step into a place (this costs 1 action), and introduce yourself in plain language (“I head over and say hi”). Once you've both introduced yourselves they're revealed, and you can date or text them. Prefer to know everyone from the start? Turn off “Start as strangers” in Settings.

Where people are shifts with the time of day and their routines. Folks are out in the morning/afternoon/evening; at night almost everyone's home unless a place has nightlife. Someone with a job is at work during their shift, and regulars haunt the same spots. Try a different time of day or come back tomorrow, and remember browsing Around Town is free; only stepping inside costs an action.

No. Texting is completely free and unlimited. Open Messages and anyone you've met or dated is in your contacts; you can even attach a photo or a gift. (Note: unprompted texts you receive only come from people you've really met — shared a date, a hangout, or a proper introduction; total strangers never text first.)

Your phone is a home screen of apps. Always there: Messages, Mail, Faces (a town feed), Moments (a per-person scrapbook), Constellation (a social star-map), Endings, Almanac (calendar), Weather, Together, Work, Shop, Games, Bag, and Settings. Three money apps only appear in worlds whose creator switched them on: Property, Market (stocks), and Casino. If you don't see one, this world simply doesn't use it (that's intended, not a bug).

Two kinds, both costing 1 energy. Most (Memory Match, Heartbeat Serenade, Lore Quiz, Sweet & Sour, Timing Meter, Read Between the Lines) are played with a character to grow your bond, and each person has a favorite, built from their own likes and goals. Two others (The Woodlot, The Copy Desk) are money-only jobs that pay for how well you play. You can't play while you're out on a date or hangout.

Open the Date tab and tap Plan a date. First choose what kind of meet-up it is, a proper date or a casual hangout (see the next question), then pick who (their card shows if they're free today) and where: Anywhere quietly puts you at a free public spot; for a date you can also pick a specific venue (some cost money, charged only when the date ends), a place you own or lease (free), or, once you're close, their private room. Then just talk: type whatever you want and they reply live. Finish with End & evaluate to score the night (costs 1 energy). If you start a date but never send a message, Cancel date throws it out for free.

A hangout is the same free-form conversation with the date apparatus switched off: nothing scores you turn by turn, there's no live vibe to crater, nobody walks out or loses interest, and you can't define the relationship over one. It's low-stakes time together, and it's always free (only free spots are offered), though it still costs 1 energy like any real outing.

It still counts, though: how the evening went shapes how they feel about you afterward, and a hangout counts as really meeting someone, so it unlocks texting the same way a first date does.

On two separate layers:

• A live read. While you talk, each message you send is judged for how engaged, warm, attentive, and genuine it is. There's no coasting (flat, forgettable lines drift the vibe down), and warmth is harder to build than to lose. If the vibe craters, the character loses interest and leaves.
• An end-of-date judge. When the date ends, a separate pass re-reads the whole evening and adjusts your relationship for the moments that mattered: real connection and vulnerability lift it; hitting a known dislike, crossing a boundary, or being cold or pushy cools it. It doesn't re-punish a merely dull date; that was the live layer's job.

A single date rarely moves any one feeling more than a handful of points. You see a word like “warming to you” or “a bit awkward,” never a number. How hard all of this lands is tunable with the Date difficulty setting (next question).

Yes: the Date difficulty setting in Settings has three levels, Gentle, Normal, and Harsh. It never changes what characters say, how the judges read your messages, or where a date's vibe starts; what it scales is the consequences: how far the vibe moves on each message, how much patience a character has for a date that's going badly, and how strongly the end-of-date judge's read lands. Gentle softens setbacks and lets good moments carry further; Harsh makes warmth slower to earn and easier to lose. It applies to dates and hangouts (never texting), and you can change it anytime — it simply applies from the next message on.

Usually it's the sum of low-effort or mismatched messages, not a fixed grudge. The vibe starts neutral and you have to earn it upward; careless lines cost more than nice ones gain, and flat lines nudge it down. On top of that, each date the character is quietly hoping for something (to be listened to, some levity, real depth, to feel wanted, a bit of spontaneity, or to be eased in slowly), and ignoring that, or hitting a dislike, cools things fast.

Spend real, attentive time with them. On dates, put genuine effort into every message: listen, ask real questions, be warm and a little vulnerable, and read what they seem to want that night. Off dates, text thoughtfully (small but steady), do Together activities, play their favorite minigame, and give the occasional well-timed gift. Don't disappear; warmth slowly decays if you neglect someone. Closeness is the average of five feelings, so it climbs gradually.

They're probably guarded. Guardedness is a character trait: guarded people open a date cooler and warm up more slowly, so you have to genuinely impress them, but they cool at full speed like everyone else. Easy to lose, hard to win. Patience, attentiveness, and not rushing intimacy matter most. (Newly created characters are mildly reserved by default.)

The first five are the warm feelings a character holds toward you; they average into your overall warmth, which names your stage: near-strangers → acquaintances → warming up → getting close → close → sweethearts. Tension is the cold one: it builds from awkward, careless, or hurtful moments and works against you (high tension blocks intimacy even when warmth is high). You don't see raw numbers in normal play, just the stage label and the date's vibe.

Once you're warm enough, a Define the relationship action appears on a date, in three rungs: Ask them out (Dating, unlocks at getting close), Become exclusive (at close), and Move in together (at sweethearts). You have to actually talk on the date first and can only climb one rung at a time. They might say yes (a milestone!), gently deflect (no harm, but they just won't revisit it for a few days), or, if you ask way too early, be put off, which spikes Tension and ends the date.

You can date as many people as you like. A monogamous character who's grown to care about you may find out and take it badly: a small sting while things are casual, but a painful betrayal once you're exclusive or living together, and worse still if they catch you with their ex, crush, or rival. Polyamorous characters are open about loving more than one person and don't get jealous.

Often, yes. Uncommitted relationships never break up outright (they just cool from neglect). A committed one goes “on the rocks” first (a “we need to talk” text and a few days to turn it around with a good date), and a single catastrophic date can end it on the spot. After a breakup there's a cooling-off period, then you can win them back by staying in touch and rebuilding warmth. Each breakup leaves a scar that makes the bond a little more fragile next time.

It's an orientation thing, and it's strictly opt-in. If you've set your gender and sexuality and a character's orientation clearly rules you out (a straight/gay mismatch), the bond can still grow into a friendly acquaintance but won't cross into the romantic stages. This only triggers for a clear-cut mismatch; if you leave orientation unset, or either of you is bisexual, non-binary, or unspecified, nothing is gated. When such a pairing levels off, the character may warmly share their orientation and gently decline romance.

Yes. Once you've met someone, that sticks. Dates form lasting memories (the end-of-date judge writes down the moments that mattered), which roll up into a per-relationship narrative the character references later, and the Moments app is a scrapbook of your milestones and keepsakes with each person. Only a deliberate progress reset erases it.

Two different things. If you're hostile or cruel, or come on crudely with someone you're not close to, the character may walk out, a real setback they remember. Separately, if the vibe craters (low-effort, going-nowhere messages), they lose interest and politely call it a night. Either way the date is still scored and still costs energy. Read the room and ease off if things cool.

Constellation is a star-map of every relationship in your world, with you at the center and threads to everyone you've met; tap anyone for a Person Dossier: their circle, what's happening in their life, and what they've heard about you through the grapevine.

The town also runs a quiet simulation each day (when you sleep): characters meet, fall in and out with each other, and spread news. Two compatible, unattached people can develop a crush that becomes a couple (“Spark”); clashing pairs can fall out into rivals (“Souring”); and people you've dated may text you gossip about news involving their friends: happy if it's a friend, bitter if it's an ex. Neglect a real love-interest for about a week and another character can even pair off with them. The town changes slowly and never overrides relationships an author set by hand.

A little. A gift is a small, thoughtful nudge (never more than a few points), not a shortcut, and the same gift can delight one person and bore another. They can't be spammed: the first gift you give someone in a day lands in full, a second that day lands at about half, and a third or more does nothing. Buy them in the Shop and give them on a date or attach one to a text.

Three of them are optional and per-world, all off by default: Property, the Stock Market, and the Casino. A world's creator turns them on in the World editor's Game features section; if one's off, its phone app simply doesn't appear (and the server blocks access entirely). The people-and-utility apps (Messages, Mail, Faces, Together, Moments, Constellation, Almanac, Weather, Work, Shop, Games, Bag) are always available.

Switch to Creator mode (Settings → Mode), open the World editor, and under Game features tick the system you want. When you enable the Casino you can also set its limits: the largest single bet and the most a player can wager in a day. Save, and the app shows up on the phone.

The Casino has slots, blackjack, roulette, and video poker, played with your real in-game money. It's deliberately not an income source: the house keeps an edge, and per-bet and daily-wager caps mean a bad streak can't wipe you out in one sitting. Treat it as risk and flavor. The only hands-off income in the game is stock dividends.

In the current version of the game you add portraits by uploading your own image. In Creator mode, open a character in the editor and use the image picker to upload a portrait (plus optional per-expression faces, so the right look shows during a date). Heartmorrow does not currently generate images. There's a separate, reverse tool (“generate a character from an image”) where a vision model reads a picture you upload and drafts the character's written details from it.

Yes. Turn on Creator mode (Settings → Mode), then use the character editor, which has five tabs (Identity, Personality, Profile, Relationships, World). Fill everything in by hand, or let the AI draft a whole character from a reference image, a block of text, or both (this needs a connected model). New characters start at the minimum age of 18 and belong to the world you're in. Social links connect only people who share the same world. You review and edit every field before saving.

Yes, in Creator mode. Use Start a new world for a guided four-step setup, or the World editor for full control over summary, tone, lore, in-fiction rules, notes, and locations. Hand-write everything or use Generate with AI to conjure a setting and draft locations. This is also where you flip the optional Property / Stock Market / Casino systems on or off.

Heartmorrow packages your creations into a single share file you can hand to anyone or keep as a backup. Look for Export and Import buttons on the world list (for whole worlds) and on the People page (for characters); it works in either Play or Creator mode.

• To export: hit Export, pick the worlds and/or characters to include, add a title and an optional note, and download the file. When you export a world you can choose whether its cast comes along (untick to share just the world and its locations).
• To import: hit Import and choose a share file. You get a read-only preview of exactly what's inside (worlds, people, and image counts) before anything is added. Importing is always additive: it makes fresh copies and never overwrites or deletes what you already have. If a file holds both worlds and people, you can take just the worlds or bring the whole cast.

There are three file types: .hmchr (one or more characters), .hmwrld (a whole world with its locations, notes, and cast), and .hmpack (a bundle of worlds plus loose characters). Share files carry the creations and their images only, never your save, relationships, money, or history. One thing to watch: if you export a world but leave out a character that others are linked to, those connections are dropped on import, so include the people whose ties you want to keep.

Yes. Heartmorrow’s source code is released under The Unlicense and dedicated to the public domain. You are free to copy it, modify it, fork it, redistribute it, use it commercially, or build something entirely new from it without asking permission. There are virtually no restrictions on what you can do with the Heartmorrow code.

If you develop a new feature or a cool idea and want to contribute it back to the game, we’d be happy to take a look at your pull request.

Third-party libraries and assets remain subject to their own licenses, and the software is provided as-is without a warranty.

No. Unsaved edits in the character editor, the world editor, and the first step of new-world setup are auto-saved as drafts on your device. When you come back, the editor offers to restore the draft (it won't silently overwrite anything), and the People page shows an “unfinished drafts” strip. Drafts are local to your browser, separate from your actual save.

Play mode is just living in a world: dating, texting, working. Creator mode adds the building tools: the character and world editors, the World and Debug tabs, and in-place generate/edit/delete controls. You flip between them under Mode in Settings; it's a per-device preference, not part of any world's save, and it isn't shared when you export.

It's a global setting that's off by default and requires confirming an age acknowledgment. Even with it on, intimacy is still earned: it only becomes possible once you're genuinely close and things are calm (low tension), and it always stays within the character's stated boundaries. It also depends on your model being willing to write it (an uncensored model is recommended). And yes, your dating skills are still evaluated; turning it on isn't a bypass.

No. The reset in the phone's Settings Danger zone wipes only your playthrough (relationships, memories, conversations, texts, emails, and inventory) and returns you to Day 1 with your starting money. Everything you authored survives: your worlds, characters, notes, shop items, and uploaded images. It's a clean slate for playing, not for building.