book

Creates and reads personalized scrolls from templates/books.

Source: src/Moongate.Server.Ultima/Modules/BookModule.cs

Functions

give

book.give(player, template_id, values?) -> integer?

Gives a document from templates/books/<template_id>.toml to the player's backpack. Resolves $name and ${name} at creation; values supplies declared custom strings, finite numbers or bools. Nil for missing data, invalid values, no backpack or no serial. Saved text stays unchanged when traded or read.

-- The shipped welcome letter declares contact_name.
local letter = book.give(player, "welcome_letter", { contact_name = "Vega" })
if letter then
    book.open(letter, player)
end

The recipient name and all values are saved when the scroll is created. A second reader sees the same text. Nil means no item was created.

Parameter	Type	Default
player	integer
template_id	string
values (optional)	table	nil

Returns integer?.

open

book.open(item, player) -> boolean

Displays the item's saved plain text without substituting reader variables. Native books submit cover and page packets during the call; true means both were accepted for sending. Scrolls opened from Lua are queued for the next game-loop turn; true means queued, with reader/item identity, the original session and item access checked again before delivery. False means refused, including invalid data, inaccessible items, size limits or unavailable queues.

-- In an item script:
function readable_scroll.on_use(serial, user)
    book.open(serial, user)
    return true
end

This displays saved text, with normal item access and range checks. Native books submit their cover and page packets during the call; true means both packets were accepted for sending. Scrolls opened from Lua are queued for the next loop turn, so true means the request was queued. Before opening a queued scroll, the server rechecks the reader and item identities, the original session and item access. Deletion, replacement, disconnection or loss of access prevents delivery; moving a scroll only prevents delivery if it becomes inaccessible. False means the request was refused.

Parameter	Type	Default
item	integer
player	integer

Returns boolean.

write

book.write(item, template_id, player, values?) -> boolean

Inscribes an existing readable item for the specified player using a book template and optional custom values. False for unknown data, invalid values, held items, stacks or unsupported items; failure leaves all saved fields unchanged.

local written = book.write(scroll, "welcome_letter", player, {
    contact_name = "Orione"
})

The item must use a nonstackable readable template and must not be held. False leaves its previous name, title, author and body unchanged.

Parameter	Type	Default
item	integer
template_id	string
player	integer
values (optional)	table	nil

Returns boolean.