Class component

component
Defined in: component.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	component() Extends the functionality of an entity as a swappable object.

Field Summary
Field Attributes	Field Name and Description
	host The current host entity of the component.
	info Human-readable information on this component viable in the inspector/debugger.
	isDrawing Whether this component should have its draw() function called automatically by the engine.
	isStepping Whether this component should have its step() function called automatically by the engine.
	onAttach Function called when the component is attached to a host.
	onDraw Function called on the draw iteration of the component.
	onStep Function called on the step iteration of the component.
	tag Identifying tag of the component.

Method Summary
Method Attributes	Method Name and Description
	canHandleEvent(eventName) Returns whether the given event is installed.
	draw() Does the naturally defined draw iteration.
	emitEvent(eventName, source) Triggers the specified event for this component.
	getKnownEvents() Returns a list of all events installed that can be processed.
	installEvent(eventName, mainHandler) Adds a new event to be recognized by the EventSystem.
	installHandler(eventName, handler) Adds a handler to an event.
	installHook(eventName, hook) Adds a hook to the event.
	step() Does the naturally defined step iteration.
	uninstallEvent(event) Removes the event from the component.
	uninstallHandler(eventName) Removes a previously installed handler.
	uninstallHook(eventName) Removes the given hook.

Class Detail

component()

Extends the functionality of an entity as a swappable object.

To work, all components have hosts; when a host updates, all components do as well. Like entity, a component can have a Draw and a Step function with an overloadable OnStep / OnDraw. In addition, all component's also have event handling capabilities. Setable with strings, it is possible to maintain and assign functions to run on certain events and even define your own events for custom components.

When making your own components, you will typically also want to include your own custom events. installEvent() is the function that adds a new recognized event with the given name. Once installed, emitEvent() should be called at the appropriate time user functions should be run.

All components will emit the 2 fallowing events:

- on-attach: Called when the component is attached to an entity.
- on-detach: Called when the component is about to be destroyed.

Built-in components, like clock, have their installed events marked in their class descriptions.

Field Detail

host

The current host entity of the component. See entity.addComponent.

info

Human-readable information on this component viable in the inspector/debugger. For built-in components, this usually contains stats and useful info regarding the current state of the component.

isDrawing

Whether this component should have its draw() function called automatically by the engine. The default is true.

isStepping

Whether this component should have its step() function called automatically by the engine. The default is true.

onAttach

Function called when the component is attached to a host.

onDraw

Function called on the draw iteration of the component.

onStep

Function called on the step iteration of the component.

tag

Identifying tag of the component. The tag can be used in access functions such as entity.queryComponent.

Method Detail

canHandleEvent(eventName)

Returns whether the given event is installed.

Parameters:
{String} eventName: The event to query.

draw()

Does the naturally defined draw iteration. This invokes the "onDraw" property method if defined. For built-in components, this may trigger native code. For hosts that are part of the engine hierarchy, draw() is called for you when the entity draw()s.

emitEvent(eventName, source)

Triggers the specified event for this component. Returns whether the event was allowed to propogate all the way to the main handler (in other words, lets you know whether all the handlers allowed the event to happen) Source is passed to the handler and is usually the source of the event (but does not have to be)

Parameters:
{String} eventName: Name of the event. This should match the name that was installed.
{entity} source: (Optional) entity that indicates the source of the event. For example, in a collision, this may be the object collided with.

{Array} getKnownEvents()

Returns a list of all events installed that can be processed.

Returns:: {Array} An array of event name strings.

installEvent(eventName, mainHandler)

Adds a new event to be recognized by the EventSystem. if mainHandler is undefined, the event is still added, but has no default handler is set. The default handler is always guaranteed to run last for the event.

Parameters:
{String} eventName: The name of the new event to install.
{Function} mainHandler: (optional) The default handler for this event. Always called first before any hooks. See component.installHandler for parameters passed to handler function objects.

installHandler(eventName, handler)

Adds a handler to an event. Handlers that are added are run in LIFO order and their return values dictate whether the event should propogate. The last handler run for an event is always the main handler of the event.
Handler function signatures contain the following parameters:

{boolean} handler(component, componentHost, eventSource)

Where component is the this component, componentHost is the host entity of this component , and eventSource is the entity given from the emitEvent() call, if any. The return value is a boolean determining if the event should continue propogating. If no return value is given, the value is assumed true, meaning the event should propogate.

Parameters:
{String} eventName: Name of the installed event to add a handler to
{Function} handler: Function to add as the handler.

installHook(eventName, hook)

Adds a hook to the event. A hook happens at the end of a given event after all the handlers have been run. Hooks occur regardless of event handler propogation. Hook function signatures contain the following parameters:

hook(component, componentHost, eventSource)

Where component is the this component, componentHost is the host entity of this component , and eventSource is the entity given from the emitEvent() call, if any.

Parameters:
{String} eventName: Name of the installed event.
{Function} hook: The hook to add. See class description for function signature.

step()

Does the naturally defined step iteration. This invokes the "onStep" property method if defined. For built-in components, this may trigger native code. For hosts that are part of the engine hierarchy, step() is called for you when the entity step()s.

uninstallEvent(event)

Removes the event from the component.

Parameters:
{String} event: Event to remove.

uninstallHandler(eventName)

Removes a previously installed handler.

Parameters:
{String} eventName

uninstallHook(eventName)

Removes the given hook.

Parameters:
{String} eventName

Classes

Class component