World art direction

This page describes what the pictures for a world should look like, and what to check before you deliver them. It is written for the people who illustrate worlds: world authors, painters, and the people who maintain the built-in worlds. You do not need to know how to program.

It has three parts: how to set a direction for your own world, the direction set for each of the four built-in worlds, and how pictures appear in the world list (the gallery). For how to make the pictures, see Illustrate characters and Make scene pictures for a world.

Decide what the pictures are for first

A world's pictures have two jobs:

• When the player chooses a world, they show at a glance how the world is played.
• After the player enters the world, they make the characters, places, and rules look believable and consistent.

So different worlds should have different art styles. The four built-in worlds aim for the same level of finish, not the same way of drawing. When you set a direction for your own world, answer these four questions:

Question	Example
How is this world mainly played?	Dialogue and relationships; investigation and risk; repair and survival
What drawing style and which colors?	Clean anime line art, sea blue, mint green, cherry pink
How do the pictures mainly appear?	Portraits with transparent backgrounds plus scene pictures (stage view); character cards with an environment plus one cover (text narrative)
What must never be drawn wrong?	A character's injury is on the left arm; a building has three floors; a person is an adult

The answer to the last question is called an invariant: the things that must stay the same no matter how many times you redraw or how many variants you make. Write them down, and check them against each picture after you make it.

The direction of the four built-in worlds

The table below is the design position set from the genre and the pictures that already exist. It was not checked by player interviews or data, and it does not limit players by age, gender, or cultural background.

World	The play it conveys, and the players who will like it	Style and colors	How the pictures appear
遥风学园 (Harukaze Academy)	Dialogue, a slow-burning relationship, a group of characters, and the school festival. For people who like visual novels and everyday companionship	Clean anime line art, soft cel shading. Sea blue, mint green, and cherry pink. At night, blue-violet ambient light with warm lamps	Portraits with transparent backgrounds, and five fixed-camera scenes for day and night
雾港 (Mistport)	Clues, factions, risk, and the unknown. For people who like mystery investigation, dark fantasy, and exploration	Realistic painted harbor noir. Cold grey, blue-grey, old bronze, and rust. In the fog, near things are clear and far things disappear	Half-body character cards and one cover of a ruined harbor, with a text narrative
Emberback	Repairing facilities, cooperative survival, and time puzzles. For people who like science fiction exploration and technical adventure	Bright retro industrial science fiction illustration. Cream white, terracotta, and cobalt blue. Low-angle bright side light, with cool dark rim light	Adult full-body figures with their work environment, and one cover of a relay station, with a text narrative
提灯古冢 (Lantern Barrow)	Classic tabletop adventure and folk fantasy. For people who like tabletop role-playing	Realistic skin and worn cloth. Warm oil-lamp key light, cool rim light. Cold, damp late autumn	Full-body portraits with transparent backgrounds, a landmark diagram, and several scene pictures

Two reminders:

• The names and narrative setting of 雾港 do not mean that the existing faces must be replaced, or that everyone must be changed to period costume.
• Emberback's warmth, practicality, and sense of community are features of its genre. Do not turn it into a cold starship bridge, military uniforms, or neon just because it is "science fiction".

The archived Cloudmere and Neonridge are not in the current playable worlds. When they are listed again, check each one separately against its own setting.

Visual invariants for each world

遥风学园

• Characters are told apart by hairstyle, expression, and one prop: 澪's manuscript paper, 凛's interview notebook and camera, 夏帆's acoustic guitar, 悠真's glasses and folder, 遥's schedule book, 千寻's chalk and old books, 奏太's drumsticks, and 茜's book and dried flowers.
• Keep the navy school uniform with white trim, which has already been finalized, and each person's existing silhouette. In expression variants, do not randomly change to a sailor uniform or a suit, and do not randomly change hair accessories or bows.
• 千寻 is an adult teacher in her twenties, and the students are high school students. The content should be clean and suitable for teenagers, but this refers to the standard for the content, not to drawing the teacher as a student. She must keep her adult identity, her professional clothing, and her gentle, guiding posture.
• The daytime scene is the master version of the space. A night scene changes only the light, the sky, and the on or off state of the existing lamps. The position of the camera, the horizon, doors and windows, floors, bookshelves, the road surface, and props do not change. Do not automatically add rain because it is night.
• Fixed features of the five scenes: the club building always has three floors, a tiled roof, and climbing vines on the right side. The window desks in the classroom and the notebook in the foreground are in fixed positions. The mezzanine and the long table on the right of the library are fixed. The vending machine on the right of the seawall slope is fixed. In the shopping street, the bookshop and the flower shop are on the left, and the restaurant and the instrument shop are on the right.
• The background is there for the characters to perform in. The foreground and the area for the dialogue box must be clearly visible. A night scene keeps a middle level of brightness. Do not turn a gentle everyday scene into a thriller.

雾港

• The identity of a place comes from the fog that never clears, the cliffs, the three-level port city, the rising and falling tide, and materials eroded by salt. The distance that can be seen in a scene should be short. Far away, only blurred outlines hint at things.
• The city panorama on the promotional cover is an overview of the genre. It does not mean that a player can see the whole city clearly in the fog, and it is not a route map of the ruins.
• Show the face and one signature prop first. Black cloth needs layers. Do not press every face into darkness for the sake of "darkness", and do not let ornate spells take attention away from clues and characters.
• 铁姑's fog-erosion is below the elbow of her own left arm, and her right arm is normal. Do not treat "the left side of the picture" as her left. It is partly translucent grey fog, not ice armor, lightning, or a mechanical prosthetic.
• When 灰隼 goes down at low tide, the light he carries is a shielded, low-brightness cool glow of tide stone, not an open flame. The warm lights of the safe places in the city and the exploration gear must be kept distinct.
• At the start, 小霜's fog-erosion only lets light through occasionally at her fingertips. 齐老's hands are much more translucent. Do not draw everyone as the same glowing mage. The exact degree follows the character card.
• Use clothing to show identity: the strict guild, the old authority of the council, the practicality and wear of 盐牙, and the plainness of the Fog Walkers. Keep the differences in age and experience. Do not make everyone a generic beauty.

Emberback

• This is a planet that always keeps one face toward the sun. The bright side, the twilight band, and the dark side are areas of space, not time. Do not use the template of "a different sky for day and night". When a scene variant is needed later, prefer showing the state of storms, electricity, and communications.
• The identifying marks of the characters: Tomas's enamel mug and radio, June's scarf and car keys, Mina's spectrum analyzer. Keep each person's age, skin tone, face shape, and professional posture.
• What best expresses this world is: the ceramic heat shields of the relay station, equipment that has been repaired many times, analog gauges, six-wheeled crawler vehicles, and basalt landforms. Gears, armor, and space suits that have no use are not.
• The workshop, station yard, and observation deck around the characters are part of the character card. They are not transparent cut-out material for the stage. Do not cut out the environment just to make things tidy.
• Bright does not mean safe. Alarms, damaged equipment, the edge of a storm, and long shadows provide suspense, while the characters remain people that are easy to approach and part of a community.

提灯古冢

• Keep these: the village of 灰苇村, the northern burial mound, the ancient lamp at the mountaintop that has gone out, and the bronze tomb door standing open. A cold, damp late autumn, old bronze, and warm oil lamps are what set it apart from the cool tide-stone glow of 雾港.
• Keep the age, identity, and personality differences on the six character cards. 伊索德 is a woman in her seventies, 雷恩 is a nineteen-year-old apprentice priest, and 布兰诺克 is a fifty-year-old veteran.
• Full-body transparent portraits use the same frame size, similar figure size, and light from the same direction. The avatar and the stage portrait come from the same image.
• The landmark map shows only the rough relations between known places. It does not fix streets, distances, or the layout of the tomb that the source text does not write down. Lighting the lamp gallery is an exploration scene that may happen. It does not mean the lamps are already lit at the start.

Making and delivering pictures

1. Read the setting first, then look at the existing pictures. Read WORLD.md, the character cards, and data/dimensions.yaml. If a prompt in the manifest contradicts an existing picture, fix the contradiction. Changing only the text does not mean the picture is acceptable.

2. New characters and new places can be generated from the manifest. The shared art style description in the manifest only reduces drift in style. It does not guarantee that the same person looks the same, or that the same place has the same layout.

3. For a variant of an existing character, or another time of day for an existing scene, use the finalized picture as a reference. List each thing that must not change. The batch scripts in the repository generate from text only, and they do not read reference pictures.

4. Size. Character pictures are 1024x1536. Scene pictures are 1536x1024. A transparent portrait must have truly transparent pixels. A transparency channel that is fully opaque does not count. Painting a checkerboard into the picture does not count either.

5. Format. Portraits and scenes are stored only as WebP (lossy, quality 90, with a lossless transparency channel). The generation scripts write WebP directly. For a PNG made with another tool, convert it with the command below, and then delete the PNG. This needs cwebp installed on your computer.

   node scripts/encode-world-webp.mjs <file.png>...

6. Check each picture. View it at full size, view the thumbnail, place it on a light background and a dark background, check how it is cropped at phone width, and compare the day and night versions. The picture must not contain explanatory text, watermarks, or signs that have not been proofread. Text that must appear is best left to the interface to display.

7. Before you replace a finalized picture, keep the original or the Git history. After the chosen picture is put into the world package, regenerate the corresponding manifest. See the next section.

Some of the pictures finalized this round were made by "editing an image with an image": the night pictures of the five scenes in 遥风学园, and the corrections to the four character pictures of 雾港. Their full prompts and the reference picture versions used are recorded in the prompt record.

What to refresh when a picture changes

When a portrait or scene file changes (redrawn, replaced, or recompressed), the checksum recorded for it in the manifest is out of date, even if the picture looks the same. Regenerate it:

node scripts/emit-presence.mjs mistport
node scripts/emit-scenes.mjs haruka-academy
pnpm validate:world worlds/emberback worlds/mistport worlds/haruka-academy worlds/lantern-barrow

When all validation passes, each world prints one line:

✓ worlds/emberback/world.yaml
✓ worlds/mistport/world.yaml
✓ worlds/haruka-academy/world.yaml
✓ worlds/lantern-barrow/world.yaml

When you change a built-in world, run the picture-asset test again. It checks that every language of each world refers to the current pictures:

pnpm --filter @covel/server exec vitest run tests/lib/world-art-assets.test.ts

The gallery manifest gallery.json also records the checksum and size of each picture. It must be updated in the same way.

Some rules about files:

• Portraits and scenes keep only WebP. PNG files in these two folders are ignored by Git and are not committed.
• Do not compress a WebP that was already compressed with loss again. When you change a picture, convert it again from a source that was never compressed: the original generated image, or the PNG in the Git history.
• Gallery pictures are an exception: they keep the original PNG, with a WebP of the same name beside it for display. The desktop installer and the Docker image do not include the gallery PNGs. So every PNG in gallery.json must have a webFilename.

Cover

A world's cover is declared by two fields in world.yaml:

cover: media/gallery/world-cover.webp
accentColor: "oklch(72% 0.15 350)"

See the world data reference for the formats and lightness range of accentColor. Loading discards invalid colours, so the world still loads and the interface derives its default accent from the world ID. pnpm validate:world still reports an error for the author to fix. The interface also uses the default accent when stored metadata contains an unusable colour.

• cover is the path of one picture, and it must be in a folder under media/. The interface shows this picture directly. If a character picture in the world package is updated, the cover does not change automatically.
• If cover is not set, the interface uses the default background.
• If the cover fits the play and the quality is acceptable, you can keep using it.

Players see the pictures before the game starts

The pictures in a world package are shown before the player enters the game:

• The world detail page lists all the pictures.
• Some interface styles show scene pictures and stills in a full-screen background carousel, place the character pictures below the introduction, and let you click to see the original and its description.
• Some interface styles show a few avatars and the total number of pictures in the lower-left corner of the cover, and cycle through the scene pictures when the mouse hovers over the cover.

So every picture must be able to stand on its own. Do not put unfinished work into a world package.

Which pictures are shown, what they are called, and how they are described is decided by the gallery manifest below.

Gallery data and front-end use

The gallery is the group of pictures shown in the world list and the world details. It is decided by media/gallery.json in the world package. Translations go in the neighboring gallery.en-US.json or gallery.zh-CN.json.

This file is optional. In that case, the gallery lists the pictures in the public picture folders of the world package (portraits, scenes). It tells scene and character pictures apart by aspect ratio, and it has no names or descriptions. If you write gallery.json, you decide the order, the categories, and the description of each picture.

The gallery and the portraits and scenes in the game are two different things. Which portrait and which background are used in the game is still decided by the manifests of Portraits and Scenes. The gallery does not change any state in the game.

How the gallery uses this manifest

• It shows the pictures in the order of the manifest, up to 60.
• If webFilename is set, it shows that. If not, it shows filename.
• It shows only pictures whose spoilerLevel is opening or is not set. The gallery is seen before playing begins, so it does not show pictures that spoil the story.
• filename and webFilename must be written as "a one-level folder under media/ / file name", for example gallery/harbor.webp. Pictures written in any other form are not shown.
• When the manifest file itself is malformed, the gallery does not come out empty. It falls back to the "no such file" approach.

kind decides how a picture is used:

kind	Use
scene	Scene picture. It fills the screen in a carousel, and cropping removes one strip from the top and one from the bottom
still	Still from the story. Same as above
map	Map or landmark diagram. Shown only in full, and not part of the carousel
portrait	Character picture
hero	The world's own cover picture. A world with no built-in cover in the app (for example, a world a player installed) uses it as its opening picture

Fields of each picture record

Field	Meaning
id, kind	A fixed identifier, and the category from the table above
name, description	The name shown, and a short description of the picture
background	Background material. It must be traceable in the world text or the character card
storyContext	What story situation this picture fits, and what plot result must not be inferred from the picture
location, visualNotes	A place that is supported by evidence, and visual points confirmed by looking at each picture. Character cards may leave these out
relatedCharacters	IDs of related characters. Listing one does not mean that character must appear in the picture
depiction, spoilerLevel	Whether this is a character portrait, a setting illustration, a landmark diagram, or a moment that may happen, and how much it reveals
sourceRefs	Paths of the original setting material in the world package
filename, webFilename	The picture file relative to media/, and an optional WebP display version
width, height, sha256, bytes	The size, checksum, and size in bytes of the file named by filename
generation	An optional generation record: the tool used, the full prompt, and the reference pictures. It is not background material for players

The interface actually reads id, kind, filename, webFilename, name, description, background, location, and spoilerLevel. The other fields are editing material for the people who maintain the worlds.

Rules for writing descriptions

• The main file contains only text in the world's default language. Language files contain only translations, matched to the main file by id. Picture paths, character IDs, and checksum information are written only in the main file.
• Setting fields must be traceable to the source text. If the source does not say something, leave it empty. Do not fill in character relationships, backgrounds, ages, or plot results with "reasonable guesses".
• Composition, clothing, and appearance written in a prompt for the sake of the picture cannot be used as evidence for the world setting.
• Expressions, clothing, and day-and-night variants are described separately. Do not infer a relationship or an event from one person's expression.
• A still uses the original character portrait as the reference for identity. Do not write an activity in the picture as something that has already happened.
• When an existing picture has no reliable generation record, do not write generation. Do not pass off the creative intent in the manifest as an actual generation record.

What the built-in worlds have now

The gallery manifests of the four built-in worlds have 54 entries in total:

World	Entries	Content
遥风学园	25	Twelve character pictures (four of them are variants), ten day and night scenes, a cover, and a new literary-club scene and a still of 澪 proofreading
提灯古冢	11	Six character pictures, a home-page exterior picture, a diagram of known landmarks, and the tavern, the tomb door, and the lamp gallery
雾港	10	Seven character pictures, a cover, and a new waterfront passage and a still of 苏窈 appraising
Emberback	8	Three existing character pictures, a cover, and two new character pictures, and stills of 第十七里 and of Tomas monitoring

Of these, 35 entries are existing material that was checked picture by picture, and 19 are new.

• The existing portraits and scenes refer to their original files directly. They were not copied.
• The existing covers of 遥风学园, 雾港, and Emberback were copied unchanged to each world's media/gallery/world-cover.webp, and world.yaml's cover points to it. When you change a cover in future, also update the checksum information in the gallery manifest.
• The cover of 提灯古冢 points to media/gallery/lantern-barrow-hero.webp, which is the WebP version of its hero picture.
• The new banner pictures are 1536x1024 PNG files, each with a WebP copy.
• Maps are best shown in full. Scenes and stills should also be shown in full where possible. When cropping, keep the characters and the key props.
• The glowing waveform on the Emberback cover is a visual image, not a physical object in the setting.

For the interface, see GET /api/worlds/:id/gallery in the API reference. For the world data side, see World data reference.

Art worth investing in next

Below are suggestions that have not been verified. They are not content that has been finished or connected.

World	What to add first	How to tell whether it helps
遥风学园	Restrained emotional variants of 澪, 悠真, and 茜, and changes to the decorations on the eve of the school festival	Can a player, without reading labels, recognize the same person, the emotion, and how far the festival has progressed?
雾港	Clue illustrations such as the main pier, the guild appraisal table, and the low-tide entrance. Use the tide level rather than day and night to show the state	Can a player see what is being investigated, where the safe boundary is, and the pressure to get out?
Emberback	The signal repair room, the crawler station yard, and Nightglass. Use normal, power cut, and approaching storm to show the state	Can a player understand the state of the equipment and where they can go next?

The suggested order is: first look at the reasons that players with different interests choose these worlds, and then look at whether, once inside, they feel the game matches what they expected, and whether they want to finish the first goal. An aesthetic judgment cannot replace this evidence. Do not change a world's original play just to fill up the number of pictures in a common visual-novel set.

Checklist before delivery

What to check	What a passing result looks like
Matches the setting	Age, identity, props, and place features all agree with the character card and the world text. Each invariant has been checked
Consistent within one world	The drawing style, tone, and direction of light are the same. People are similar in size and framing
Size and format	Characters 1024x1536, scenes 1536x1024, WebP. Pictures that require transparency are really transparent
Recognizable when small	When shrunk to an avatar, you can still tell who it is
Different backgrounds	A transparent portrait placed on light and dark backgrounds has no white or black edge
No extra text	No watermarks, explanatory text, or garbled signs
The manifests are current	After changing a picture, emit-presence / emit-scenes has been run again, and validation passes
Clean folders	No PNG is left in media/portraits/ or media/scenes/

Next

• Start making portraits. See Illustrate characters.
• Start making scene pictures. See Make scene pictures for a world.
• How pictures are imported into a game and how they are stored. See World data reference and Media store reference.