Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Dialog

Ling has two dialog tools. Dialog boxes show what a character says: an adventure-game text box that types out letter by letter, pages, and highlights names, places and items in colour. Dialog models decide what a character says: a tiny language model, trained in a second from that character’s own lines, that every NPC can carry. Its training data uses a plain text format, the Ling Dialog Standard (.lingdialog).

Both work without a window except dialog_draw, so you can test a whole conversation headless.

Summary

Builtin中文日本語한국어ไทยPurpose
dialog_show(text, cps)对话显示会話表示대화표시แสดงบทสนทนาOpen a dialog box with marked-up text.
dialog_step(dt)对话步进会話更新대화스텝ก้าวบทสนทนาAdvance the typewriter and auto-advance timer.
dialog_advance()对话推进会話送り대화진행เลื่อนบทสนทนาThe player pressed confirm.
dialog_active()对话激活会話中대화중บทสนทนาทำงานWhether a box is open.
dialog_typing()对话打字会話タイプ中대화타이핑กำลังพิมพ์บทสนทนาWhether the page is still typing.
dialog_close()对话关闭会話閉じる대화닫기ปิดบทสนทนาClose the box at once.
dialog_color(role, r, g, b)对话颜色会話色대화색สีบทสนทนาColour of a text role.
dialog_draw(x, y, w, h, font)对话绘制会話描画대화그리기วาดบทสนทนาDraw the box and its revealed text.
dialog_new(ctx, embed, hidden, seed)建对话模型対話モデル作成대화모델생성สร้างโมเดลสนทนาCreate an empty dialog model.
dialog_learn(m, text)对话学习対話学習대화학습เรียนรู้สนทนาAdd one line to the model’s corpus.
dialog_load(m, path)对话载入対話読込대화불러오기โหลดชุดสนทนาAdd a .lingdialog file to the corpus.
dialog_train(m, epochs, lr)对话训练対話訓練대화훈련ฝึกสนทนาTrain on the corpus. Returns the loss.
dialog_say(m, prompt, max, temp)对话生成対話生成대화생성พูดสนทนาGenerate a reply.
dialog_save(m, path)对话存模対話モデル保存대화모델저장บันทึกโมเดลสนทนาSave the trained model.
dialog_load_model(path)对话载模対話モデル読込대화모델불러오기โหลดโมเดลสนทนาLoad a saved model.

Dialog boxes

The box state lives in the runtime, separate from drawing: dialog_show opens it, dialog_step moves time forward, dialog_advance reacts to the player, and dialog_draw paints it. While dialog_active() is true, pause your game world.

Markup

MarkupMeaning
{n}...{/}A character name (colour role 1).
{p}...{/}A place (role 2).
{i}...{/}An item (role 3).
a newline characterA new line in the box.
||A page break.

A tag is exactly three characters, {, a letter and }, and {/} returns to plain text (role 0). Anything else is shown as written.

A page that has finished typing advances by itself after 1.4 seconds, and the last page then closes the box.

dialog_show(text, cps)

Opens a box with text, typed at cps characters per second (default 32, at least 1). It replaces any box already open.

dialog_step(dt)

Advances the typewriter and the auto-advance timer by dt seconds (default 0.016). Call it every frame while the box is active.

dialog_advance()

Call it when the player presses the confirm key. If the page is still typing, the rest of the page appears at once; otherwise the box moves to the next page, or closes after the last one. Drive it from a key press (key_pressed), not a held key, so one press doesn’t skip several pages.

dialog_active(), dialog_typing() and dialog_close()

dialog_active() is true while a box is open. dialog_typing() is true while the current page is still appearing. dialog_close() closes the box immediately.

bind start = do {
  dialog_show("Hello {n}Ling{/}.||Second page.", 100)
  print("active: " + str(dialog_active()))
  print("typing: " + str(dialog_typing()))
  dialog_step(0.5)
  print("typing after 0.5 s: " + str(dialog_typing()))
  dialog_advance()
  print("page 2 typing: " + str(dialog_typing()))
  dialog_advance()
  dialog_advance()
  print("active at the end: " + str(dialog_active()))
}
active: true
typing: true
typing after 0.5 s: false
page 2 typing: true
active at the end: false

At 100 characters per second the first page is fully typed after 0.5 s. The first dialog_advance turns to page 2, the second reveals all of page 2, and the third closes the box.

dialog_color(role, r, g, b)

Sets the colour of a role: 0 plain text, 1 name, 2 place, 3 item (values above 3 count as 3). r, g and b are 0 to 255 (default 255).

dialog_draw(x, y, w, h, font)

Draws the bevelled box with its top-left corner at (x, y) (default 40, 0), size w by h (default 720 by 150), and the text revealed so far. font is a handle from font_load; leave it out or pass -1 to use the built-in text drawing.

bind start = do {
  open_window(800, 600)
  bind ui = font_load("assets/fonts/Exo2.ttf", 600.0)
  bind line = "Hey {n}Link{/}! Take the {i}Master Sword{/} to {p}Hyrule Field{/}.||Beware the night."
  dialog_color(1, 255, 210, 80)
  while window_is_open() {
    if key_pressed("space") {
      if dialog_active() { dialog_advance() } else { dialog_show(line, 34.0) }
    }
    fill(10, 10, 20)
    if dialog_active() {
      dialog_step(0.016)
      dialog_draw(50.0, 420.0, 700.0, 150.0, ui)
    } else {
      // normal game update here
    }
    present()
  }
}

Dialog models

A dialog model is a miniature next-word language model, a few kilobytes in size, built into Ling (ling_ai::dialog_lm). You give it a character’s lines, train it, and ask it to continue a prompt. It learns cadence and vocabulary, not facts, so it suits ambient chatter, barks and flavour text. Training a small corpus takes well under a second. With temperature 0 the output is deterministic.

bind start = do {
  bind npc = dialog_new(3, 32, 64, 1)
  dialog_learn(npc, "welcome traveler")
  dialog_learn(npc, "keep your blade sharp")
  dialog_learn(npc, "welcome back traveler")
  bind loss = dialog_train(npc, 60, 0.1)
  print(loss < 2.0)
  print(dialog_say(npc, "welcome", 6, 0.0))
}
true
back traveler

dialog_new(ctx, embed, hidden, seed)

Creates an empty model and returns its handle. ctx (default 3) is how many previous words it looks at, embed (default 32) and hidden (default 64) are the network sizes, and seed (default 1) makes training repeatable.

dialog_learn(m, text) and dialog_load(m, path)

dialog_learn adds one line to the corpus. dialog_load adds a whole .lingdialog file and returns the number of training lines it added (one per conversation), or -1 if the file can’t be read.

dialog_train(m, epochs, lr)

Trains on everything in the corpus for epochs passes (default 20) at learning rate lr (default 0.1). Returns the final loss: lower means the model fits its lines better.

dialog_say(m, prompt, max, temp)

Continues prompt for up to max words (default 24) and returns only the new words. It stops early at the end of a turn. temp (default 0.8) is the temperature: 0 always picks the likeliest word, higher values are more varied.

The tokenizer splits text at spaces and punctuation and lower-cases it. For languages written without spaces, put a space between words in your corpus and prompts; the reply comes back with spaces between words.

dialog_save(m, path) and dialog_load_model(path)

dialog_save writes the trained model to a file (default "model.llm") and returns true on success. dialog_load_model reads one back and returns a new handle, or -1 on failure. Train once while building your game, then ship and load the small model file.

The Ling Dialog Standard

.lingdialog is a line-based, human-writable corpus format. Writers edit it by hand or generate it from a spreadsheet; it diffs cleanly in reviews and can be localized like any text file.

# Ling Dialog Standard v1
@meta title: Tavern Keeper
@meta speaker: Bram

= welcome
bram: welcome traveler
hero: any news from the road
bram: bandits on the north pass
      nothing my stew cannot cure

= rumors
bram: keep your blade sharp
LineMeaning
# ...Comment to the end of the line.
@meta key: valueMetadata about the dataset. Repeatable.
= labelStart a new conversation. The label is optional.
speaker: textOne turn. The speaker is the text before the first colon.
a line without :Continues the previous turn (joined with a space).
a blank lineIgnored.

Parsing never fails: a malformed line is skipped, so one stray character can’t break a training run. Turns before the first = form an implicit conversation.

Each conversation becomes one training line, with its turns joined by the reserved <eos> token, so the model learns to continue across turns. Writing <eos> yourself also marks a turn boundary. The reserved tokens are <pad>, <bos>, <eos> and <unk>.

bind start = do {
  write_file("bram.lingdialog", "# Ling Dialog Standard v1\n@meta speaker: Bram\n\n= welcome\nbram: welcome traveler\nhero: any news from the road\nbram: bandits on the north pass\n\n= rumors\nbram: keep your blade sharp\n")
  bind npc = dialog_new(3, 32, 64, 1)
  print(dialog_load(npc, "bram.lingdialog"))
  dialog_train(npc, 80, 0.1)
  print(dialog_say(npc, "bandits on the", 8, 0.0))
  print(dialog_save(npc, "bram.llm"))
  bind again = dialog_load_model("bram.llm")
  print(dialog_say(again, "keep your", 8, 0.0))
}
2
north pass
true
blade sharp

Writing a good corpus

  • Consistency beats volume. A small corpus in one clear voice gives a more recognisable character than a large generic one.
  • Repeat signature phrases. Lines you want the character to favour should appear a few times across conversations.
  • One file per voice. Keep each character in its own file, so each gets its own model and personality.
  • Write naturally. Case and punctuation are handled by the tokenizer.

Putting them together

The model writes the line; the box shows it:

bind start = do {
  open_window(800, 600)
  bind bram = dialog_load_model("npc/bram.llm")
  while window_is_open() {
    if key_pressed("e") && !dialog_active() {
      dialog_show("{n}Bram{/}: " + dialog_say(bram, "welcome", 12, 0.7))
    }
    if key_pressed("space") && dialog_active() { dialog_advance() }
    fill(10, 10, 20)
    dialog_step(0.016)
    if dialog_active() { dialog_draw(50, 420, 700, 150) }
    present()
  }
}

See also