Dialogs

Unified `Dialog` (`D`)

Builder, events, pages, and palette shortcuts in one table.

Lua

local D = require("CrawlzUtils").Dialog

Field	Resolves to
`D.new`, `D.build`	`DialogBuilder.new`
`D.Builder`	`DialogBuilder`
`D.Event`	`DialogEvent`
`D.Page`	`DialogPage`
`D.PagesBook`	`DialogPagesBook`
`D.pagesBook`	`DialogBuilder.pagesBook`
`D.Pages`	`DialogBuilder.Pages`
`D.open`, `D.openWith`, `D.screen`, `D.route`, `D.on`, `D.go`, `D.any`, `D.handle`, `D.setDebug`	`DialogEvent`
`D.pick`, `D.button`, `D.input`, `D.dialogName`	Packet helpers
`D.Align`, `D.Size`, `D.Colors`, `D.TextColors`, `D.ProgressColors`	Layout / palettes

Example

local D = require("CrawlzUtils").Dialog
D.openWith(world, pl, "shop", { coins = 100 })

Tip. For interactive dialogs, pair DialogEvent.screen with DialogEvent.route; the first registration binds rendering and return handling for that screen or route.

`DialogBuilder`

Fluent builder: DialogBuilder.new(name) or DialogBuilder(name).

Finishing the packet

Method	Description
`:build()`	Full dialog string
`:toString()`	Same as `build()`
`:send(player)`	After `build()`, deliver (returns `false` if dialog not accepted)
`:endDialog(dialogName, close, confirm?, cancel?)`	Footer / `end_dialog`
`:buttons(close, confirm?, cancel?)`	Footer labels

Theme & layout (aliases)

Alias	Maps to
`:defaultColor(name)`	`set_default_color`
`:bgColor(rgbaOrName)`	`set_bg_color`
`:borderColor(rgbaOrName)`	`set_border_color`
`:spacing(x, y)`	`set_custom_spacing`
`:title(text, iconID)`	`add_title`
`:smallText(text)`	`add_smalltext`
`:label(size, text, align)`	`add_label`
`:spacer(size)`	`add_spacer`
`:button(name, text, flags, u1, u2)`	`add_button`
`:textInput(name, label, default, len)`	`add_text_input`
`:quickExit()`	`add_quick_exit`
`:progressBar(...)`	`add_progress_bar`

For every add_* / set_*, snake_case aliases exist on DialogBuilder (e.g. add_smalltext).

Power user

Method	Description
`:line(cmd, ...)`	Raw protocol line
`:raw(line)`	Minimal sanitization
`:clone()`	Copy state
`:with(fn)` / `:also(fn)`	Inline hook
`:each({ fn1, fn2 })`	Multiple hooks
`:embedData(embed, data)`	Embedded payload
`:pages(config, pageList)`	Pagination · `renderPages`, `add_pages`
`:pagesBook(defaults)`	New `DialogPagesBook`

Themed menu

local Utils = require("CrawlzUtils")
local B = Utils.DialogBuilder
local P = Utils.wrapPlayer(pl)

B.new("main_menu")
  :bgColor("discordDarker")
  :borderColor("Blurple")
  :defaultColor("white")
  :title("Main Menu", 242)
  :smallText("`wWelcome, ``" .. P:plainName())
  :button("shop", "Shop", "noflags", 0, 0)
  :button("close", "Close", "noflags", 0, 0)
  :quickExit()
  :send(pl)

Pagination

local Utils = require("CrawlzUtils")
local B = Utils.DialogBuilder
local Pg = Utils.DialogPage

B.new("book")
  :bgColor("DarkNavy")
  :pages({ prevId = "pg_prev", nextId = "pg_next" }, {
    Pg.new():title("Page 1", 18):draw(function(b) b:smallText("First") end),
    Pg.new():title("Page 2", 18):draw(function(b) b:smallText("Second") end),
  })
  :quickExit()
  :build()

`DialogEvent` & `DialogRoute`

Screen renders UI; route handles buttonClicked.

Core API

Function	Description
`DialogEvent.screen(name, renderer)`	`renderer(world, player, context)` → builder or string · `register`, `dialog`
`DialogEvent.route(name)`	Get or create route
`DialogEvent.on(name, button, handler)`	Shortcut
`DialogEvent.go(name, button, targetDialog)`	Jump dialog
`DialogEvent.any(name, handler)`	Fallback `*`
`DialogEvent.open(player, name, context)`	Render screen
`DialogEvent.openWith(world, player, name, context)`	Sets `context.world`
`DialogEvent.handle(world, player, data)`	Dispatch return
`DialogEvent.setDebug(bool)`	Verbose errors

Packet helpers

Function	Description
`DialogEvent.pick(data, key, default)`	Case-insensitive lookup
`DialogEvent.button(data)`	Button id
`DialogEvent.input(data, field, default)`	Read field
`DialogEvent.dialogName(data)`	Dialog id

DialogRoute

Method	Description
`:on(buttonName, callbackOrTarget)`	Function or target dialog name (string)
`:go(button, targetDialog)`	String jump
`:back(button?, targetDialog)`	Back
`:close(callback?)`	`__close`
`:open(player, context)`	Open this dialog
`:map(definitions)`	Bulk register

Handler arguments: (world, player, data, context) — context includes world, player, data, dialog, button.

Return	Effect
`true` / `nil`	Stop (re-open manually if needed)
`string`	Open dialog with that name
`DialogBuilder` or object with `:build()`	Send new dialog

Important. Arbitrary keys you pass to DialogEvent.open do not automatically round-trip inside data. Persist state yourself or rely on echoed embed/input fields.

Screen + route + Command

local Utils = require("CrawlzUtils")
local D = Utils.Dialog
local Command = Utils.Command

local stored = {}

local function uid(pl)
  local id = Utils.wrapPlayer(pl):identity().uid
  return id ~= nil and tostring(id) or "?"
end

D.screen("demo", function(w, pl, ctx)
  local n = tonumber(ctx.clicks) or 0
  return D.Builder.new("demo")
    :bgColor("DarkNavy")
    :borderColor("Gold")
    :title("Demo", 18)
    :smallText("Clicks: " .. tostring(n))
    :button("bump", "+1", "noflags", 0, 0)
    :quickExit()
end)

D.route("demo"):on("bump", function(world, player)
  local k = uid(player)
  stored[k] = (tonumber(stored[k]) or 0) + 1
  D.openWith(world, player, "demo", { clicks = stored[k] })
  return true
end)

Command.new()
  :name("demo")
  :execute(function(d)
    local k = uid(d.player)
    stored[k] = 0
    D.openWith(d.world, d.player, "demo", { clicks = 0 })
  end)

`DialogPage` & `DialogPagesBook`

DialogPage

local Pg = require("CrawlzUtils").DialogPage
Pg.new({ id = "optional", title = { "Text", 242 } })

Method	Description
`:id`, `:title`, `:subtitle`, `:icon`	Header
`:draw(fn)`	`fn(builder, ctx)`
`:visible(predicate)`	`fn(ctx) -> bool`
`:hiddenMessage`, `:before`, `:after`, `:withMeta`, `:apply`	Hooks

DialogPagesBook

local Book = require("CrawlzUtils").DialogPagesBook
local book = Book.new({ bgColor = "DarkNavy" })
book:add(page1, page2)
book:into(builder, { index = 2 })

Method	Description
`:add`, `:clear`, `:count`, `:into`	Book operations

Unified Dialog (D)

DialogBuilder

DialogEvent & DialogRoute

DialogPage & DialogPagesBook

Unified `Dialog` (`D`)

`DialogBuilder`

`DialogEvent` & `DialogRoute`

`DialogPage` & `DialogPagesBook`