PropPlacer

const PropPlacer: object

Defined in: client/api.d.ts:2731

Placement mode: a translucent preview under the crosshair, tinted for whether the spot is accepted, put down with a click.

The loop is native and runs with the game’s own frame, so the preview tracks the camera exactly and no script runs per frame. While a session is up this client’s input belongs to it, the way one of the game’s own screens takes it – which is what stops a confirm click also swinging the player’s sword, and what stops the player walking away mid-placement.

One session at a time, and it belongs to the resource that started it: a resource that stops takes its session with it.

Nothing here is authority. The rules below colour a preview at one client. What actually gets built is the server’s decision, made again from the pose the client confirmed – two players aiming at the same patch of ground both see green.

Type Declaration

begin()

begin(options): boolean

Starts placement. The preview appears under the crosshair on the same frame.

Parameters

options

model, models, offsets and rotations describe the preview exactly as PropGhost.create takes them.

validTint and invalidTint are the two colours the preview flips between, translucent green and translucent red by default. range is how far the aim ray reaches in metres (40 by default, up to 512) and fallbackDistance is where the preview sits when the ray reaches nothing. verticalOffset lifts or sinks it, yaw is a fixed turn added to whatever the aim settles on, and the mouse wheel moves that while a session is up.

alignToSurface stands the preview on the slope it is aimed at instead of upright; faceAwayFromPlayer turns it to face away from where you stand, which is what a wall or a tower wants and is on by default. keepOpen leaves the session running after a confirm so several can be placed in one go, and is on by default.

rules is what the preview is tinted by, and every one of them is off unless named. maxSlope is degrees the ground may lean; surfaces is which surface names are allowed; minDistance and maxDistance bound how far from the player it may stand; clearance is metres that must be free of other entities, narrowed to clearanceClasses when given; requireSurface refuses a spot the ray never reached, and is on by default.

alignToSurface?

boolean

faceAwayFromPlayer?

boolean

fallbackDistance?

number

invalidTint?

Color

keepOpen?

boolean

model?

string

models?

string[]

offsets?

Vector3[]

range?

number

rotations?

Quaternion[]

rules?

{ clearance?: number; clearanceClasses?: string[]; maxDistance?: number; maxSlope?: number; minDistance?: number; requireSurface?: boolean; surfaces?: string[]; }

rules.clearance?

number

rules.clearanceClasses?

string[]

rules.maxDistance?

number

rules.maxSlope?

number

rules.minDistance?

number

rules.requireSurface?

boolean

rules.surfaces?

string[]

scale?

number

validTint?

Color

verticalOffset?

number

yaw?

number

Returns

boolean

True when the session started; false when one is already running, when this client has no world or camera, when another part of the mod holds the controls, and when the preview could not be built.

end()

end(): void

Ends the session and gives the player their input back. end is raised. Doing nothing when no session is running is not an error.

Returns

void

getPose()

getPose(): PlacementPose | null

Where the placement is aimed right now, without waiting for a move.

Returns

PlacementPose | null

The pose, or null when no session is running and before the first aim settles.

isActive()

isActive(): boolean

Whether a placement session is running at this client right now.

Returns

boolean

True while one is up.

on()

on(event, handler): Unsubscribe

Listens for one of the session’s events. Handlers belong to the resource that registered them and go when it stops.

Parameters

event

"rejected" | "move" | "confirm" | "cancel" | "end"

move fires when the aim has travelled far enough to be worth reporting, and whenever the spot flips between accepted and refused – it is throttled on purpose, because it is the one event that could otherwise fire every frame. confirm is a click the rules accepted, and is the one to send to the server. rejected is a click they refused, so the resource can say why; the session stays up. cancel is the player backing out. end is the session stopping, however it stopped, and is always the last one.

handler

PlacementHandler<PlacementPose>

Called with where the placement is aimed and whether that spot is accepted. The pose is null for cancel and end.

Returns

Unsubscribe

A function that removes this subscription.

rotate()

rotate(degrees): boolean

Turns the preview, the same way the mouse wheel does while a session is up.

Parameters

degrees

number

How far to turn it, in degrees. Negative turns the other way.

Returns

boolean

True while a session is running.

setVeto()

setVeto(vetoed): boolean

Refuses every spot until cleared, which is where a rule the engine cannot answer belongs – what the player can afford, what the server has already said no to. It latches, so it costs the placement loop nothing.

Parameters

vetoed

boolean

Whether to refuse the spot whatever the rules say.

Returns

boolean

True while a session is running.