> For the complete documentation index, see [llms.txt](https://docs.cuxial.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuxial.com/scripts/interface/cuxial-emotes/developers.md). # Exports & events Public exports, events and player states of Cuxial Emotes for use from other resources. Other resources can play and cancel emotes, lock the player, change walk styles and read what the player is doing. Anything not listed on this page is internal. All client exports act on the local player unless stated otherwise. ## Client exports ### Play and cancel | Export | Parameters | Returns | What it does | | --------------------- | ------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PlayEmoteByCommand` | `command: string`, `variant?: number` | `boolean` | Plays an emote, scenario, walk style or expression by its command. Returns `false` if the command does not exist, the player is locked or the cooldown is active. | | `StartAnimationPlay` | `command: string`, `variant?: number` | — | Same as above, without a return value. | | `PlayEmote` | `data: table`, `variation?: number` | `boolean` | Plays an emote from its data table, as returned by `findEmoteByCommand`. | | `playScenario` | `name: string` | — | Starts a GTA scenario in place. Does nothing in a vehicle or while locked. | | `CancelEmote` | `skipReset?: boolean` | — | Cancels the current emote. If an upper body emote is layered on top, only that one is cancelled. With `true` it stops everything at once, skips the exit animation and works even while locked. | | `StopAnimation` | `skipReset?: boolean` | — | Alias of `CancelEmote`. | | `CancelUpperLayer` | — | — | Cancels only the upper body animation layered on top of another emote. | | `CancelAllAnimations` | — | — | Clears emotes and movement states (hands up, crossed arms, pointing, prone). Does nothing while locked. | | `PlayAnimOnNPC` | `command: string`, `ped: number` | — | Plays an emote or scenario from the catalog on another ped. | ```lua local played = exports.cuxial_emotes:PlayEmoteByCommand('adjust') if not played then print('Emote could not be played') end -- later exports.cuxial_emotes:CancelEmote() ``` ### Lock and state | Export | Parameters | Returns | What it does | | ----------------------- | ----------------- | -------------- | ------------------------------------------------------------------------- | | `SetEmoteLock` | `locked: boolean` | — | While locked, the player cannot start or cancel emotes, or open the menu. | | `IsEmoteLocked` | — | `boolean` | Whether the lock is active. | | `SetCanPlayAnimation` | `value: boolean` | — | Allows or blocks starting emotes. | | `CanPlayAnimation` | — | `boolean` | Whether emotes can be started. | | `SetCanCancelAnimation` | `value: boolean` | — | Allows or blocks cancelling the current emote. | | `SetAnimationPlaying` | `value: boolean` | — | Overrides the "an emote is playing" flag. | | `IsPlayingAnimation` | — | `boolean` | Whether an emote is playing. | | `isPlayerDead` | — | `boolean` | Whether the script considers the player dead, following `deadCheck`. | | `GetBaseLayer` | — | `table \| nil` | Current emote: `{ data, variation, dict, anim }`. | | `GetUpperLayer` | — | `table \| nil` | Current upper body emote, same shape. | | `HasUpperLayer` | — | `boolean` | Whether an upper body emote is layered. | ```lua -- Hold the player in a scripted animation exports.cuxial_emotes:SetEmoteLock(true) -- ... your scene ... exports.cuxial_emotes:SetEmoteLock(false) ``` {% hint style="warning" %} Always release a lock you set. A locked player cannot use any emote until `SetEmoteLock(false)` is called. The lock is also released when the resource that set it stops. {% endhint %} ### Catalog | Export | Parameters | Returns | What it does | | --------------------- | --------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `findEmoteByCommand` | `command: string` | `table \| nil`, `string \| nil` | Emote data and its kind: `'emote'`, `'scenario'`, `'walk'` or `'expression'`. | | `buildAnimationsList` | — | `table[]` | The list shown in the menu. Each entry has `name`, `title`, `description`, `category` and `liked`. Emotes also carry `isSynced`, `icon`, `tags` and `added`. | | `GetAnimationFromSet` | `setIndex: number`, `animIndex: number` | `string \| nil` | Command stored in a slot of a quick set. | | `buildPropsFromData` | `props: table`, `variation?: number` | `table[]` | Converts an emote's `Options.Props` into `{ hash, bone, placement, variant }` entries. | | `CleanAllPedProps` | — | — | Removes the emote props attached to the player. | ```lua local emote, kind = exports.cuxial_emotes:findEmoteByCommand('atm') if emote then print(emote.Label, kind) end ``` ### Walk style, expression and aiming | Export | Parameters | Returns | What it does | | ---------------------- | --------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `SetWalk` | `clipset: string`, `skipSave?: boolean` | — | Applies a movement clipset, such as `'move_m@brave'`, and sets the `walkstyle` state. With `skipSave` it is not stored for the next session. | | `ResetWalk` | — | — | Returns to the default walk and clears the `walkstyle` state. | | `RestoreLastWalkStyle` | — | — | Applies the clipset in the `walkstyle` state again, or the default walk if there is none. | | `SetExpression` | `name: string`, `skipSave?: boolean` | — | Applies a facial expression, such as `'mood_angry_1'`. With `skipSave` it is not stored for the next session. | | `ResetExpression` | — | — | Returns to the default expression. | | `SetWeaponAnimation` | `dict?: string`, `name?: string` | — | Sets the animation played while aiming with a weapon listed in `data/weapons.lua`. Call it without arguments to clear it. | | `GetWeaponAnimation` | — | `string \| nil`, `string \| nil` | Current aiming dictionary and clip. | ```lua -- Your script changed the movement clipset with natives for an effect. -- When it ends, give the player their own walk style back. exports.cuxial_emotes:RestoreLastWalkStyle() ``` ### Movement | Export | Parameters | Returns | What it does | | ------------------ | ---------------- | ---------------- | ----------------------------------- | | `IsPlayerCrouched` | — | `boolean \| nil` | Crouching. | | `IsPlayerProne` | — | `boolean` | Lying prone. | | `IsPlayerCrawling` | — | `boolean` | Crawling. | | `IsHandUp` | — | `boolean` | Hands up. | | `IsPointing` | — | `boolean` | Pointing. | | `IsCrossArms` | — | `boolean` | Arms crossed. | | `IsInRagdoll` | — | `boolean` | In ragdoll triggered by the script. | | `SetPlayerCrouch` | `value: boolean` | — | Forces crouch on or off. | | `SetHandsUp` | `value: boolean` | — | Forces hands up on or off. | ```lua if exports.cuxial_emotes:IsHandUp() then -- the player is surrendering end ``` ### Position editor, photo mode and zones | Export | Parameters | Returns | What it does | | ------------------------- | ------------------ | -------------- | ------------------------------------------------------------------------------ | | `GetLockedEditPosition` | — | `table \| nil` | Position fixed with the position editor: `{ x, y, z, heading }`. | | `UnlockEditedPosition` | — | — | Releases that position. | | `IsPhotoModeActive` | — | `boolean` | Whether photo mode is open. | | `IsCameraActive` | — | `boolean` | Whether the free camera is in use. | | `GetActiveZones` | — | `string[]` | Internal names of the emote zones the player is inside, as `cuxial_zone_`. | | `IsInZone` | `zoneName: string` | `boolean` | Whether the player is inside the zone with that internal name. | | `GetActiveZoneCategories` | — | `string[]` | Names of the zone categories currently available in the menu. | ```lua if exports.cuxial_emotes:IsPhotoModeActive() then return end ``` ## Server exports ### ForcePlaySyncedEmote Starts a paired emote between two players without asking for confirmation. ```lua exports.cuxial_emotes:ForcePlaySyncedEmote(requesterId, responderId, senderCommand) ``` | Parameter | Type | Description | | --------------- | ------ | ----------------------------------------------------- | | `requesterId` | number | Server id of the player who performs `senderCommand`. | | `responderId` | number | Server id of the other player. | | `senderCommand` | string | Command of a synchronized emote. | Returns `boolean`: `true` if the emote started. It fails if either player is offline, both ids are the same, the command is not a synchronized emote with a valid `OtherEmote`, or the players are further apart than `sync.distance`. ```lua local started = exports.cuxial_emotes:ForcePlaySyncedEmote(source, targetId, 'rasurar') ``` ### Item exports `condom_closed`, `condom_open`, `pregnancy_test` and `hiv_test` are item hooks for `ox_inventory`. They are meant to be referenced from the item definition, not called by hand. See [Installation](/scripts/interface/cuxial-emotes/installation.md). ## Events ### cuxial\_emotes:OpenMenu Client, local. Opens the emote menu. Useful from a radial menu. ```lua TriggerEvent('cuxial_emotes:OpenMenu') ``` ### cuxial\_emotes:PlayQuickAnim Client, network event. Plays a slot of the active quick set. The slot goes in the second argument, in the shape radial menus use. ```lua TriggerEvent('cuxial_emotes:PlayQuickAnim', nil, { id = 1 }) ``` ### cuxial\_emotes:ChangeSet Client, network event. Switches the active quick set. ```lua TriggerEvent('cuxial_emotes:ChangeSet', nil, { id = 2 }) ``` Both quick set events exist only when `emotes.quickAnims` is `true`. ### cuxial\_emotes:server:syncedEmoteStarted Server, local. Fired every time a paired emote starts. ```lua AddEventHandler('cuxial_emotes:server:syncedEmoteStarted', function(requesterId, responderId, command) print(('%s and %s started %s'):format(requesterId, responderId, command)) end) ``` ## Player states The script writes these state bags on the player. Read them from any resource. | Key | Replicated | Value | | ------------------------------- | -------------- | ----------------------------------------------- | | `isInEmote` | Yes | `true` while an emote is playing. | | `inSynchronizedEmote` | Yes | Server id of the partner during a paired emote. | | `walkstyle` | Yes | Current movement clipset. | | `expression` | Yes | Current facial expression. | | `handsUp` | Yes | `true` while the hands are up. | | `emoteProps`, `emotePropsUpper` | Yes | Props of the current emote. | | `crouch` | No, local only | `true` while crouching. | ```lua -- server side if Player(source).state.handsUp then -- allow the search end ``` The script also reads two states that other resources set: | Key | Effect | | ----------- | ----------------------------------------------------------------- | | `dead` | The player counts as dead when `deadCheck.useStateBag` is `true`. | | `isLimited` | While it is set, the player cannot start emotes. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.cuxial.com/scripts/interface/cuxial-emotes/developers.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.