BSDE Spec 0.02

Features that are RED are incomplete/unimplemented.
Features that are PURPLE are deprecated.

Constants

Various properties will be assigned constant values.
The exact meaning of a constant, when used, will depend on the context it is used in.

Constant Ranges

Lower	Upper	Description
0	255	Small numbers with a context-defined meaning
256	8191	Reserved for 'officially defined' constants
8192	16383	Reserved for 'locally defined' constants (eg: for a particular implementation)
16384	32767	Reserved for experimental and/or dynamically assigned values
32768	65535	Larger set of context-defined numbers
65536+		Invalid

IO Type Modifiers
    I, integer;
    B, bool;
    F, float;
    V2/3/4, Vector of described length;
    M22/33/44, Matrix of described size;
    IV, integer vector.

Global Values

Name	Value	Description
BSDE_FALSE	0	Logical False Value passed to functions.
BSDE_TRUE	1	Logical True Value passed to functions.

Object Vector Properties

0x0100..0x011F

Name	Value	IO	Description
BSDE_ORIGIN BSDE_ORIGIN_0	0x0100	R/W	The origin for an object
BSDE_VELOCITY	0x0101	R/W	The linear velocity for an object
BSDE_TORQUE	0x0102	R/W	The torque at the center of mass for an object
BSDE_ANGULAR_VELOCITY	0x0103	R/W	The angular velocity at the center of mass
BSDE_ROTATION	0x0104	R/W	A quaternion giving the rotation at the center of mass
BSDE_MINS	0x0105	R/W	The minimum extents for an AABB or OBB
BSDE_MAXS	0x0106	R/W	The maximum extents for an AABB or OBB
BSDE_MASS_OFFSET	0x0107	R/W	The offset of the center of mass relative to the origin for an object
BSDE_INERTIA_TENSOR	0x0108	R/W, M33	A 3x3 matrix giving the distribution of mass relative to the center of mass for an object
BSDE_DIRECTION BSDE_DIRECTION_0	0x0109	R/W, V3/4	The direction of orientation for an object/joint
BSDE_ORIGIN_A	0x010A	R/W	The origin on object A for a joint
BSDE_ORIGIN_B	0x010B	R/W	The object on object B for a joint
BSDE_ORIGIN_RA	0x010C	R/W	The origin on object A for a joint in object A's local space
BSDE_ORIGIN_RB	0x010D	R/W	The origin on object B for a joint in object B's local space
BSDE_DIRECTION_A	0x010E	R/W	Axis on Object A
BSDE_DIRECTION_B	0x010F	R/W	Axis on Object B
BSDE_DIRECTION_RA	0x0110	R/W	Axis on Object A in local space
BSDE_DIRECTION_RB	0x0111	R/W	Axis on Object B in local space
BSDE_ROTATION_MATRIX	0x0112	R, M33	3x3 matrix giving rotation.
BSDE_NORMAL	0x0113	V4	Normal vector
BSDE_VERTICES	0x0114	R	A set of vertices for an object
BSDE_CONTACT_VELOCITY	0x0115	R/W	Velocity at contact points (walking, ...)
BSDE_ACCELERATION	0x0116	R/W	Global acceleration at the center of mass
BSDE_LOCAL_THRUST	0x0117	R/W	Local acceleration at the center of mass
BSDE_ORIGIN_1	0x0118	W	Second origin
BSDE_ORIGIN_2	0x0119	W	Third origin
BSDE_ORIGIN_3	0x011A	W	Fourth origin
BSDE_DIRECTION_1	0x011B	W	Second direction
BSDE_ORIGIN_123	0x011C	W	Set base origin and generate others

Object Float Properties

0x0120..0x013F

Name	Value	IO	Description
BSDE_HEIGHT	0x0120	R/W	The height for an object
BSDE_RADIUS	0x0121	R/W	The radius for an object
BSDE_MASS	0x0122	R/W	The mass for an object
BSDE_VOLUME	0x0123	R/W	The volume for an object
BSDE_DENSITY	0x0124	R/W	The density for an object
BSDE_ELASTIC	0x0125	R/W	The elastic value for object surfaces
BSDE_FRICTION	0x0126	R/W	The friction value for object surfaces Friction is presently defined as (roughly) f₀f₁v/(v²+1)
BSDE_VISCOSITY	0x0127	R/W	The viscosity of a fluid
BSDE_CONTACT_POWER	0x0128	R/W	Power at contact point
BSDE_STRENGTH BSDE_STRENGTH_0	0x0129	R/W	The strength of a force/joint constraint
BSDE_STRENGTH_1	0x012A	R/W	Second strength
BSDE_STRENGTH_2	0x012B	R/W	Third strength
BSDE_STRENGTH_3	0x012C	R/W	Fourth strength
BSDE_CONSTANT_ATTENUATION	0x012D	R/W	Constant Attenuation (C) (Joints)
BSDE_LINEAR_ATTENUATION	0x012E	R/W	Linear Attenuation (B) (Joints)
BSDE_QUADRATIC_ATTENUATION	0x012F	R/W	Quadratic Attenuation (A) (Joints) Together these form a quadratic: Ax²+Bx+C

Object Integer/Boolean Properties

0x0140..0x015F

Name	Value	IO	Description
BSDE_SOLIDTYPE	0x0140	R	The solid-type for an object
BSDE_MOVEFLAGS	0x0141	R	A set of flags for the object
BSDE_NOSPIN	0x0142	R/W, B	Object can't rotate
BSDE_NOMOVE	0x0143	R/W, B	Object can't move
BSDE_NOGRAVITY	0x0144	R/W, B	Object is uneffected by gravity
BSDE_STATIC	0x0145	R/W, B	Object does not move and otherwise ignores physics
BSDE_SEMISTATIC	0x0146	R/W, B	Object may move but otherwise ignores physics
BSDE_FLUID	0x0147	R/W, B	Object is a fluid
BSDE_NONSOLID	0x0148	R/W, B	Object is non-solid
BSDE_TRIGGER	0x0149	R/W, B	Object is a trigger
BSDE_NUM_FACES	0x014A	R	Number of faces for a hull or trimesh
BSDE_NUM_VERTICES	0x014B	R	Number of vertices for a hull or trimesh

Object Integer Vector Properties

0x0160..0x017F

Name	Value	IO	Description
BSDE_FACE_VERTICES	0x0160	R	Vertex numbers for each vertex in each face
BSDE_FACE_COUNTS	0x0161	R	The number of vertices for each face

World Properties

0x0180..0x019F

Name	Value	IO	Description
BSDE_GRAVITY	0x0180	R/W, V3	Gravity Vector
BSDE_MAXSTEP	0x0181	R/W, F	Maximal/Main internal timestep
BSDE_MINSTEP	0x0182	R/W, F	Minimal internal timestep
BSDE_MAXFRAME	0x0183	R/W, F	Maximum amount of time/frame
BSDE_REALTIME	0x0184	R, F	Total amount of time step has been called with
BSDE_WORLDTIME	0x0185	R, F	The approximate time within the simulation
BSDE_CONTACT_SELF	0x0186		Array of self handles for contact array
BSDE_CONTACT_OTHER	0x0187		Array of other handles for contact array
BSDE_CONTACT_ORIGIN	0x0188		Vector for each contact point
BSDE_CONTACT_NORMAL	0x0189		Normal for each contact point
BSDE_TRIGGER_ARRAY	0x018A	R/W, IV	Pairs of handles for trigger behavior
BSDE_COLLIDE_STRICT	0x018B	R/W, B	Attempt to avoid interpenetration whenever possible.
BSDE_FRAME_PASSES	0x018C	R/W, I	(implementation specific) Recommended number of passes to take when simulating a frame.

Solid Types

0x0210..0x023F

Name	Value	Description
BSDE_SOLID_OTHER	0x0210	"Other" solid types
BSDE_SOLID_AABB	0x0211	Axis-Aligned-Bounding-Box
BSDE_SOLID_OBB	0x0212	Oriented-Bounding-Box
BSDE_SOLID_SPHERE	0x0213	Sphere
BSDE_SOLID_CYLINDER	0x0214	Flat topped cylinder
BSDE_SOLID_CCYLINDER BSDE_SOLID_CAPSULE	0x0215	Sphere capped cylinder
BSDE_SOLID_PLANE	0x0216	Solid Plane
BSDE_SOLID_TRIMESH	0x0217	Triangular Mesh
BSDE_SOLID_HULL	0x0218	Convex Hull
BSDE_SOLID_BSP	0x0219	BSP Tree

Joint Types

0x0240..0x0280

Name	Value	Description
BSDE_JOINT_OTHER	0x0240	"Other" joint type
BSDE_JOINT_BALL	0x0241	Keeps Joint Origins together
BSDE_JOINT_HINGE	0x0242	Works like a ball, but also keeps direction vectors together
BSDE_JOINT_SLIDER	0x0243	Allows sliding along an axis
BSDE_JOINT_UNIVERSAL	0x0244	Works like a ball, but keeps direction vectors at 90 degrees
BSDE_JOINT_FIXED	0x0245	"Welds" objects together
BSDE_JOINT_ELASTIC	0x0246	Pulls joint origins together with a defined force when the distance exceeds the radius. Attenuation factors effect the force: f=Ad²+Bd+C

Data Types

0x0280..0x02BF

Name	Value	Description
BSDE_BYTE	0x0280	Signed byte value
BSDE_UNSIGNED_BYTE	0x0281	Unsigned byte value
BSDE_SHORT	0x0282	Signed short
BSDE_UNSIGNED_SHORT	0x0283	...
BSDE_INT	0x0284
BSDE_UNSIGNED_INT	0x0285
BSDE_FLOAT	0x0286
BSDE_DOUBLE	0x0287
BSDE_2_BYTES	0x0288
BSDE_3_BYTES	0x0289
BSDE_4_BYTES	0x028A
BSDE_2_SHORTS	0x028B
BSDE_3_SHORTS	0x028C
BSDE_4_SHORTS	0x028D
BSDE_2_INTS	0x028E
BSDE_3_INTS	0x028F
BSDE_4_INTS	0x0290
BSDE_2_FLOATS	0x0291
BSDE_3_FLOATS	0x0292
BSDE_4_FLOATS	0x0293
BSDE_2_DOUBLES	0x0294
BSDE_3_DOUBLES	0x0295
BSDE_4_DOUBLES	0x0296

Construction Related

0x02C0..0x02FF

Name	Value	Description
BSDE_BSP_LEAF	0x02C0	BSP Leaf
BSDE_BSP_NODE	0x02C1	BSP Node
BSDE_BSP_FACE	0x02C2	BSP Face

Functions

General

void bsdeSRand(bsdeUInt seed);
void bsdeSRand2(bsdeUInt seed1, bsdeUInt seed2);

Set seed values for the random number generators.
If the initial seeds are not set, then random number generation will use some default seed instead or will otherwise be initialized in an implementation defined manner.
If these are to be used, they should be called before the first call to bsdeNewWorld.
These may be no-op if the implementation does not use an RNG, or if some other condition exists.

char *bsdeGetString(int str);

Get a null-terminated string describing some aspect of the implementation.

Name	Value	Description
BSDE_NULL	0	An empty string.
BSDE_CREATOR	1	The name of the creator of this implementation.
BSDE_ENGINE	2	The name of the implementation. This should fairly uniquely identify the implementation and should not change between implementation versions.
BSDE_ENGINE_VER	3	The version of the implementation. If one engine has multiple varieties, (for example, a standalone and networked version, or a software and hw-accel version), these should be encoded in this string, along with any other info that is expected to vary. The exact structure and meaning of the contents of this string may depend on the implementation.
BSDE_VERSION	4	The newest version of the specification the implementation conforms to.
BSDE_EXTENSIONS	5	A space seperated list of known extensions.
Reserved	6 to 127	A set of currently reserved string numbers.
Implementation Defined	128 to 255	A set of implementation specific strings.

The returned value for any unknown string number is to be NULL.

World

int bsdeNewWorld();
Create a new world.
At least a single default world is needed for the simulation.
Each world is completely seperate. It is not possible for objects located in different worlds to interact, and handles related to objects in one world are invalid in another (or may refer to a different object).

void bsdeBindWorld(int i);
Set the current world.
Any objects or joints created will be created within the context of the current world.

void bsdeStepWorld(double dt);
Step the world by a certain amount of time.

double bsdeGetWorldAttrF(int var);
void bsdeSetWorldAttrF(int var, double val);
int bsdeGetWorldAttrI(int var);
void bsdeSetWorldAttrI(int var, int val);
void bsdeGetWorldAttrFV(int var, float *val, int n);
void bsdeSetWorldAttrFV(int var, float *val, int n);
void bsdeGetWorldAttrDV(int var, double *val, int n);
void bsdeSetWorldAttrDV(int var, double *val, int n);

Get/Set world attributes.
For vector types, a count is passed indicating the size of the vector being get/set.

Triggers

int *bsdeGetTriggerArray();
int bsdeGetTriggerArrayPos();
void bsdeResetTriggerArray();
void bsdeSetTriggerArray(int *arr, int num);

Get/Set the trigger array.
The trigger array is used for reporting contact between objects that are marked as triggers, and is represented as an array of integer pairs (the first holding 'self', the other, 'other').
For each trigger there will be 1 entry for each object it makes contact with.

Reseting the trigger array position sets it to be 0, meaning that the array can be refilled.
Each world will have a seperate trigger array.

Objects/Solids

int bsdeNewAABB(double mx, double my, double mz,double nx, double ny, double nz);
int bsdeNewOBB(double mx, double my, double mz,double nx, double ny, double nz);
int bsdeNewSphere(double radius);
int bsdeNewCylinder(double height, double radius);
int bsdeNewCappedCylinder(double height, double radius);
int bsdeNewPlane(double x, double y, double z, double d);
int bsdeNewHullF(float *norms, int n);
int bsdeNewHullD(double *norms, int n);
int bsdeNewTriMeshF(float *vecs, int *tris, int nv, int nt);
int bsdeNewTriMeshD(double *vecs, int *tris, int nv, int nt);

Create an object/solid of the specified type.
Note that OBBs are currently required to be centered with their origins.
For planes, d points in the positive direction along the normal.
Hulls are passed as arrays of 4 values comprising each plane, likewise, d points in the positive direction of the normal.

TriMeshes are passed as 2 arrays, 1 of vertices, and the other of triangles. Each vertex occupies 3 values, and vertex indices start at 0.

void bsdeHide(int obj);
void bsdeUnhide(int obj);

Hide or Unhide an object.
A hidden object will be ignored in the simulation of the world.

void bsdeDestroy(int obj);
Remove an object from the simulation and free the memory used by the object.

double bsdeGetAttrF(int obj, int var);
void bsdeSetAttrF(int obj, int var, double val);
int bsdeGetAttrI(int obj, int var);
void bsdeSetAttrI(int obj, int var, int val);
void bsdeGetAttrFV(int obj, int var, float *val, int n);
void bsdeSetAttrFV(int obj, int var, float *val, int n);
void bsdeGetAttrDV(int obj, int var, double *val, int n);
void bsdeSetAttrDV(int obj, int var, double *val, int n);
void bsdeGetAttrIV(int obj, int var, int *val, int n);
void bsdeSetAttrIV(int obj, int var, int *val, int n);

Get/Set object attributes.
For vector types, a count is passed indicating the size of the vector being get/set.

Joints

int bsdeNewJoint(int type);
void bsdeBindJointSolids(int obj, int obja, int objb);
double bsdeGetJointAttrF(int obj, int var);
void bsdeSetJointAttrF(int obj, int var, double val);
int bsdeGetJointAttrI(int obj, int var);
void bsdeSetJointAttrI(int obj, int var, int val);
void bsdeGetJointAttrFV(int obj, int var, float *val, int n);
void bsdeSetJointAttrFV(int obj, int var, float *val, int n);
void bsdeGetJointAttrDV(int obj, int var, double *val, int n);
void bsdeSetJointAttrDV(int obj, int var, double *val, int n);

Object Construction

void bsdeBegin(int type);
int bsdeEnd();

Begin/End construction of something.
These may be nested for the construction of compound objects.
At the toplevel, bsdeEnd() will return the handle of the constructed object.

At the time of this writing only BSP trees may be created in this way.

void bsdeVertex3f(double x, double y, double z);
void bsdeVertex4f(double x, double y, double z, double w);
void bsdeVertex3d(double x, double y, double z);
void bsdeVertex4d(double x, double y, double z, double w);
void bsdeVertex3fv(float *v);
void bsdeVertex4fv(float *v);
void bsdeVertex3dv(double *v);
void bsdeVertex4dv(double *v);
void bsdeNormal3f(double x, double y, double z);
void bsdeNormal4f(double x, double y, double z, double w);
void bsdeNormal3d(double x, double y, double z);
void bsdeNormal4d(double x, double y, double z, double w);
void bsdeNormal3fv(float *v);
void bsdeNormal4fv(float *v);
void bsdeNormal3dv(double *v);
void bsdeNormal4dv(double *v);

Pass a vertex or normal to be used in constructing an object.
Note that normals are treated like vertices, and not like an implicit property applied to vertices.
The exact meaning of a vertex or normal is context dependent.

void bsdeAttrI(int var, int val);
void bsdeAttrF(int var, double val);
void bsdeAttrIV(int var, int *val, int num);
void bsdeAttrFV(int var, float *val, int num);
void bsdeAttrDV(int var, double *val, int num);

Pass an attribute to be used in object construction.
The meaning of an attribute may depend on context.