Skip to content
MTA:SA Neon Documentation

createBird

Client-side
NEON APIScriptable birds

Available in Neon, not standard MTA

Creates a managed bird element with its own renderer and flight control.

Syntax

bird|false createBird(float x, float y, float z [, table options])

Arguments

xfloat

World X.

yfloat

World Y.

zfloat

World Z.

optionstableoptional

Optional preset, speed, size, renderDistance, wingBeatTime, curvedFlight, shootable, movementEnabled, bodyColor, wingColor and velocity fields.

Table keys

presetstringoptional · default "normal"

normal, water or desert. The presets differ visibly in size and flight cadence.

speedfloatoptional

Initial speed.

sizefloatoptional

Size multiplier.

renderDistancefloatoptional

Distance at which the bird fades out. It is not destroyed.

wingBeatTimefloatoptional

Wing beat period. Must be greater than zero.

curvedFlightbooloptional

Whether the bird banks through curves instead of flying straight.

shootablebooloptional

Whether the bird takes part in gunshot hit testing.

movementEnabledbooloptional

Whether the bird flies. False freezes it while the rest of a flock keeps moving.

bodyColorcoloroptional

Body colour.

wingColorcoloroptional

Wing colour.

velocitytableoptional

Starting velocity as {x, y, z}.

Returns

A bird element, or false when the position or options are rejected.

Ownership and lifecycle

A bird belongs to the client resource that created it and is removed when that resource stops. Birds fade near their render distance instead of being destroyed, and a dimension or interior mismatch hides them while keeping the element alive.

Important behavior
  • preset accepts normal, water or desert, which differ visibly in size and flight cadence.
  • Every option field is optional; omitted fields keep the preset default.
  • Managed birds are not bound by GTA's six native ambient bird slots. The harness runs 128 at once.
  • GTA's own ambient birds keep spawning and behaving independently.

OOP aliases

  • Bird.create(x, y, z, options)

Example

local bird = createBird(x, y, z, {
    preset = "desert",
    size = 1.5,
    shootable = true,
})

Where this comes from

SOURCECLuaBirdDefs.cppClient/mods/deathmatch/logic/luadefs/CLuaBirdDefs.cpp INTRODUCED / EXTENDED23fedfbc9Read the commit and why the change was made TEST RESOURCE bird-test test-resources/bird-test
RELATED NEON APIS

Continue exploring

Read the system guide →
processBirdGunShot Runs a gunshot trace against every shootable managed bird, for custom weapon systems. getBirdVelocity Returns the current velocity of a managed bird. setBirdVelocity Sets a managed bird's velocity immediately.

← Back to the Neon Lua API · How Scriptable birds works →