NEVEL-98 Manual

NEVEL-98 is a fantasy computer for visual novels. It imagines a 1990s Japanese personal computer in the style of the NEC PC-9801: a 640×400 screen, 16 colors from a palette of 4096, FM sound, and a Lua interpreter with a visual novel engine built in.

This manual covers the machine, the console, every API function, the editors, and the cartridge format.

1. The machine¶

Lua's io, os, debug and require are not available; carts can only touch the machine through the API below. math.random is replaced by a deterministic generator so that saved games replay exactly.

2. Getting around¶

The machine boots into the console. From there:

While a cart is running, Esc opens the game's own system menu (save, load, log, settings) and F1–F5 stop the cart and return to the editors. Runtime errors stop the cart and print the message in the console; press F1 to open the code at the line that failed.

The mouse works everywhere: click the tabs in the top bar, the function key labels at the bottom of the console, and every button. Over the machine's screen the pointer becomes a PC-98 style arrow; while a cart runs it hides itself after three seconds without movement, and a cart can hide it for good with cursor(false).

3. Console commands¶

Commands are not case sensitive. File names without an extension are looked up as .n98, then .n98.png. Tab completes file names, Up/Down recall previous commands.

Files¶

Carts¶

Commands that would discard unsaved work ask you to repeat them.

Media¶

import options:

Transparent pixels in the source picture become color 0, which is set as the image's transparent color. A common workflow is to build a palette from a collage of all your art (import collage.png pal -c, then rmimg pal) and import every picture against it.

Text tables¶

Sharing¶

In the browser version, exports are downloaded; on the desktop they are written to the drive.

System¶

cls, keys (shortcut reference), help, reboot, shutdown.

4. Writing a visual novel¶

A cart's code runs once when the cart starts. Usually it only defines scenes; the engine then starts the scene named "title" if there is one, otherwise "start".

speaker("Rei", 11)                         -- name color for Rei

scene("title", function()
  title_screen{ bg = "station", music = 0 }
  jump("start")
end)

scene("start", function()
  bg("station", "dither")
  show("rei", "center")
  say("Rei", "You missed it too?")
  local c = choice{ "Who are you?", "Missed what?" }
  if c == 2 then flag.honest = true end
  jump("ending")
end)

scene("ending", function()
  say("The board flickers and goes dark.")
  the_end("NEXT YEAR")
end)

Each function call below waits for as long as it needs to: say waits for the player to read the line, bg with a transition waits until the transition ends, choice waits for an answer. You write the story top to bottom.

If you don't define any scenes, the top-level code itself is the story.

Texts and languages¶

Write your lines in the TEXT editor (F3) instead of in the code. Each row has a key and one string per language, like Godot's CSV translations:

In the code, tr("rei.hello", "Taro") returns "Hi, Taro!" (or "Ciao, Taro!" in Italian). {1}, {2}... are replaced by the extra arguments. A missing key comes back unchanged, so you can see what's left to write; a missing translation falls back to the first language.

Every visual novel function also accepts keys directly: a string that starts with @ is looked up in the table.

speaker("@char.rei", 7)
say("@char.rei", "@rei.hello")
if choice{ "@c.yes", "@c.no" } == 1 then ... end
the_end("@end.good")

When a cart has more than one language, the Settings menu gets a Language row and the player's choice is remembered. The first language is the source: the editor shows it next to the language you are translating.

The engine's own texts (title screen, system menu, settings, "THE END") can be translated too, by adding keys that start with ui.: ui.new_game, ui.continue, ui.load, ui.options, ui.quit, ui.save, ui.log, ui.auto_on, ui.auto_off, ui.skip, ui.settings, ui.title, ui.quit_to_editor, ui.close, ui.system, ui.save_game, ui.load_game, ui.empty, ui.backlog, ui.settings_title, ui.instant, ui.text_speed, ui.auto_delay, ui.music_volume, ui.sound_volume, ui.language, ui.lang_name (the name of each language, shown in Settings), ui.back, ui.return_to_title, ui.yes, ui.no, ui.the_end, ui.nothing_to_save, ui.saved_slot and ui.slot_empty (both use %d for the slot number). The demo cart translates all of them into Italian.

Scenes and flow¶

A scene that finishes without jumping ends the game with the_end().

Pictures¶

Characters are drawn bottom-aligned to the screen. If a background image has its own palette, the palette is switched with it.

Transitions: "dither" (ordered dissolve), "wipe" (left to right), "down" (top to bottom), "blinds", "curtain" (from the center), "mosaic", and "fade" (through black).

Text¶

Text wraps automatically. Inline tags:

window fields: x, y, w, h (default 16, 290, 608, 100), bg, fg, border (colors; by default the darkest, brightest and a middle color of the current palette), style ("solid" or "mesh" for a see-through dithered window), lines (default 4), blip (a pattern played as a typing sound).

Framed layouts (the PC-98 look)¶

Most PC-98 adventures show the scene in a window inside an ornate frame, with side panels for the date, a clock or the command menu, and the text in a console below. layout sets this up:

layout("game", {
  view = { 16, 16, 448, 264 },          -- where the scene is drawn
  frame = "frame",                      -- full-screen image drawn on top; its transparent color shows the scene
  hud = function(t) ... end,            -- draws panels (clock, date...) every frame, after the frame
  menu = { 486, 156, 130 },             -- menu{} appears here, as a list without a box
  menu_step = 21, menu_text_dx = 20,    -- row height and text offset (match your button art)
  menu_bar = 3, menu_bar_dx = 15,       -- color and offset of the bar behind the selected entry
  menu_sel = 6, menu_idle = 8,          -- colors for the selected / other entries
  choices = "window",                   -- choice{} is listed inside the text window
  window = { x = 16, y = 298, w = 608, h = 92, style = "none",
             name_style = "plate", name_x = 46, name_y = 288 },
})

scene("start", function()
  layout("game")                        -- switch to it (saved with the game)
  ...
end)

layout(name, def) defines a layout, layout(name) switches to it and layout(nil) goes back to full screen. Inside a layout, backgrounds are centered in the view, characters stand on the view's bottom edge, positions such as "right" are relative to the view, and effects are clipped to it. The layout's window entries override window{}.

Extra window fields: style = "none" draws no box (use it when the frame image already has one); name_style = "plate" prints the speaker's name at name_x, name_y (over a name plate in your frame art), "inline" writes it at the start of the text, and the default draws a small name box; name_format formats inline names; cursor colors the ▼ prompt.

The demo cart shows a complete framed layout, with a red LED clock drawn by its hud function.

Choices¶

A false entry hides an option while keeping the numbering: choice{ "Leave", flag.key and "Open the door" }.

Timing and effects¶

State and saving¶

title_screen options: bg, color, music, title (use \n for several lines), subtitle, scale (title size, default 3), title_x, title_y, menu_x, menu_y (centers and tops), title_color, text_color.

The player can save and load from the system menu at any time. A save records the scene, the flags as they were when the scene began, and every choice made since; loading replays the scene instantly up to the saved line. Two rules keep this exact:

1. Keep story state in flag (and persist), not in other global variables.
2. Use rnd/irnd (or math.random) for randomness: the generator is saved too.

The system menu¶

Esc or a right click opens it: Save, Load, Log (backlog; the mouse wheel also opens it), Auto, Skip, Settings (text speed, auto delay, music and sound volume), Title, and Quit. Holding Ctrl skips text; A toggles auto mode.

5. Machine API¶

All drawing happens in the cart's 16 colors (0–15). Coordinates are in pixels, (0, 0) is the top-left corner.

Drawing¶

DITHER holds ready-made patterns: solid, d12, d25, d50, d75, d87, hlines, vlines, diag. For example fillp(DITHER.d50) then rectfill(...) draws a checkerboard mesh, the classic PC-98 shading.

Images¶

Palette and screen¶

Input¶

Sound¶

Data and system¶

Math helpers¶

flr, ceil, abs, sgn, mid(a, b, c), clamp(x, lo, hi), lerp(a, b, t), sin(t) / cos(t) (t in turns), rnd([x or table]), irnd(a, b), srand(seed).

Game mode¶

A cart that defines _draw (and optionally _init and _update) and no scenes runs as a plain game loop, like PICO-8: _init() once, then _update() and _draw() 60 times per second.

local x = 320
function _update()
  if btn("left") then x = x - 2 end
  if btn("right") then x = x + 2 end
end
function _draw()
  cls(0)
  circfill(x, 200, 20, 12)
  print("arrows to move", 8, 8, 15)
end

6. The editors¶

Code (F1)¶

A Lua editor with syntax highlighting (keywords, API names, strings, numbers, comments).

Shift extends the selection; the mouse selects by dragging.

Image (F2)¶

The image list is on the left; NEW, DEL, NAME, SIZE, KEY (make the secondary color transparent), PAL (toggle the image's own palette), IMPORT PNG and FIT are below it.

Left click draws with the primary color, right click with the secondary color. D cycles the dither pattern: patterns mix the primary and secondary colors, so a 50% pattern with blue and black gives the classic PC-98 shading. X swaps the two colors, [ ] change the brush size, Shift constrains shapes to squares and circles.

The mouse wheel zooms around the cursor; drag with the middle button (or Space + left button) to pan; the arrow keys pan too; F fits the image. Ctrl+C / Ctrl+X copy or cut the selection (or the whole image), Ctrl+V pastes it as a stamp under the mouse (click to place, H flips it, Shift+click places several), Delete clears the selection. Ctrl+Z / Ctrl+Y undo and redo. PgUp/PgDn select the previous/next image.

The palette strip shows the 16 colors: left click picks the primary, right click the secondary. The R G B steppers edit the primary color; the change applies to the image's own palette if it has one, otherwise to the cart palette.

Text (F3)¶

A table of keys and their strings, one column per language. The yellow-framed language button is the source language; click another one to choose the language shown in the second column.

The buttons on the top right add, delete (click twice), rename and find keys; + and - add and remove languages. Missing translations are shown in red. Keys may use letters, digits, ., _ and -; dots are a good way to group them (rei.hello, menu.look, end.home). The panel at the bottom shows the whole text of the selected cell.

Sound (F4)¶

Edit the 32 instruments. Each one is:

• FM: 4 operators combined by one of 8 algorithms (shown as a diagram; yellow boxes are carriers you hear, blue ones modulate). FB is operator 1's self-feedback.
• SSG: a square wave with a duty cycle, using operator 1's envelope.
• NOISE: noise whose rate follows the pitch, using operator 1's envelope.

Operator parameters: AR attack rate, DR decay rate, SR sustain decay rate (0 holds the sustain level), RR release rate, SL sustain level, TL total level (attenuation, so higher is quieter), MUL frequency multiple (0 means ×0.5), DT detune. Click a value and drag up or down, or use the wheel, or the arrow keys with [ ]. VOL is the instrument's volume, VIB and SPD a vibrato.

Play the instrument with the keyboard (Z S X D C V G B H N J M for one octave, Q 2 W 3 E R 5 T 6 Y 7 U for the next), or click the piano; PgUp/PgDn change the octave. PRESET cycles through starting points (e-piano, strings, bass, bell, lead, SSG square, hi-hat, kick, snare, sine). Ctrl+C / Ctrl+V copy instruments.

Music (F5)¶

A tracker with 6 channels. Each cell is note instrument volume, for example C-4 01 F.

The left panel picks the song, its speed (frames per row at 60 frames per second; 6 means 10 rows per second) and loop point, and edits the order list: ADD inserts the current pattern after the selected slot, REMOVE deletes the slot, − and + change the slot's pattern. STEP is how many rows the cursor moves after each entry.

sfx(n) plays pattern n once and borrows only the channels the pattern uses, so put sound effects on channel 6 to keep the music going.

7. Cartridge format¶

A .n98 cart is UTF-8 text, made of sections:

-- nevel-98 cartridge v1
__meta__
title=Last Train Home
author=Someone
__lua__
...code...
__pal__
112 612 435 ... (16 entries of 3 hex digits, 0xRGB)
__img__ <name> <width> <height> <key> <has_palette>
[palette line, if has_palette is 1]
z<base64 of zlib-compressed 4-bit pixels, two per byte, high nibble first>
 <continuation lines start with a space>
__ins__
<index> <name> <type> <alg> <fb> <duty> <vib_depth> <vib_speed> <volume> | <AR DR SR RR SL TL MUL DT> | ... (4 operators)
__pat__ <index>
C-4 01 F  --- .. .  ...   (32 rows, 6 cells per row)
__song__ <index> <speed> <loop> <length> <pattern> <pattern> ...
__font__
z<base64 zlib of 256 glyphs × 16 rows>
__text__ en it
<key>\t<english>\t<italian>   (\n, \t and \\ are escaped)
__label__
<palette line>
z<base64 zlib of the 640×400 label>
__end__

Instruments that are unchanged from their defaults, empty patterns and empty songs are omitted.

A .n98.png floppy is an ordinary PNG picture of a 3.5" disk showing the cart label; the full cart text is stored, zlib-compressed, in a private nvCt chunk. Image hosts that re-encode pictures will strip it, so share floppies as files.

An exported .html player contains the WebAssembly machine and the zlib-compressed cart, base64-encoded, in one page.

Custom fonts¶

importfont reads a picture of a 16×16 grid of 8×16 glyph cells (128×256 pixels, or any multiple) covering character codes 0–255 in Latin-1 order. Light pixels on a dark background (or dark on light) become the glyph. The font replaces the 8×16 font for codes 0–255 while the cart runs; other characters still use the built-in font.

8. Limits and tips¶

• Keep full-screen backgrounds at 640×400, or size them to your layout's view (448×264 in the demo). Characters around 240×264 fit the demo's view.
• For characters that appear on several backgrounds, reserve a block of palette entries (the demo uses colors 0–9 for skin, hair, clothes and the frame) and give each background its own palette that keeps those entries and changes only the rest.
• 16 colors go further with dithering: plan a palette for the whole game (import collage.png pal -c).
• bg() clears the characters; call show() after it.
• Each frame has 5 seconds of CPU before the machine stops the cart, which catches infinite loops.
• Saves, settings and persist live in the drive under .saves/<cart name>/; renaming a cart file starts fresh saves.

9. Running and building¶

Playing in the browser¶

web/dist/index.html is the complete machine (console and editors) in one file; web/dist/demo.html plays the demo novel. Open either one directly, or upload it to any static host such as itch.io. Files you create in the browser are kept in the browser's storage; drop .n98, .n98.png or images on the page to add them.

Building¶

Desktop (Windows, macOS, Linux)¶

Requirements: CMake 3.16+, a C11 compiler. SDL3 is used if installed, otherwise CMake downloads it.

cmake -S . -B build
cmake --build build --config Release
./build/nevel98            # or build\Release\nevel98.exe on Windows

Command line:

nevel98                      boot into the console
nevel98 game.n98             boot with a cart loaded
nevel98 --play game.n98      run a cart as a standalone player
nevel98 --demo               play the demo novel
nevel98 --scale 3            start with a 3x window

Carts are stored in the machine's drive, a carts folder inside your user application data folder (on Linux ~/.local/share/nevel98/NEVEL-98/carts). Type folder in the console to see the exact path and open it. You can also drag carts and images onto the window.

Web (WebAssembly)¶

The browser build uses wasi-sdk (version 25 or newer):

WASI_SDK=/path/to/wasi-sdk ./web/build_web.sh

This writes web/dist/nevel98.wasm, web/dist/index.html and web/dist/demo.html. When web/dist/nevel98.wasm exists, the desktop build bundles it so the export game.html command works offline. A prebuilt copy is included in this repository.

Headless runner¶

nevel98_headless runs the machine without a window. It is used for automated tests and can script input and save screenshots:

./build/nevel98_headless --play --frames 600 --keys "60:z,120:z" --shot 300:shot.png @demo

Project layout¶

src/core/        the machine: graphics, FM synth, carts, Lua API, editors, console
src/core/prelude.lua   the visual novel engine, written in Lua
src/platform/    hosts: SDL3 desktop, WebAssembly, headless
web/             browser shell and build script; web/dist has prebuilt files
carts/           the demo cart (.n98 and floppy .n98.png)
assets/          application icon (.ico for Windows, PNG for the window)
tools/           bin2c, mkhtml, the font converter
third_party/     Lua 5.4.7, stb_image, stb_image_write
docs/MANUAL.md   the complete manual

Fonts¶

The built-in fonts are converted from Spleen (BSD 2-Clause). The original NEC PC-98 font ROM is copyrighted and is not included; if you own one, you can draw or convert its glyphs into a 16×16 sheet of 8×16 cells and install it in a cart with importfont sheet.png.

License¶

NEVEL-98 is released under the MIT license (see LICENSE). Third-party components keep their own licenses: Lua (MIT), stb (public domain / MIT), Spleen (BSD 2-Clause), SDL3 (zlib). Carts you make are yours.

This page is generated from docs/MANUAL.md and the README of NEVEL-98.