Class Index | File Index

Classes


Namespace R.Engine

The main engine class which is responsible for keeping the world up to date. Additionally, the Engine will track and display metrics for optimizing a game. Finally, the Engine is responsible for maintaining the local client's worldTime.

The engine includes methods to load scripts and stylesheets in a serialized fashion and report on the sound engine status. Since objects are tracked by the engine, a list of all game objects can be obtained from the engine. The engine also contains the root rendering context, or "default" context. For anything to be rendered, or updated by the engine, it will need to be added to a child of the default context.

Other methods allow for starting or shutting down then engine, toggling metric display, setting of the base "frames per second", toggling of the debug mode, and processing of the script and function queue.

Since JavaScript is a single-threaded environment, frames are generated serially. One frame must complete before another can be rendered. By default, if frames are missed, the engine will wait until the next logical frame can be rendered. The engine can also run where it doesn't skip frames, and instead runs a constant frame clock. This doesn't guarantee that the engine will run at a fixed frame rate.
Defined in: engine.main.js.

Namespace Summary
Constructor Attributes Constructor Name and Description
 
Field Summary
Field Attributes Field Name and Description
<static>  
R.Engine.liveTime
The number of milliseconds the engine has been running.
<static>  
R.Engine.worldTime
The current time of the world on the client.
Method Summary
Method Attributes Method Name and Description
<static>  
R.Engine.addTimer(timerName, timer)
Add a timer to the pool so it can be cleaned up when the engine is shutdown, or paused when the engine is paused.
<static>  
R.Engine.create(obj)
Create an instance of an object within the Engine and get a unique Id for it.
<static>  
R.Engine.define(classDef)
Defines a new class.
<static>  
R.Engine.destroy(obj)
Destroys an object instance within the Engine.
<static>  
R.Engine.getActualFPS()
Get the actual FPS (frames per second) the engine is running at.
<static>  
R.Engine.getDebugMode()
Query the debugging mode of the engine.
<static>  
R.Engine.getDefaultContext()
Get the default rendering context for the Engine.
<static>  
R.Engine.getDrawTime()
Get the amount of time it took to draw the last frame.
<static>  
R.Engine.getEngineLoad()
Get the load the currently rendered frame is putting on the engine.
<static>  
R.Engine.getEnginePath()
Get the path to the engine.
<static>  
R.Engine.getFPS()
Get the FPS (frames per second) the engine is set to run at.
<static>  
R.Engine.getFrameTime()
Get the amount of time allocated to draw a single frame.
 
Get the game object that has been loaded by the engine.
<static>  
R.Engine.getObject(id)
Get an object by the Id that was assigned during the call to #create.
<static>  
R.Engine.include(scriptURL)
Include a script file.
<static>  
R.Engine.initObject(objectName, primaryDependency, fn)
See #define instead.
<static>  
R.Engine.isSoundEnabled()
Returns true if SoundManager2 is loaded and initialized properly.
<static>  
R.Engine.loadGame(gameSource, gameObjectName, gameDisplayName)
Loads a game's script.
<static>  
R.Engine.onShutdown(fn)
Add a method to be called when the engine is being shutdown.
<static>  
R.Engine.pause()
Pauses the engine and any running timers.
<static>  
R.Engine.removeTimer(timerName)
Remove a timer from the pool when it is destroyed.
<static>  
R.Engine.run()
Starts or resumes the engine.
<static>  
R.Engine.setDebugMode(mode)
Set the debug mode of the engine.
<static>  
R.Engine.setDefaultContext(defaultContext)
Override the engine's default context.
<static>  
R.Engine.setFPS(fps)
Set the FPS (frames per second) the engine runs at.
<static>  
R.Engine.shutdown()
Shutdown the engine.
<static>  
R.Engine.startup(debugMode)
Starts the engine and loads the basic engine scripts.
<static>  
R.Engine.step()
Steps the engine when paused.
<static>  
R.Engine.toString()
Prints the version of the engine.
Namespace Detail
R.Engine
Field Detail
<static> R.Engine.liveTime
The number of milliseconds the engine has been running. This time is updated for each frame generated by the Engine.

<static> R.Engine.worldTime
The current time of the world on the client. This time is updated for each frame generated by the Engine.
Method Detail
<static> R.Engine.addTimer(timerName, timer)
Add a timer to the pool so it can be cleaned up when the engine is shutdown, or paused when the engine is paused.
Parameters:
timerName
{String} The timer name
timer
{R.lang.Timer} The timer to add

<static> {String} R.Engine.create(obj)
Create an instance of an object within the Engine and get a unique Id for it. This is called by any object that extends from R.engine.PooledObject.
Parameters:
obj
{R.engine.PooledObject} An object within the engine
Returns:
{String} The global Id of the object

<static> R.Engine.define(classDef)
Defines a new class. The format of the object definition is:
R.Engine.define({
   "class": "[class name]",
   "requires": [
      "R.[package name].[dependency]"
   ],
   "depends": [
      "[dependency]"
   ],
   "includes": [
      "/path/to/file.js"
   ]
});
Each class must define its class name via the "class" key. This is the name that other classes will use to locate the class object. The "requires" key defines the classes within the engine that the class is dependent upon. Anything that falls into the "R." namespace should be declared as a requirement here. The "requires" key performs class loading for these objects automatically. In other words, you do not need to load classes which start with "R.".

If your class has dependencies on classes not defined in the "R" namespace, they should be declared via the "depends" array. These are classes which your game classes need to load via R.engine.Game#load calls. For files which just need to be loaded, use the "include" key to tell the engine where the file is.

Until all requirements, dependencies, and included files have been loaded and/or initialized, a class will, itself, not be initialized. Be aware of class dependencies so you do not create circular dependencies. First-level circular dependencies are okay, such as A requires B, while B requires A. But second, third, and so on circular dependencies will cause your classes to remain unresolved. The engine will not start the game, and an erro message will be sent to the console listing classes which were resolved and those which are unresolved.

The "requires", "includes" and "depends" keys are optional. You can either omit them entirely, set them to null, or assign an empty array to them.

The "depends" key is the only way your game classes can establish class dependencies which are not in the "R." namespace. Classes specified via the "depends" key are not loaded via the engine class loader like "requires" does. Instead, your game will need to load the classes. For example:

R.Engine.define({
   "class": "Foo",
   "requires": [
      "R.rendercontexts.CanvasContext"
   ],
   "depends": [
      "Bar"
   ]
});

// Load the Bar class
R.engine.Game.load("bar.js");
After receiving the definition, the engine will load R.rendercontexts.CanvasContext for Foo. The call to R.engine.Game.load("bar.js") would load the Bar class. When the context and Bar have loaded and initialized, Foo can be initialized which will enable any classes dependent on Foo to be initialized.
Parameters:
classDef
{Object} The object's definition

<static> R.Engine.destroy(obj)
Destroys an object instance within the Engine.
Parameters:
obj
{R.engine.PooledObject} The object, managed by the engine, to destroy

<static> {Number} R.Engine.getActualFPS()
Get the actual FPS (frames per second) the engine is running at. This value will vary as load increases or decreases due to the number of objects being rendered. A faster machine will be able to handle a higher FPS setting.
Returns:
{Number}

<static> {Boolean} R.Engine.getDebugMode()
Query the debugging mode of the engine.
Returns:
{Boolean} true if the engine is in debug mode

<static> {RenderContext} R.Engine.getDefaultContext()
Get the default rendering context for the Engine. This is the document.body element in the browser.
Returns:
{RenderContext} The default rendering context

<static> {Number} R.Engine.getDrawTime()
Get the amount of time it took to draw the last frame. This value varies per frame drawn, based on visible objects, number of operations performed, and other factors. The draw time can be used to optimize your game for performance.
Returns:
{Number} Milliseconds required to draw the frame

<static> {Number} R.Engine.getEngineLoad()
Get the load the currently rendered frame is putting on the engine. The load represents the amount of work the engine is doing to render a frame. A value less than one indicates the the engine can render a frame within the amount of time available. Higher than one indicates the engine cannot render the frame in the time available.

Faster machines will be able to handle more load. You can use this value to gauge how well your game is performing.

Returns:
{Number}

<static> {String} R.Engine.getEnginePath()
Get the path to the engine. Uses the location of the /runtime/engine.js file that was initially loaded to determine the URL where the engine is running from. When files are included, or classes are loaded, they are loaded relative to the engine's location on the server.
Returns:
{String} The path/URL where the engine is located

<static> {Number} R.Engine.getFPS()
Get the FPS (frames per second) the engine is set to run at.
Returns:
{Number}

<static> {Number} R.Engine.getFrameTime()
Get the amount of time allocated to draw a single frame.
Returns:
{Number} Milliseconds allocated to draw a frame

{R.engine.Game} getGame()
Get the game object that has been loaded by the engine. The game object isn't valid until the game is loaded.
Returns:
{R.engine.Game}

<static> {R.engine.PooledObject} R.Engine.getObject(id)
Get an object by the Id that was assigned during the call to #create. Only objects that are contained within other objects will be found. Discreetly referenced objects cannot be located by Id.
Parameters:
id
{String} The Id of the object to locate
Returns:
{R.engine.PooledObject} The object

<static> R.Engine.include(scriptURL)
Include a script file.
Parameters:
scriptURL
{String} The URL of the script file

<static> R.Engine.initObject(objectName, primaryDependency, fn)
See #define instead.
Parameters:
objectName
primaryDependency
fn

<static> {Boolean} R.Engine.isSoundEnabled()
Returns true if SoundManager2 is loaded and initialized properly. The resource loader and play manager will use this value to execute properly.
Returns:
{Boolean} true if the sound engine was loaded properly

<static> R.Engine.loadGame(gameSource, gameObjectName, gameDisplayName)
Loads a game's script. This will wait until the specified gameObjectName is available before running it. Doing so will ensure that all dependencies have been resolved before starting a game. Also creates the default rendering context for the engine.

All games should execute this method to start their processing, rather than using the script loading mechanism for engine or game scripts. This is used for the main game script only. Normally it would appear in the game's "index" file.

 <script type="text/javascript">
    // Load the game script
    Engine.loadGame('game.js','Spaceroids');
 </script>
Parameters:
gameSource
{String} The URL of the game script.
gameObjectName
{String} The string name of the game object to execute. When the framework if ready, the startup() method of this object will be called.
gameDisplayName Optional
{String} An optional string to display in the loading dialog

<static> R.Engine.onShutdown(fn)
Add a method to be called when the engine is being shutdown. Use this method to allow an object, which is not referenced by the engine, to perform cleanup actions.
Parameters:
fn
{Function} The callback function

<static> R.Engine.pause()
Pauses the engine and any running timers.

<static> R.Engine.removeTimer(timerName)
Remove a timer from the pool when it is destroyed.
Parameters:
timerName
{String} The timer name

<static> R.Engine.run()
Starts or resumes the engine. This will be called after all scripts have been loaded. You will also need to call this if you #pause the engine. Any paused timers will also be resumed.

<static> R.Engine.setDebugMode(mode)
Set the debug mode of the engine. Engine debugging enables helper objects which visually assist in debugging game objects. To specify the console debug message output level, see R.debug.Console@setDebuglevel.

Engine debug helper objects include:

Parameters:
mode
{Boolean} true to enable debug mode

<static> R.Engine.setDefaultContext(defaultContext)
Override the engine's default context. The engine will use the R.rendercontexts.DocumentContext as the default context, unless otherwise specified.
Parameters:
defaultContext
{R.rendercontexts.AbstracRenderContext} The context to use as the start of the scene graph.

<static> R.Engine.setFPS(fps)
Set the FPS (frames per second) the engine runs at. This value is mainly a suggestion to the engine as to how fast you want to redraw frames. If frame execution time is long, frames will be processed as time is available. See the metrics to understand available time versus render time.
Parameters:
fps
{Number} The number of frames per second to refresh Engine objects.

<static> R.Engine.shutdown()
Shutdown the engine. Stops the global timer and cleans up (destroys) all objects that have been created and added to the engine, starting at the default engine context.

<static> R.Engine.startup(debugMode)
Starts the engine and loads the basic engine scripts. When all scripts required by the engine have been loaded the #run method will be called.
Parameters:
debugMode
{Boolean} true to set the engine into debug mode which allows the output of messages to the console.

<static> R.Engine.step()
Steps the engine when paused. Any timers that were paused, stay paused while stepping.

<static> R.Engine.toString()
Prints the version of the engine.

Documentation generated by JsDoc Toolkit 2.4.0 on Mon Mar 18 2013 16:09:18 GMT-0400 (EDT)