Packageorg.ffilmation.engine.core
Classpublic class fScene
InheritancefScene Inheritance flash.events.EventDispatcher

The fScene class provides control over a scene in your application. The API for this object is used to add and remove elements from the scene after it has been loaded, and managing cameras.

Moreover, you can get information on topology, visibility from one point to another, search for paths and other useful methods that will help, for example, in programming AIs that move inside the scene.

The data structures contained within this object are populated during initialization by the fSceneInitializer class (which you don't need to understand).



Public Properties
 PropertyDefined by
  AI : fAiContainer
The AI-related method are grouped inside this object, for easier access
fScene
  all : Array
An array of all elements in this scene, use it with ID Strings.
fScene
  bullets : Array
All the bullets currently active in the scene are here
fScene
  characters : Array
An array of all characters for fast loop access.
fScene
  container : Sprite
Were this scene is drawn
fScene
  controller : fEngineSceneController
Retrieves controller from this scene
fScene
  depth : Number
Scene depth in pixels
fScene
  environmentLight : fGlobalLight
The global light for this scene.
fScene
  everything : Array
An array of all elements for fast loop access.
fScene
  floors : Array
An array of all floors for fast loop access.
fScene
  height : Number
Scene height in pixels
fScene
  id : String
Every Scene is automatically assigned and ID
fScene
  lights : Array
An array of all lights for fast loop access.
fScene
  objects : Array
An array of all objects for fast loop access.
fScene
  ready : Boolean
Indicates if the scene is loaded and ready
fScene
  stat : String
An string indicating the scene's current status
fScene
  walls : Array
An array of all walls for fast loop access.
fScene
  width : Number
Scene width in pixels.
fScene
Public Methods
 MethodDefined by
  
createBullet(x:Number, y:Number, z:Number, speedx:Number, speedy:Number, speedz:Number, renderer:fEngineBulletRenderer):fBullet
Creates a new bullet and adds it to the scene.
fScene
  
Creates a new camera associated to the scene
fScene
  
createCharacter(idchar:String, def:String, x:Number, y:Number, z:Number):fCharacter
Creates a new character an adds it to the scene
fScene
  
createOmniLight(idlight:String, x:Number, y:Number, z:Number, size:Number, color:String, intensity:Number, decay:Number, bumpMapped:Boolean = false):fOmniLight
Creates a new light and adds it to the scene.
fScene
  
disable():void
This Method is called to disable the scene.
fScene
  
enable():void
This Method is called to enable the scene.
fScene
  
initialize():void
Starts initialization process
fScene
  
removeBullet(bullet:fBullet):void
Removes a bullet from the scene.
fScene
  
Removes a character from the scene.
fScene
  
Removes an omni light from the scene.
fScene
  
render():void
Use this method to completely rerender the scene.
fScene
  
setCamera(camera:fCamera):void
This method sets the active camera for this scene.
fScene
  
Normally you don't need to call this method manually.
fScene
  
translate3DCoordsTo2DCoords(x:Number, y:Number, z:Number):Point
This method translates scene 3D coordinates to 2D coordinates relative to the Sprite containing the scene
fScene
  
translate3DCoordsToStageCoords(x:Number, y:Number, z:Number):Point
This method translates scene 3D coordinates to 2D coordinates relative to the Stage
fScene
  
translateStageCoordsTo3DCoords(x:Number, y:Number):Point
This method translates Stage coordinates to scene coordinates.
fScene
  
translateStageCoordsToElements(x:Number, y:Number):Array
This method returns the element under a Stage coordinate, and a 3D translation of the 2D coordinates passed as input.
fScene
Public Constants
 ConstantDefined by
  LOADCOMPLETE : String = "sceneloadcomplete"
[static] The fScene.LOADCOMPLETE constant defines the value of the type property of the event object for a sceneloadcomplete event.
fScene
  LOADINGDESCRIPTION : String = "Creating scene"
[static] An string describing the process of loading and processing and scene XML definition file.
fScene
  LOADPROGRESS : String = "scenecloadprogress"
[static] The fScene.LOADPROGRESS constant defines the value of the type property of the event object for a scenecloadprogress event.
fScene
Property detail
AIproperty
public var AI:fAiContainer

The AI-related method are grouped inside this object, for easier access

allproperty 
public var all:Array

An array of all elements in this scene, use it with ID Strings. Bullets are not here

bulletsproperty 
public var bullets:Array

All the bullets currently active in the scene are here

charactersproperty 
public var characters:Array

An array of all characters for fast loop access. For "id" access use the .all array

containerproperty 
public var container:Sprite

Were this scene is drawn

controllerproperty 
controller:fEngineSceneController  [read-write]

Retrieves controller from this scene

Implementation
    public function get controller():fEngineSceneController
    public function set controller(value:fEngineSceneController):void
depthproperty 
public var depth:Number

Scene depth in pixels

environmentLightproperty 
public var environmentLight:fGlobalLight

The global light for this scene. Use this property to change light properties such as intensity and color

everythingproperty 
public var everything:Array

An array of all elements for fast loop access. For "id" access use the .all array. Bullets are not here

floorsproperty 
public var floors:Array

An array of all floors for fast loop access. For "id" access use the .all array

heightproperty 
public var height:Number

Scene height in pixels

idproperty 
public var id:String

Every Scene is automatically assigned and ID

lightsproperty 
public var lights:Array

An array of all lights for fast loop access. For "id" access use the .all array

objectsproperty 
public var objects:Array

An array of all objects for fast loop access. For "id" access use the .all array

readyproperty 
public var ready:Boolean

Indicates if the scene is loaded and ready

statproperty 
public var stat:String

An string indicating the scene's current status

wallsproperty 
public var walls:Array

An array of all walls for fast loop access. For "id" access use the .all array

widthproperty 
public var width:Number

Scene width in pixels.

Method detail
createBullet()method
public function createBullet(x:Number, y:Number, z:Number, speedx:Number, speedy:Number, speedz:Number, renderer:fEngineBulletRenderer):fBullet

Creates a new bullet and adds it to the scene. Note that bullets use their own render system. The bulletRenderer interface allows you to have complex things such as trails. If it was integrated with the standard renderer, your bullets would have to be standard Sprites, and I dind't like that.

Note to developers: bullets are reused. Creating new objects is slow, and depending on your game you could have a lot being created and destroyed. The engine uses an object pool to reuse "dead" bullets and minimize the amount of new() calls. This is transparent to you but I think this information can help tracking weird bugs

Parameters
x:Number — Start position of the bullet
 
y:Number — Start position of the bullet
 
z:Number — Start position of the bullet
 
speedx:Number — Speed of bullet
 
speedy:Number — Speed of bullet
 
speedz:Number — Speed of bullet
 
renderer:fEngineBulletRenderer — The renderer that will be drawing this bullet. In order to increase performace, you should't create a new renderer instance for each bullet: pass the same renderer to all bullets that look the same.

Returns
fBullet
createCamera()method 
public function createCamera():fCamera

Creates a new camera associated to the scene

Returns
fCamera — an fCamera object ready to move or make active using the setCamera() method
createCharacter()method 
public function createCharacter(idchar:String, def:String, x:Number, y:Number, z:Number):fCharacter

Creates a new character an adds it to the scene

Parameters
idchar:String — The unique id that will identify the character
 
def:String — Definition id. Must match a definition in some of the definition XMLs included in the scene
 
x:Number — Initial x coordinate for the character
 
y:Number — Initial x coordinate for the character
 
z:Number — Initial x coordinate for the character

Returns
fCharacter
createOmniLight()method 
public function createOmniLight(idlight:String, x:Number, y:Number, z:Number, size:Number, color:String, intensity:Number, decay:Number, bumpMapped:Boolean = false):fOmniLight

Creates a new light and adds it to the scene. You won't see the light until you call its render() or moveTo() methods

Parameters
idlight:String — The unique id that will identify the light
 
x:Number — Initial x coordinate for the light
 
y:Number — Initial x coordinate for the light
 
z:Number — Initial x coordinate for the light
 
size:Number — Radius of the sphere that identifies the light
 
color:String — An string specifying the color of the light in HTML format, example: #ffeedd
 
intensity:Number — Intensity of the light goes from 0 to 100
 
decay:Number — From 0 to 100 marks the distance along the lights's radius from where intensity starrts to fade fades. A 0 decay defines a solid light
 
bumpMapped:Boolean (default = false) — Determines if this light will be rendered with bumpmapping. Please note that for the bumpMapping to work in a given surface, the surface will need a bumpMap definition and bumpMapping must be enabled in the engine's global parameters

Returns
fOmniLight
disable()method 
public function disable():void

This Method is called to disable the scene. It will disable all controllers associated to the scene and its elements. The engine no longer calls this method when the scene is hidden. Do it manually when needed. A typical use of manual enabling/disabling of scenes is pausing the game or showing a dialog box of any type.

See also

enable()method 
public function enable():void

This Method is called to enable the scene. It will enable all controllers associated to the scene and its elements. The engine no longer calls this method when the scene is shown. Do it manually when needed. A typical use of manual enabling/disabling of scenes is pausing the game or showing a dialog box of any type.

See also

initialize()method 
public function initialize():void

Starts initialization process

removeBullet()method 
public function removeBullet(bullet:fBullet):void

Removes a bullet from the scene. Bullets are automatically removed when they hit something, but you If you can't wait for them to be delete, you can do it manually.

Parameters
bullet:fBullet — The fBullet to be removed.
removeCharacter()method 
public function removeCharacter(char:fCharacter):void

Removes a character from the scene. This is not the same as hiding the character, this removes the element completely from the scene

Parameters
char:fCharacter — The character to be removed
removeOmniLight()method 
public function removeOmniLight(light:fOmniLight):void

Removes an omni light from the scene. This is not the same as hiding the light, this removes the element completely from the scene

Parameters
light:fOmniLight — The light to be removed
render()method 
public function render():void

Use this method to completely rerender the scene. However, under normal circunstances there shouldn't be a need to call this manually

setCamera()method 
public function setCamera(camera:fCamera):void

This method sets the active camera for this scene. The camera position determines the viewable area of the scene

Parameters
camera:fCamera — The camera you want to be active
startRendering()method 
public function startRendering():void

Normally you don't need to call this method manually. When an scene is shown, this method is called to initialize the render engine for this scene ( this involves creating all the Sprites ). This may take a couple of seconds.
Under special circunstances, however, you may want to call this method manually at some point before showing the scene. This is useful is you want the graphic assets to exist before the scene is shown ( to attach Mouse Events for example ).

translate3DCoordsTo2DCoords()method 
public function translate3DCoordsTo2DCoords(x:Number, y:Number, z:Number):Point

This method translates scene 3D coordinates to 2D coordinates relative to the Sprite containing the scene

Parameters
x:Number — x-axis coordinate
 
y:Number — y-axis coordinate
 
z:Number — z-axis coordinate

Returns
Point — A Point in this scene's container Sprite
translate3DCoordsToStageCoords()method 
public function translate3DCoordsToStageCoords(x:Number, y:Number, z:Number):Point

This method translates scene 3D coordinates to 2D coordinates relative to the Stage

Parameters
x:Number — x-axis coordinate
 
y:Number — y-axis coordinate
 
z:Number — z-axis coordinate

Returns
Point — A Coordinate in the Stage
translateStageCoordsTo3DCoords()method 
public function translateStageCoordsTo3DCoords(x:Number, y:Number):Point

This method translates Stage coordinates to scene coordinates. Useful to map mouse events into game events

Parameters
x:Number — x-axis coordinate
 
y:Number — y-axis coordinate

Returns
Point — A Point in the scene's coordinate system. Please note that a Z value is not returned as It can't be calculated from a 2D input. The returned x and y correspond to z=0 in the game's coordinate system.

Example
You can call it like
       function mouseClick(evt:MouseEvent) {
         var coords:Point = this.scene.translateStageCoordsTo3DCoords(evt.stageX, evt.stageY)
         this.hero.character.teleportTo(coords.x,coords.y, this.hero.character.z)
        }
   

translateStageCoordsToElements()method 
public function translateStageCoordsToElements(x:Number, y:Number):Array

This method returns the element under a Stage coordinate, and a 3D translation of the 2D coordinates passed as input. To achieve this it finds which visible elements are under the input pixel, ignoring the engine's internal coordinates. Now you can find out what did you click and which point of that element did you click.

Parameters
x:Number — Stage horizontal coordinate
 
y:Number — Stage vertical coordinate

Returns
Array — An array of objects storing both the element under that point and a 3d coordinate corresponding to the 2d Point. This method returns null if the coordinate is not occupied by any element. Why an Array an not a single element ? Because you may want to search the Array for the element that better suits your intentions: for example if you use it to walk around the scene, you will want to ignore trees to reach the floor behind. If you are shooting people, you will want to ignore floors and look for objects and characters to target at.

See also

Constant detail
LOADCOMPLETEconstant
public static const LOADCOMPLETE:String = "sceneloadcomplete"

The fScene.LOADCOMPLETE constant defines the value of the type property of the event object for a sceneloadcomplete event. The event is dispatched when the scene finishes loading and processing and is ready to be used

LOADINGDESCRIPTIONconstant 
public static const LOADINGDESCRIPTION:String = "Creating scene"

An string describing the process of loading and processing and scene XML definition file. Events dispatched by the scene while loading containg this String as a description of what is happening

LOADPROGRESSconstant 
public static const LOADPROGRESS:String = "scenecloadprogress"

The fScene.LOADPROGRESS constant defines the value of the type property of the event object for a scenecloadprogress event. The event is dispatched when the status of the scene changes during scene loading and processing. A listener to this event can then check the scene's status property to update a progress dialog