Boids Lua API

From Blue Mars Developer Guidebook

Jump to: navigation, search
There are security restrictions on this article

Contents

Overview

Boids are lightweight objects that move together in a flock. Each boid object is not as fully featured as an entire entity - it has position, direction, a model, and optionally, animation.

A flock of boids is attached to an entity (via an entity "boid proxy"). The entity position is the flock origin, around which the flock's boid objects spawn and move. Entity scripts for the available types of boids are in Game/Scripts/Entities/Boids

Image:Boids.png

See the Sandbox Manual for a description of the boids properties listed in the Sandbox Editor and Boids Asset Creation for tips on creating models and animation for boids.

Constants

There are several variations of flocking behavior enumerated by these Lua constants:

FLOCK_BIRDS
FLOCK_BUGS
FLOCK_FROGS
FLOCK_BIRDS
FLOCK_FISH
FLOCK_CHICKENS
FLOCK_TURTLES

Functions

The boid functions are in the Boids table. Like the Entity functions, the boid functions operate on entities, but require the entity to be passed in as the first parameter. For example, the boid entity scripts in Game/Scripts/Entities/Boids typically have something like:

Boids.CreateFlock(self,FLOCK_BUGS,params);

Flocks

These functions create and control flocks


CreateFlock(entity, nType, tParamsTable)
create a new flock
entity - entity that owns the new flock
nType - type of the flock, one of the constants listed above
tParamsTable - table flock parameters
example - used in each of the boid entity scripts in Game/Scripts/Entities/Boids to create the associated flock

The flock parameters table can contain any of the following name-value pairs:


count 
integer - number of individual objects to spawn default - 0
model 
string - Geometry for the boid, can be a character (.CHR) or static geometry (.CGF) default - nil
model1 
string - additional model default - nil
model2 
string - additional model default - nil
model3 
string - additional model default - nil
model4 
string - additional model default - nil
character 
string - character to use for the individual objects default - nil
animation 
string - animation to use for the individual objects default - nil
behavior 
integer - behavior default - 0
boid_mass 
float - mass of each object default - 0
boid_size 
float - scale factor of each object default - 0
boid_random_size 
float - Random variation on the size of the boid, as multiplication of the size parameter default - 0
min_height 
float - Minimal height boid can fly at (Height above land) default - 0
max_height 
float - Maximal height boids can fly to (Height above land) default - 0
min_attract_distance 
float - Minimal distance that boids are comfortable to stay close to each other before the separation force is starting to affect them default - 0
max_attract_distance 
float - Maximal distance at which one boid can see’s another boid. Boids that are too far away will not be interacted with. default - 0
min_speed 
float - Minimal speed that boid can move with default - 0
max_speed 
float - Maximal speed that boid can move with default - 0
factor_align 
float - Steer towards the average heading of local flockmates default - 0
factor_cohesion 
float - Steer to move toward the average position of local flockmates default - 0
factor_separation 
float - scale factor of each object default - 0
factor_origin 
float - Controls the force that attract boids to the origin point of the flock default - 0
factor_keep_height 
float - Controls the force that is applied to keep boids at the original height for the flock default - 0
factor_avoid_land 
float - Force coefficient to divert boid from the land or water default - 0
factor_random_accel 
float - random acceleration default - 0
max_anim_speed 
float - maximum animation speed default - 0
follow_player 
bool - not applicable in Blue Mars default - false
no_landing 
bool - Turns landing for birds flocks on/off default - false
avoid_water 
bool - flock avoids water default - false
avoid_obstacles 
bool - Boids will sense the physical environment and be diverted from the physical obstacled. This option adds more heavier physical checks on the boids and should be used carefully only when really needed. default - false
max_view_distance 
float - Maximal distance from which whole flock can be visible. If player camera is farer away from flock origin boids will not be simulated and rendered default - 0
planar_position 
float - default - 0
spawn_radius 
float - Maximual radius boid is spawned from the flock origin point default - 0
gravity_at_death 
float - Gravity acceleration that affects the body of the killed boid default - 0
boid_mass 
float - Mass of each individual boid default - 0
fov_angle 
float - Field of vision of the boid to consider other boids as flockmates, in degrees default - 0
Sounds 
table - List of sound names default - nil
Animations 
table - List of animation names default - nil


SetFlockParams(entity, tParamsTable)
modify the parameters of a flock
entity - entity that has the flock
tParamsTable - table flock parameters, same as with CreateFlock
example - used in each of the boid entity scripts in Game/Scripts/Entities/Boids to modify the associated flock


EnableFlock(entity, bEnable)
turn flock rendering/updating on/off
entity - entity that has the flock
example - used in each of the boid entity scripts in Game/Scripts/Entities/Boids to activate/deactivate the associated flock


SetFlockPercentEnabled(entity, fPercentage)
controls how much of the flock is visible
entity - entity that has the flock
example - used in each of the boid entity scripts in Game/Scripts/Entities/Boids to fade flock visibility


GetBoidsCount(entity)
query number of boids in a flock
return value - number of boids in a flock, nil if no flock
by Avatar Reality , last modified on 3/11/2009


GetBoidsSpawnRadius(entity)
query approximate the spawn radius of boids
return value - returns the boid spawn radius in this flock, as specified in the spawn_radius param
entity - entity that has the flock
by Avatar Reality , last modified on 4/2/2009


GetBoidsRadius(entity)
query approximate radius of boids, used in positioning terrain-bound boids
return value - returns the boid radius, derived from the axis-aligned bounding box of the boid model multipled by the scale, as specified in the boid-scale param
entity - entity that has the flock
by Avatar Reality , last modified on 4/2/2009


GetBoidsMass(entity)
query the mass of boids
return value - returns the boid mass, as specified in the boid-mass param
entity - entity that has the flock
by Avatar Reality , last modified on 4/2/2009


GetBoidsThickness(entity)
query the thickness of the boids (used in particle physics)
return value - returns the boid thickness, derived per flock type
entity - entity that has the flock
by Avatar Reality , last modified on 4/2/2009


Boids

These functions access info from individual boids of a flock. An individual boid is referenced by a number (starting with zero, within the range of the count passed in the flock parameters).


GetBoidPos(entity, boid)
get the position of a boid
return value - vector position of the boid, nil if no flock
boid - int index of the boid
by Avatar Reality , last modified on 3/10/2009


GetBoidAccel(entity, boid)
get the acceleration of a boid
return value - vector acceleration of the boid, nil if no flock
boid - int index of the boid
by Avatar Reality , last modified on 3/10/2009


GetBoidAccelTarget(entity, boid)
get the desired acceleration of a boid
return value - vector desired accleration of the boid, nil if no flock
boid - int index of the boid
by Avatar Reality , last modified on 3/10/2009


GetBoidHeading(entity, boid)
get the heading of a boid
return value - vector heading of the boid, nil if no flock
boid - int index of the boid
by Avatar Reality , last modified on 3/10/2009


GetBoidScale(entity, boid)
get the scale of a boid
return value - float scale of the boid, nil if no flock
boid - int index of the boid
by Avatar Reality , last modified on 3/10/2009


GetBoidSpeed(entity, boid)
get the speed of an individual boid object
return value - float speed of the boid, nil if no flock
boid - int index of the boid
by Avatar Reality , last modified on 3/10/2009


GetBoidBanking(entity, boid)
get the banking of the individual boid object
return value - float banking of the boid, nil if no flock
boid - int index of the boid
by Avatar Reality , last modified on 3/10/2009


GetBoidBankingTarget(entity, boid)
get the desired banking of the individual boid object
return value - float desired banking of the boid, nil if no flock
boid - int index of the boid
by Avatar Reality , last modified on 3/10/2009
Problems with this wiki page? Contact us either by: Support Email or Support Ticket System

Blue Mars Guidebook Privacy Policy
Blue Mars Guidebook Community Guidelines

Personal tools