Manual Object Molecule

From oWiki

Jump to: navigation, search

Preference Dialog

Attributes

type

string ( r )
Type of this molecule, 'manualobject'.

pref.name

string ( r )
The scriptable name for this molecule. This name can be set using rename method dynamically.

pref.enableWhen

string ( r, w )
Specifies the event that activates this molecule. Default is 'load'.

pref.disableWhen

string ( r, w )
Specifies the event that deactivates this molecule. Default is 'none'.

pref.soundURL

string ( r, w )
Specifies the URL of the audio file attached to this mesh.

pref.terrainClampping

bool ( r, w )
Specifies whether this mesh will clamp to the terrain, if any.

pref.x

float ( r, w )
Specifies the x coordinate of this mesh's position.

pref.y

float ( r, w )
Specifies the y coordinate of this mesh's position.

pref.z

float ( r, w )
Specifies the z coordinate of this mesh's position.

pref.sx

float ( r, w )
Specifies the x component of this mesh's scale.

pref.sy

float ( r, w )
Specifies the y component of this mesh's scale.

pref.sz

float ( r, w )
Specifies the z component of this mesh's scale.

pref.dx

float ( r, w )
Specifies the x-dimension of this mesh's size.

pref.dy

float ( r, w )
Specifies the y-dimension of this mesh's size.

pref.dz

float ( r, w )
Specifies the z-dimension of this mesh's size.

pref.fX

float ( r, w )
Specifies the x compnent of this mesh's orientation as quaternion.

pref.fY

float ( r, w )
Specifies the y compnent of this mesh's orientation as quaternion.

pref.fZ

float ( r, w )
Specifies the z compnent of this mesh's orientation as quaternion.

pref.fW

float ( r, w )
Specifies the w compnent of this mesh's orientation as quaternion.

renderQueueGroup

int ( r, w )
Gets/Sets the rendering queue position of this mesh. Render queues are grouped to allow you to more tightly control the ordering of rendered objects. If you do not call this method, all Entity objects default to the default queue, which is fine for most objects. You may want to alter this if you want this entity to always appear in front of other objects, e.g. for a 3D menu system or such.

renderingDistance

float ( r, w )
Gets/Sets the distance at which the object is no longer rendered.

volume

float, [0.0, 1.0] ( r, w )
Gets/Sets the volume of the sound attached to this manual object.

currentTime

float ( r, w )
Gets/Sets the playback position (in secs) of the sound attached to this manual object.

duration

float ( r )
Gets the duration (in secs) of the sound attached to this manual object.

status

int ( r )
Polls for the current sound playing status.
Possible return values are:

Value	Description
AL_PLAYING	A sound track is playing.
AL_STOPPED	Sound track has stopped.

Methods

rename(n)

n: string

Rename this molecule.

show()

show this mesh object.

hide()

hide this mesh object.

update()

Force molecule to update with the current set of attributes.

clone()

Return: a molecule

Create a clone of this molecule.

attach(droplet)

droplet: a droplet object (e.g. app.box.droplet)

Attach this molecule to a droplet.

detach()

Remove this molecule from its droplet.

v: Vector3
ts: int

Translate this mesh along Cartesian axes. v is the movement along the axes.

Possible values for ts are:

Value	Description
TS_LOCAL	Transform is relative to the local space.
TS_PARENT	Transform is relative to the space of the parent node.
TS_WORLD	Transform is relative to world space.

getInheritScale()

Return: bool

Returns true if this node is affected by scaling factors applied to the parent node.

resetOrientation()

Resets the nodes orientation (local axes as world axes, no rotation).

setInitialDir( v )

v: Vector3

Defines the initial direction this mesh is facing.

setCastShadows( b )

b: bool

Specifies whether this mesh cast shadow.

setMaterialName( m )

m: string

Applies material to this mesh.

getMaterialName( i )

i: int
Return: string

Gets the material name applied to the selected sub-entity at index i.

enableAutoTracking( entity, dir, pos )

entity: molecule
dir: Vector3
pos: Vector3

If you enable auto-tracking, this mesh will automatically rotate to point it's -Z at the target every frame, no matter how the target moves.

dir is the local vector considered to be the usual 'direction' of the mesh; normally the local -Z but can be another direction.
pos is the target point in local space of the target node instead of the origin of the target node, for changing the look-at point.

disableAutoTracking()

Disable auto tracking of another entity.

attachSound( url )

url: string

Attach an audio track to the mesh, replace the existing one if any. The attached audio moves with the mesh during animation and creates 3D sound effect. Use Camera.listen() to hear the sound effects.

playSound( loop )

loop: bool

Play the attached sound track, loops if necessary.

pauseSound()

Pause the sound track.

stopSound()

Stop the sound track.

rewindSound()

Rewind the sound track to the beginning.

enableCollision( prmShape, size )

prmShape: int
size: Vector3

Enable collision detection for this mesh.

prmShape is the shape of the detection surface. size is the size of the bounding box for the mesh.
Possible values for prmShape are:

Value	Description
PRM_BOX	Standard primitive Box.
PRM_ELLIPSOID	Becomes a sphere when the size is the same for all 3 axis.
PRM_CYLINDER	Standard primitive cylinder.
PRM_CAPSULE	A cylinder with rounded tips.
PRM_CONE	Standard primitive cone.
PRM_CAPSULE	Standard primitive capsule.
PRM_CHAMFERCYLINDER	Filled-donut shape primitive.
PRM_CONVEXHULL	"wrap" around a set cloud of vertices. a convex hull is the smallest possible convex shape that fully encloses all points supplied.
PRM_PYRAMID	Standard primitive pyramid.
PRM_TREE	A primitive that is built dynamically from the vertice and index information of the mesh.

setCollisionMaterial( mat )

mat: string

Defines a collision material for this mesh. The material property will determine the behavior of collision against another mesh with the same or different material.

setCollidable( mat, b )

mat: string
b: bool

Set the materials defined by the interaction between the given material and the material of the mesh to be collidable or non-collidable by default.

setFriction( mat, statf, dynf )

mat: string
statf: float
dynf: float

Set the default coefficients of friction defined by the interaction between the given material and the material of the mesh. statf is static and dynf is dynamic coefficient. Default values for the default material are: Static: 0.9, Dynamic: 0.5.

setElasticity( mat, val )

mat: string
val: float

Sets the default coefficients of restitution (elasticity) for the material defined by the interaction between the given material and the material of the mesh. val must be a positive value. It is recommended that it be set to a value lower or equal to 1.0, default value is 0.4.

setSoftness( mat, val )

mat: string
val: float

Sets the default softness coefficients for the material defined by the interaction between the given material and the material of the mesh. val must be a positive value. It is recommended that it be set to value lower or equal to 1.0 A low value for val will make the material soft. A typical value is 0.15, default value is 0.1.

setSurfaceThickness( mat, val )

mat: string
val: float

Sets the surface thickness for the material defined by the interaction between the given material and the material of the mesh. val must be a positive value.

installPreCollisionCallback( mat, script )

mat: string
script: molecule

Install a pre-collision callback. The script molecule is called when a collision is about to happen between the given material and material of the mesh. Returning 0 from the script causes the collision to be ignored. Returning 1 will receive the subsequent collision callbacks. The input parameter, params, contains the following members:

params.me: the name of the mesh that is listening for collision.
params.peer: the name of the other mesh that triggers the collision.

installCollisionCallback( mat, script )

mat: string
script: molecule

Install a collision callback. The script molecule is called when a collision happens between the given material and material of the mesh. Returning 0 from the script causes the collision to be ignored. Returning 1 will receive the subsequent collision callbacks. The input parameter, params, contains the following members:

params.me: the name of the mesh that is listening for collision.
params.peer: the name of the other mesh that triggers the collision.
params.contacts: an array of Vector3. The points of collision.

setContactSoftness( i, val )

This function can only be called during collision callback.
i: int
val: float

Sets the softness coefficient of the indexed contact point in the params.contacts array.

setContactFrictionState( i, val, n )

This function can only be called during collision callback.
i: int
val: float
n: int

Enable or disable friction calculation for the indexed contact point in the params.contacts array.
val is the friction state, 0 makes the contact frictionless along the index tangent vector.
n is the index to the tangent vector. 0 for primary tangent vector or 1 for the secondary tangent vector.

setContactFriction( i, statf, dynf, n )

This function can only be called during collision callback.
i: int
statf: float
dynf: float
n: int

Sets the coefficients of friction along the selected tangent vector and for the indexed contact point in the params.contacts array.
statf is the static and dynf the dynamic coefficient.
n is the index to the tangent vector. 0 for primary tangent vector or 1 for the secondary tangent vector.

setContactElasticity( i, val )

This function can only be called during collision callback.
i: int
val: float

Sets the elasticity for the indexed contact point in the params.contacts array.

setContactNormalDirection( i, dir )

This function can only be called during collision callback.
i: int
dir: Vector3

This function changes the basis of the contact point to one where the contact normal is aligned to the new direction vector and the tangent direction are recalculated to be perpendicular to the new contact normal.

setContactNormalAcceleration( i, val )

This function can only be called during collision callback.
i: int
val: float

Force the contact point to have a non-zero acceleration along the contact normal.

rotateTangentDirections( i, dir )

This function can only be called during collision callback.
i: int
dir: Vector3

Rotate the tangent direction of the contact until the primary direction is aligned with the given direction, dir.

setContactTangentAcceleration( i, val, n )

This function can only be called during collision callback.
i: int
val: float
n: int

Force the contact point to have a non-zero acceleration along the surface plane.
n is the index to the tangent vector. 0 for primary tangent vector or 1 for the secondary tangent vector.

freeze()

Freezes the mesh. Removing it from physics simulation.

resume()

Resumes physics simulation for this mesh.

replicate( type, dim, mul, rpos, rsca, rori )

type: 0 or 1
dim: Vector3
mul: Vector3
rpos: Vector3
rsca: Vector3
rori: Vector3

Replicate the mesh.

type defines the method of replication.
dim is the box inside which each replicated entity is located.
mul is the multiplicity of the replication along the xyz-axes.
rpos introduces randomness to the position of each replicated entity in the box. Valid values are from (0, 0, 0) to (1, 1, 1).
rsca introduces randomness to the scale of each replicated entity in the box. Valid values are from (0, 0, 0) to (1, 1, 1).
rori introduces randomness to the orientation of each replicated entity in the box. Valid values are from (0, 0, 0) to (1, 1, 1).

undoReplicate()

Undo replication.

setMass( mass )

mass: float

Set the weight of this mesh.

setVelocity( dir )

dir: Vector3

Set the velocity of this mesh.

applyForce( force, dir, pos, time )

force: float
dir: Vector3
pos: Vector3
time: float

Apply a force of amplitude force and direction dir at a world position pos and for a time period given by time.

applyLocalForce( force, dir, pos, time )

force: float
dir: Vector3
pos: Vector3
time: float

Apply a force of amplitude force and direction dir at a mesh's local position pos and for a time period given by time.

applyTorque( amp, dir, time )

amp: float
dir: Vector3
time: float

Apply a torque to this mesh with amplitude amp and direction dir for a time period given by time.

setCenterOfMass( c )

c: Vector3

Sets the center of mass for this mesh.

getCenterOfMass()

Return: Vector3

Returns the location of this mesh's center of mass.

buildTangentVector()

Regenerate tangent vector along the mesh's surface.

When applying normal map, the mesh must have its surface tangents defined. If not, you can called this function to regenerate surface tangents.

setDynamic( b )

b: bool

Use before defining geometry to indicate that you intend to update the geometry regularly and want the internal structure to reflect that.

begin( mat, type )

mat: string
type: int

Begin drawing the 3D object.

mat is the name of the material to be applied to the object.

type is the method of contructing the 3D object.

Possible values for type are:

Value	Description
OT_POINT_LIST	A list of points, 1 vertex per point.
OT_LINE_LIST	A list of lines, 2 vertices per line.
OT_LINE_STRIP	A strip of connected lines, 1 vertex per line plus 1 start vertex.
OT_TRIANGLE_LIST	A list of triangles, 3 vertices per triangle.
OT_TRIANGLE_STRIP	A strip of triangles, 3 vertices for the first triangle, and 1 per triangle after that.
OT_TRIANGLE_FAN	A fan of triangles, 3 vertices for the first triangle, and 1 per triangle after that.

beginUpdate( s )

s: int

Using this method, you can update an existing section of the object efficiently. You do not have the option of changing the operation type obviously, since it must match the one that was used before.

s is the index of the section you want to update. The first call to begin() would have created section 0, the second section 1, etc.

addPoint( p )

p: Vector3

Add a point to the object under construction.

textureCoord( u, v )

u: float
v: float

Add a texture coordinate to the current vertex.

normal( n )

n: Vector3

Add a normal to the current vertex.

color( c )

c: RGBA

Add a color to the current vertex.

index( i )

i: int

Add a vertex index to construct faces / lines / points via indexing rather than just by a simple list of vertices. You will have to call this 3 times for each face for a triangle list, or use the alternative 3-parameter version. Other operation types require different numbers of indexes.

triangle( i1, i2, i3 )

i1: int
i2: int
i3: int

Add a set of 3 vertex indices to construct a triangle; this is a shortcut to calling index() 3 times. It is only valid for triangle lists.

quad( i1, i2, i3, i4 )

i1: int
i2: int
i3: int
i4: int

Add a set of 4 vertex indices to construct a quad (out of 2 triangles); this is a shortcut to calling index() 6 times, or triangle() twice. It's only valid for triangle list operations.

convertToMesh()

Convert this manual object into mesh.

getNumSections()

Returns the number of sub-sections of this manual object.

setUseIdentityProjection( b )

b: bool

Sets whether or not to use an 'identity' projection. Usually ManualObjects will use a projection matrix as determined by the active camera. However, if they want they can cancel this out and use an identity projection, which effectively projects in 2D using a {-1, 1} view space. Useful for overlay rendering. Normally you don't need to change this. The default is false.

setUseIdentityView( b )

b: bool

Sets whether or not to use an 'identity' view. Usually ManualObjects will use a view matrix as determined by the active camera. However, if they want they can cancel this out and use an identity matrix, which means all geometry is assumed to be relative to camera space already. Useful for overlay rendering. Normally you don't need to change this. The default is false.

Manual Object Molecule

From oWiki

Contents

Preference Dialog

Attributes

type

pref.name

pref.enableWhen

pref.disableWhen

pref.soundURL

pref.terrainClampping

pref.x

pref.y

pref.z

pref.sx

pref.sy

pref.sz

pref.dx

pref.dy

pref.dz

pref.fX

pref.fY

pref.fZ

pref.fW

renderQueueGroup

renderingDistance

volume

currentTime

duration

status

Methods

rename(n)

show()

hide()

update()

clone()

attach(droplet)

detach()

deleteMod()

serialize()

getBounds()

setPosition( v )

getPosition()

setSize( v )

getSize()

setScale( v )

getScale()

scale( v )

translate( v, ts )

translate( m3, v, ts )

roll( a, ts )

pitch( a, ts )

yaw( a, ts )

rotate( v, a, ts )

setVisible( b, cascade )

flipVisibility( cascade )

attachTo( entity )

detachFrom( entity )

setInheritOrientation( b )

getInheritOrientation( )

setInheritScale( b )

getInheritScale()

resetOrientation()

setInitialDir( v )

setCastShadows( b )

setMaterialName( m )

getMaterialName( i )

enableAutoTracking( entity, dir, pos )

disableAutoTracking()

attachSound( url )

playSound( loop )

pauseSound()

stopSound()

rewindSound()

enableCollision( prmShape, size )

setCollisionMaterial( mat )

setCollidable( mat, b )

setFriction( mat, statf, dynf )

setElasticity( mat, val )

setSoftness( mat, val )