Event

CubicVR.Event

The Event class is used to represent a universal triggerable event with a functional action. The event class is often instantiated transparently by passing an event object initializer to a class that supports the addEvent routine.

Constructor:

Event( obj_init )

Parameters:

Object Constructor:

• id : The event ID that will be triggered, it can be a custom event identifer or one of the CubicVR.enums.event built-in events.
• name : A Name supplied to the event, used for reference and debugging only.
• interval : The event interval in seconds, i.e. 1/10 for 10 calls per second. Interval 0 runs every frame, default: 0
• weight : (not yet implemented) A numeric value representing weight for the event to ensure some actions are called before others.
• enabled : Whether this event is enabled. A disabled event will bypass and drop any trigger calls. default: true
• properties : A user-defined set of parameters that can be obtained via event.getProperties() or individually via event.getProperty(name) and event.setProperty(name,value)
• buffered : By default every Event is unbuffered, meaning a call to event.getEventProperties() will return a single result set. If multiple events are triggered the action wil be called once for each. When buffering is enabled event.getEventProperties() will return an array with all results since the last interval
• action : A function in the format function(event, event_handler) where event is your Event object, and event_handler is the calling EventHandler. This will be called when the event is triggered.

Built-in Events:

Several classes in CubicVR already support events and have available triggers. Binding these triggers to a SceneObject will automatically initiate the event handling system. The following represent the options for the id event object constructor parameter.

• Scene

  • enums.event.TICK : Called once per interval.
  • enums.event.MOVE : Called when the SceneObject position changes.

• ScenePhysics

  • enums.event.COLLIDE : Called when a RigidBody makes contact with a predefined list of RigidBody objects.
  • enums.event.CONTACT : Called when a RigidBody makes contact with any other RigidBody, includes a ContactMap for evaluating every contact.
  • enums.event.CONTACT_GHOST : Called when a RigidBody makes contact or overlaps a ghost type RigidBody, efficent for simple triggering.

Warning that COLLIDE event may cause performance degredation if over-used.

Methods:

setId( id )

Set the Event ID.

Parameters:

• id : A user-defined string, number or built-in enum of CubicVR.enums.event.*

Returns:

none.

getId()

Get the Event ID.

Returns:

The numeric or string event identifier.

setName( name )

Set the name of the event, this is a user-defined property only.

Parameters:

• name : A name for the event.

Returns:

none.

getName()

Get the user-defined name for the event.

Returns:

none.

enable()

Enable the event and allow triggers to call it.

Returns:

none.

disable()

Disable the event and bypass and discard any trigger calls.

Returns:

none.

isEnabled()

Check the 'enabled' status of the event.

Returns:

true if enabled, false if not.

isBuffered()

Check if the event is currently buffered.

Returns:

true if buffered, false if not.

setBuffered( bval )

Set the buffering state for the event. When buffered, multiple event triggers since the last interval will be packed into a single array returned by event.getEventProperties(). If buffering is disabled it will call your action for each event trigger since the last interval and contain a single record in event.getEventProperties();

Parameters:

• bval : true to enable buffering, false to disable.

Returns:

none.

setInterval( timeSeconds )

Set the current timing interval, the interval is the rate at which the event is allowed to be called.

Parameters:

• timeSeconds : Minimum time in seconds between event calls.

Returns:

none.

getInterval()

Get the currently defined timing interval.

Returns:

Current timing interval in seconds.

getRestInterval()

Get the current 'rest' interval. The rest interval is the time remaining between now and the next allowable trigger event action interval.

Returns:

none.

setRestInterval( time )

Manually set the rest interval for the next frame

Parameters:

• time : Amount of time in seconds until the event is allowed to be called again.

Returns:

none.

rest( time )

Alias for setRestInterval(time)

Parameters:

• time : Amount of time in seconds until the event is allowed to be called again.

Returns:

none.

awake()

Alias for setRestInterval(0), allow immediate execution on the next trigger.

Returns:

none.

setAction( action )

Manually set the action callback function

Parameters:

• action : A new function in the format function(event, event_handler) to use for event triggering.

Returns:

none.

getProperty( propName )

Return a user-defined property belonging to this event.

Parameters:

• propName : The name of the property to retrieve

Returns:

The value of the property.

setProperty( propName, value )

Set the value of a user-defined event property.

Parameters:

• propName : The name of the property to set.
• value : The value to set the property to.

Returns:

none.

getProperties()

Return the object containing the user-defined properties.

Returns:

An object containing all user-defined properties for the event.

setProperties( props )

Set the useer-defined property object.

Parameters:

• props : An object containing user-defined properties.

Returns:

none.

getEventProperty( propName )

Retrieve the event property (or if buffered, an array of event properties) object for a triggered event. Each built-in event will contain it's own set of parameters, refer to the built-in events for details.

Parameters:

• propName : Name of property to get.

Returns:

Value of the event property.

setEventProperty( propName, value )

Used internally or when managing custom event handlers, this is used to set the outgoing trigger event properties.

Parameters:

• propName : Name of property to set.
• value : Value to set.

Returns:

none.

getEventProperties()

Get the event properties object.

Returns:

Object containing all event properties or if buffered, an array of event properties.

setEventProperties( props )

Used internally or when managing custom event handlers, this is used to set the outgoing trigger event properties object.

Parameters:

• props : An object containing the event properties.

Returns:

none.

getTimeSleeping()

Get the amount of time the event has been inactive.

Returns:

The amount of time in seconds the event has been resting, including time between interval events.

getTimeActive()

Get the amount of time the event has been active.

Returns:

The amount of time in seconds the event has been active.

getTimeUpdated()

Get the last time in seconds that this event was updated.

Returns:

Return the absolute time in seconds that this event was last updated (not called).

getLastUpdateSeconds()

Get the amount of time that occured between the start of the last interval and the immediate time.

Returns:

Return the amount of time in seconds since the event was last updated.

getUpdateCount()

Get the amount of times this event has been updated

Returns:

An integer of the number of calls to update() that have occured since the last enable().

breakChain()

During an event trigger call, this allows you to break any chained (buffered and waiting to call) events, preventing any further calls to that event for the current interval.

Returns:

none.