Exports

Start the in-world placement preview for the note held in the given inventory slot. The slot's item must carry a saved document (a docId in its metadata); if it does not, the player is notified to save it first.

-- Wired on the notepad item in ox_inventory/data/items.lua,
-- so the inventory's right-click "Place" button enters placement.
buttons = {
    {
        label = 'Place',
        action = function(slot)
            exports.nx_write:placeFromSlot(slot)
        end,
    },
},

Open or continue a writing session. Returns false if a session or placement preview is already active, or if the kind is unknown. Pass docId to continue a saved document; omit it for a new one. slot and itemName are opaque values echoed back in nx_write:documentSaved on save.

-- Continue a document your custom inventory stored on the item.
exports.nx_write:Open({
    kind     = 'notepad',
    docId    = item.metadata.docId,
    slot     = item.slot,
    itemName = item.name,
})

Register a writable paper kind at runtime, so another resource can add its own paper without editing nx_write. The def needs a kind key plus whatever differs from the template. Everything else is filled in from a small-card default, and the session feel (hold pose, pen, write animation, hand IK) is inherited from the live post-it entry, so a registered kind tracks future post-it retunes instead of a frozen copy. Call the server export with the same def, or saving a session of that kind is rejected. Built-in kinds cannot be overwritten. Returns true, or false plus a reason string.

-- Register on both sides, then open sessions with your own item.
exports.nx_write:RegisterPaperKind({
    kind       = 'polaroid',
    label      = 'Polaroid',
    prop       = 'prop_cs_polaroid',
    features   = { tear = false, fontButton = false },
    background = { box = { x = 0.06, y = 0.05, w = 0.88, h = 0.72 } },
})

exports.nx_write:Open({
    kind       = 'polaroid',
    docId      = item.metadata.docId,
    slot       = item.slot,
    itemName   = item.name,
    background = { url = photoUrl },
})

Start the in-world placement preview for a saved document. docId is required, since the placement renders the document's saved preview image. slot and itemName ride along to the server and are echoed on nx_write:placementCreated.

exports.nx_write:Place({ kind = 'notepad', docId = item.metadata.docId, slot = item.slot, itemName = item.name })

Create a committed placement at explicit coords and rotation, skipping the in-world aim preview. This is the hook for custom positioning tooling (transform gizmos, snapping, free-rotate): your UX owns where the note goes, nx_write owns persistence, render, and multiplayer sync. It runs the same server callback as a preview commit, so it persists, bakes and renders on every client, and fires nx_write:placementCreated. Returns the placement id on success, or false. A client-driven create is still validated against the player's position (Config.Placement.maxPlaceDistance plus 2 m slack); use the server export for an unbounded, trusted placement.

-- From a transform gizmo: the tool owns positioning, nx_write owns the rest.
-- Passing a live entity is the precise path: the placement is
-- byte-identical to the preview prop the player was dragging.
local id = exports.nx_write:CreatePlacement({
    kind     = 'notepad',
    docId    = item.metadata.docId,
    entity   = gizmoPreviewProp,
    slot     = item.slot,
    itemName = item.name,
})

-- Or place at explicit coords with a lossless quat.
exports.nx_write:CreatePlacement({
    kind   = 'notepad',
    docId  = item.metadata.docId,
    coords = vec3(215.7, -810.2, 30.7),
    quat   = { x = 0.0, y = 0.0, z = 0.0, w = 1.0 },
})

Re-pull placements from the server and render any not held locally. Live creates already arrive over the spawn broadcast, so this is a manual resync for tooling that writes to nx_write_placements out of band. Idempotent. Returns true if the refresh ran.

exports.nx_write:RefreshPlacements()

Save (or discard) the active writing session and close it. Pass true to discard without saving. Returns false if no session was active.

exports.nx_write:Close()      -- save and close
exports.nx_write:Close(true)  -- discard and close

True while a writing session or a placement preview is active. Gate your own item-use with it so a second use does not double-open.

if not exports.nx_write:IsBusy() then
    exports.nx_write:Open({ kind = 'notepad', docId = item.metadata.docId })
end

Forward an open request to a player's client. Mirrors the client Open export and accepts the same opts. Use this when your inventory routes item-use through a server hook.

-- From your inventory's server-side item-use handler.
exports.nx_write:Open(source, {
    kind     = 'notepad',
    docId    = item.metadata.docId,
    slot     = item.slot,
    itemName = item.name,
})

Server-side twin of the client RegisterPaperKind export. Pass the same def. Saving validates the payload kind against the registered papers, so a kind registered only on the client would open sessions it can never save. Returns true, or false plus a reason string.

exports.nx_write:RegisterPaperKind({ kind = 'polaroid', label = 'Polaroid' })

Read a saved document's stored preview image, so a host resource can render the ink outside nx_write (on its own prop, in its own UI). Returns nil if the document does not exist. The preview is a transparent PNG data URL. The caller owns its own access policy: serve only the kinds you registered, or private notepad ink becomes readable.

-- { kind = 'polaroid', title = 'Beach', dataUrl = 'data:image/png;base64,...' }
local preview = exports.nx_write:GetDocumentPreview(docId)
if preview and preview.kind == 'polaroid' then
    TriggerClientEvent('myresource:drawInk', src, preview.dataUrl)
end

Create a placement at explicit coords from the server, bypassing the aim preview. The trusted mirror of the client CreatePlacement export. Because the server supplies the coords, the per-player rate-limit and distance gate are skipped (those guard the untrusted client callback). Everything else is identical to a preview commit: it persists, broadcasts so every client bakes and renders it, and fires nx_write:placementCreated. Pass coords with quat or rotation; there is no entity option, since the server cannot read a client entity. Returns the placement id on success, or false.

-- Seed a placement programmatically from a server hook.
local id = exports.nx_write:CreatePlacement(source, {
    kind   = 'notepad',
    docId  = docId,
    coords = vec3(215.7, -810.2, 30.7),
    quat   = { x = 0.0, y = 0.0, z = 0.0, w = 1.0 },
})