Server Exports#
For opening books from your own scripts — the rules on first join, a briefing when a player clocks in, a plaque at a museum, a quest note picked up from the floor.
openBook
Opens a saved book in the reader for one player. It is read-only: no item is needed, and the player cannot edit it.
local ok = exports['qs-book-creator']:openBook(source, bookUid)Parameter | Type | Description |
|---|---|---|
| number | The player's server id. |
| string | number | The book's |
Returns false only when an argument is missing. A book that does not exist, or has no title or pages, shows the player This book has no data instead of opening.
-- /rules opens the server rulebook for whoever types it
RegisterCommand('rules', function(source)
exports['qs-book-creator']:openBook(source, 'server-rules')
end, false)useBook
The item-use handler for ox_inventory. It is declared in the item's definition and never called by hand:
server = {
export = 'qs-book-creator.useBook',
},A Book With a Readable Id#
A blank item gets a random id, but an id can be any text up to 64 characters. Giving the books you open from code a readable one — server-rules, lspd-handbook — means no copying ids out of the database. Open the writer on that id from the server, write the book, and save:
-- restricted: needs the ace command.writerules
RegisterCommand('writerules', function(source)
TriggerClientEvent('book:client:openCreator', source, {
bookUid = 'server-rules',
})
end, true)No item is involved: saving stores the book under server-rules, ready for openBook and for copies. The writer opens empty unless a book table is passed with it, and saving replaces whatever is stored under that id.
Giving a Copy of a Book#
A copy is an ordinary book item whose metadata carries the book's id. Use the id you chose, or read one from the database with SELECT unique_id, title FROM qs_books;.
exports.ox_inventory:AddItem(source, 'book', 1, {
bookUid = 'server-rules',
bookTitle = 'Server Rules',
author = 'Staff',
})exports['qs-inventory']:AddItem(source, 'book', 1, nil, {
bookUid = 'server-rules',
bookTitle = 'Server Rules',
author = 'Staff',
})local Player = QBCore.Functions.GetPlayer(source)
Player.Functions.AddItem('book', 1, false, {
bookUid = 'server-rules',
bookTitle = 'Server Rules',
author = 'Staff',
})Opening a Book Built in Code#
The reader does not need the database. Send it a book table and it opens — for content made on the spot: a criminal record from your MDT, a receipt, a mission briefing, a generated newspaper.
TriggerClientEvent('book:client:openBook', source, {
title = 'Case File #2231',
author = 'LSPD Records',
description = 'Confidential',
cover_url = 'https://example.com/case-cover.png',
pages = {
{
title = 'Suspect',
subtitle = 'Known aliases',
content = 'First paragraph.\nSecond paragraph.',
image = 'https://example.com/mugshot.png',
},
{ content = 'A page with text only.' },
},
})Every page needs content; the rest is optional. A book with no pages shows This book has no data, and nothing opens while the player is already reading.
Client Events#
Sent from the server with TriggerClientEvent.
Event | Payload | Does |
|---|---|---|
| A book table | Opens the reader. |
|
| Opens the writer. |
|
| Shows the Open / Edit menu. |
|
| Shows a message in the book interface. |
Callbacks#
Client to server, through ox_lib — lib.callback.await(name, false, ...) from any client script.
Callback | Parameters | Returns |
|---|---|---|
|
| The book, or |
|
|
|
|
|
|
|
|
|
| — |
|
| — |
|
book:createBook, book:updateBook, book:removeBook and book:getBookById are kept for integrations written against older versions.
Data Shapes#
-- A book, as stored and as sent to the reader
Book = {
unique_id = 'server-rules', -- the id items carry as bookUid
title = 'Server Rules',
author = 'Staff',
description = 'Read before you play',
cover_url = 'https://example.com/cover.png',
pages = { Page, Page, ... },
item = 'book',
creator = 'char1:1a2b3c...', -- who first wrote it
}
-- One page
Page = {
title = 'Chapter I', -- optional
subtitle = 'The beginning', -- optional
content = 'Text...', -- required; \n starts a new paragraph
image = 'https://example.com/a.png', -- optional
}
-- The metadata on a book item
metadata = {
bookUid = 'server-rules',
bookTitle = 'Server Rules',
author = 'Staff',
}