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,
})

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,
})

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 },
})