Torque3D Documentation / _generateds / consoledoc.h

consoledoc.h

consoledoc.h

More...

Classes:

class
AccumulationVolume

An invisible shape that allow objects within it to have an accumulation map.

class
ActionMap

ActionMaps assign platform input events to console commands.

class
AdvancedLightBinManager

Rendering Manager responsible for lighting, shadows, and global variables affecing both.

class
afxAnimClipData

A datablock that specifies an Animation Clip effect.

class
afxAnimLockData

A datablock that specifies an Animation Lock effect.

class
afxAreaDamageData

A datablock that specifies an Area Damage effect.

class
afxAudioBank

A datablock that specifies an Audio Bank effect.

class
afxBillboard

A Billboard effect as defined by an afxBillboardData datablock.

class
afxBillboardData

A datablock that specifies a Billboard effect.

class
afxCamera

A 3rd person camera object.

class
afxCameraData

A datablock that describes an afxCamera.

class
afxCameraPuppetData

A datablock that specifies a Camera Puppet effect.

class
afxCameraShakeData

A datablock that specifies a Camera Shake effect.

class
afxChoreographer

Base class used by choreographers.

class
afxChoreographerData

Datablock base class used by choreographers.

class
afxCollisionEventData

A datablock that specifies a Collision Event effect.

class
afxConsoleMessageData

A datablock that specifies a Console Message effect.

class
afxDamageData

A datablock that specifies a Damage effect.

class
afxEffectBaseData

A datablock baseclass for afxEffectWrapperData and afxEffectGroupData.

class
afxEffectGroupData

A datablock that describes an Effect Group.

class
afxEffectron

A basic effects choreographer.

class
afxEffectronData

Defines the properties of an afxEffectron.

class
afxEffectWrapper

An Effect Wrapper as defined by an afxEffectWrapperData datablock.

class
afxEffectWrapperData

A datablock that describes an Effect Wrapper.

class
afxEventCatchAll

A simple but useful GUI control that propagates all events to its parent control.

class
afxF_DragData

A datablock for specifiying AFX drag forces.

class
afxF_GravityData

A datablock for specifiying AFX gravity forces.

class
afxFootSwitchData

A datablock that specifies a Foot Switch effect.

class
afxGuiControllerData

A datablock that specifies a Gui Controller effect.

class
afxGuiSubstitutionField

A customized variation of GuiInspectorField.

class
afxGuiTextData

A datablock that specifies a Gui Text effect.

class
afxGuiTextHud

Similar to GuiShapeNameHud, afxGuiTextHud displays ShapeBase object names but also allows Gui Text effects.

class
afxLightData

afxLightData is a legacy datablock which is not supported for T3D.

class
afxMachineGunData

A datablock that specifies a Machine Gun effect.

class
afxMagicMissile

Magic-missile class used internally by afxMagicSpell. Properties of individual missile types are defined using afxMagicMissileData.

class
afxMagicMissileData

Defines a particular magic-missile type. (Use with afxMagicSpellData.)

class
afxMagicSpell

A magic spell effects choreographer.

class
afxMagicSpellData

Defines the properties of an afxMagicSpell.

class
afxModel

A Model effect as defined by an afxModelData datablock.

class
afxModelData

A datablock that specifies a Model effect.

class
afxMooring

A Mooring effect as defined by an afxMooringData datablock.

class
afxMooringData

A datablock that specifies a Mooring effect.

class
afxMultiLightData

afxMultiLightData is a legacy datablock which is not supported for T3D.

class
afxParticleEmitterConeData

An AFX customized particle emitter that emits particles within a cone shape.

class
afxParticleEmitterData

A base datablock inherited by AFX Particle Emitter effects.

class
afxParticleEmitterDiscData

An AFX customized particle emitter that emits particles within a disc shape.

class
afxParticleEmitterPathData

An AFX customized particle emitter that emits particles along a path.

class
afxParticleEmitterVectorData

An AFX customized particle emitter that emits particles along a 3D vector.

class
afxParticlePool

A ParticlePool object as defined by an afxParticlePoolData datablock.

class
afxParticlePoolData

A ParticlePool datablock.

class
afxPathData

A datablock for specifiying a 3D path for use with AFX.

class
afxPhraseEffectData

A datablock that specifies a Phrase Effect, a grouping of other effects.

class
afxPhysicalZoneData

A datablock that specifies a PhysicalZone effect.

class
afxPlayerMovementData

A datablock that specifies a Player Movement effect.

class
afxPlayerPuppetData

A datablock that specifies a Player Puppet effect.

class
afxProjectile

A Projectile effect as defined by an afxProjectileData datablock.

class
afxProjectileData

A datablock that specifies a Projectile effect.

class
afxRenderHighlightMgr
class
afxResidueMgr

A class that manages certain AFX effects that can persist for long durations.

class
afxRPGMagicSpellData

A datablock for defining RPG aspects of a spell.

class
afxScriptEventData

A datablock that specifies a Script Event effect.

class
afxSelectron

A choreographer for selection effects.

class
afxSelectronData

Defines the properties of an afxSelectronData.

class
afxSpellBook

A spellbook object.

class
afxSpellBookData

A spellbook datablock.

class
afxSpellButton

A GUI button with some special features that are useful for casting AFX spells.

class
afxSpellCastBar

A GUI progress bar useful as a spell casting bar.

class
afxStaticShape

A StaticShape effect as defined by an afxStaticShapeData datablock.

class
afxStaticShapeData

A datablock that specifies a StaticShape effect.

class
afxStatusBar

A GUI status bar for tracking and displaying health and energy of ShapeBase objects.

class
afxStatusBox

A simple GUI control used to contain player status bars and a label.

class
afxStatusLabel

A simple GUI control used for a player status label.

class
afxT3DLightBaseData

A datablock baseclass for afxT3DPointLightData and afxT3DSpotLightData.

class
afxT3DPointLightData

A datablock that specifies a dynamic Point Light effect.

class
afxT3DSpotLightData

A datablock that specifies a dynamic Spot Light effect.

class
afxTSCtrl

A customized variation of GameTSCtrl.

class
afxVolumeLightData

afxVolumeLightData is a legacy datablock which is not supported for T3D.

class
afxXM_AimData

An xmod datablock.

class
afxXM_AltitudeConformData

An xmod datablock.

class
afxXM_BaseData
class
afxXM_BoxAdaptData

An xmod datablock.

class
afxXM_BoxConformData

An xmod datablock.

class
afxXM_BoxHeightOffsetData

An xmod datablock.

class
afxXM_ForceData

An xmod datablock.

class
afxXM_FreezeData

An xmod datablock.

class
afxXM_GroundConformData

An xmod datablock.

class
afxXM_HeightSamplerData

An xmod datablock.

class
afxXM_LocalOffsetData

An xmod datablock.

class
afxXM_MountedImageNodeData

An xmod datablock.

class
afxXM_OscillateData

An xmod datablock.

class
afxXM_OscillateZodiacColorData

An xmod datablock.

class
afxXM_PathConformData

An xmod datablock.

class
afxXM_PivotNodeOffsetData

An xmod datablock.

class
afxXM_RandomRotData

An xmod datablock.

class
afxXM_ScaleData

An xmod datablock.

class
afxXM_ShockwaveData

An xmod datablock.

class
afxXM_SpinData

An xmod datablock.

class
afxXM_VelocityOffsetData

An xmod datablock.

class
afxXM_WaveBaseData

An xmod datablock.

class
afxXM_WaveColorData

An xmod datablock.

class
afxXM_WaveRiderBaseData

An xmod datablock.

class
afxXM_WaveRiderColorData

An xmod datablock.

class
afxXM_WaveRiderScalarData

An xmod datablock.

class
afxXM_WaveScalarData

An xmod datablock.

class
afxXM_WeightedBaseData
class
afxXM_WorldOffsetData

An xmod datablock.

class
afxZodiacData

A datablock that specifies a decal-like Zodiac effect.

class
afxZodiacGroundPlaneRenderer

A render bin for zodiac rendering on GroundPlane objects.

class
afxZodiacMeshRoadRenderer

A render bin for zodiac rendering on MeshRoad objects.

class
afxZodiacPlane

A ZodiacPlane effect as defined by an afxZodiacPlaneData datablock.

class
afxZodiacPlaneData

A datablock that specifies a Zodiac Plane effect.

class
afxZodiacPolysoupRenderer

A render bin for zodiac rendering on polysoup TSStatic objects.

class
afxZodiacTerrainRenderer

A render bin for zodiac rendering on Terrain objects.

class
AIClient

Simulated client driven by AI commands.

class
AIConnection

Special client connection driven by an AI, rather than a human.

class
AIPlayer

A Player object not controlled by conventional input, but by an AI engine.

class
AITurretShape
class
AITurretShapeData

Defines properties for an AITurretShape object.

class
ArrayObject

Data structure for storing indexed sequences of key/value pairs.

class
AssetBase
class
AssetImportConfig

Defines properties for an AssetImprotConfig object. @AssetImportConfig is a SimObject derived object intended to act as a container for all the necessary configuration data when running the Asset Importer. @It dictates if and how any given asset type will be processed when running an import action. This is because the Asset Importer utilizes a lot of informed logic @to try and automate as much of the import process as possible. In theory, you would run the import on a given file, and based on your config the importer will do @everything from importing the designated file, as well as finding and importing any associated files such as images or materials, and prepping the objects at time @of import to avoid as much manual post-processing as possible.

class
AssetImporter

Defines properties for an AssetImportObject object. @AssetImportObject is a SimObject derived object intended to act as a stand-in for the to-be imported objects. @It contains important info such as dependencies, if it's been processed, any error/status issues and the originating file @or if it's been programmatically generated as part of the import process.

class
AssetImportObject

Defines properties for an AssetImportObject object. @AssetImportObject is a SimObject derived object intended to act as a stand-in for the to-be imported objects. @It contains important info such as dependencies, if it's been processed, any error/status issues and the originating file @or if it's been programmatically generated as part of the import process.

class
AssetManager
class
AssetQuery
class
AssetTagsManifest
class
AudioDescription

Allows legacy AudioDescription datablocks to be treated as SFXDescription datablocks.

class
AudioProfile

Allows legacy AudioProfile datablocks to be treated as SFXProfile datablocks.

class
AutoloadAssets
class
BanList

Used for kicking and banning players from a server. There is only a single instance of BanList. It is very important to note that you do not ever create this object in script like you would other game play objects. You simply reference it via namespace.

class
BasicClouds

Renders up to three layers of scrolling cloud-cover textures overhead.

class
BoxEnvironmentProbe

An example scene object which renders a mesh.

class
Camera

Represents a position, direction and field of view to render a scene from.

class
CameraData

A datablock that describes a camera.

class
CloudLayer

A layer of clouds which change shape over time and are affected by scene lighting.

class
ConsoleLogger
class
ConvexShape

A renderable, collidable convex shape defined by a collection of surface planes.

class
CoverPoint

A type of marker that designates a location AI characters can take cover.

class
CppAsset
class
CubemapAsset
class
CubemapData

Used to create static or dynamic cubemaps.

class
CustomMaterial

Material object which provides more control over surface properties.

class
CustomShaderFeatureData

A Shader Feature with custom definitions.

class
Debris

Base debris class. Uses the DebrisData datablock for properties of individual debris objects.

class
DebrisData

Stores properties for an individual debris type.

class
DebugDrawer

A debug helper for rendering debug primitives to the scene.

class
DecalData

A datablock describing an individual decal.

class
DecalManager

The object that manages all of the decals in the active mission.

class
DecalRoad

A strip shaped decal defined by spine nodes which clips against Terrain objects.

class
DeclaredAssets
class
EditorIconRegistry

This class is used to find the correct icon file path for different SimObject class types.

class
EditorTool
class
EventManager

The EventManager class is a wrapper for the standard messaging system.

class
ExampleAsset
class
Explosion

The emitter for an explosion effect, with properties defined by a ExplosionData object.

class
ExplosionData

Defines the attributes of an Explosion: particleEmitters, debris, lighting and camera shake effects.

class
FileDialog

Base class responsible for displaying an OS file browser.

class
FileObject

This class is responsible opening, reading, creating, and saving file contents.

class
FileStreamObject

A wrapper around StreamObject for parsing text and data from files.

class
FlyingVehicle

A flying vehicle.

class
FlyingVehicleData

Defines the properties of a FlyingVehicle.

class
Forest

Forest is a global-bounds scene object provides collision and rendering for a (.forest) data file.

class
ForestBrushElement

Represents a type of ForestItem and parameters for how it is placed when painting with a ForestBrush that contains it.

class
ForestItemData

Base class for defining a type of ForestItem. It does not implement loading or rendering of the shapeFile.

class
ForestWindEmitter

Object responsible for simulating wind in a level.

class
fxFoliageReplicator

An emitter to replicate fxFoliageItem objects across an area.

class
fxShapeReplicatedStatic

The object definition for shapes that will be replicated across an area using an fxShapeReplicator.

class
fxShapeReplicator

An emitter for objects to replicate across an area.

class
GameBase

Base class for game objects which use datablocks, networking, are editable, and need to process ticks.

class
GameBaseData

Scriptable, demo-able datablock. Used by GameBase objects.

class
GameConnection

The game-specific subclass of NetConnection.

class
GameObjectAsset
class
GameTSCtrl

The main 3D viewport for a Torque 3D game.

class
GFXCardProfilerAPI

This class is the interface between TorqueScript and GFXCardProfiler.

class
GFXInit

Functions for tracking GFX adapters and initializing them into devices.

class
GFXSamplerStateData

A sampler state used by GFXStateBlockData.

class
GFXStateBlockData

A state block description for rendering.

class
GroundCover

Covers the ground in a field of objects (IE: Grass, Flowers, etc).

class
GroundPlane

An infinite plane extending in all direction.

class
Gui3DProjectionCtrl
class
guiAnimBitmapCtrl
class
GUIAsset
class
GuiAutoScrollCtrl

A container that scrolls its child control up over time.

class
GuiBitmapBarCtrl
class
GuiBitmapBorderCtrl

A control that renders a skinned border specified in its profile.

class
GuiBitmapButtonCtrl

A button that renders its various states (mouse over, pushed, etc.) from separate bitmaps.

class
GuiBitmapButtonTextCtrl

An extension of GuiBitmapButtonCtrl that additionally renders a text label on the bitmapped button.

class
GuiBitmapCtrl

A gui control that is used to display an image.

class
GuiBorderButtonCtrl

A push button that renders only a border.

class
GuiBubbleTextCtrl

A single-line text control that displays its text in a multi-line popup when clicked.

class
GuiButtonBaseCtrl

The base class for the various button controls.

class
GuiButtonCtrl

The most widely used button class.

class
GuiCanvas

A canvas on which rendering occurs.

class
GuiCheckBoxCtrl

A named checkbox that can be toggled on and off.

class
GuiChunkedBitmapCtrl

This is a control that will render a specified bitmap or a bitmap specified in a referenced variable.

class
GuiClockHud

Basic HUD clock. Displays the current simulation time offset from some base.

class
GuiConsole

The on-screen, in-game console. Calls getLog() to get the on-screen console entries, then renders them as needed.

class
GuiConsoleEditCtrl

Text entry element of a GuiConsole.

class
GuiContainer

Brief Desc.

class
GuiControl

Base class for all Gui control objects.

class
GuiControlArrayControl

Brief Desc.

class
GuiControlProfile

A collection of properties that determine control behavior and rendering.

class
GuiCrossHairHud

Basic cross hair hud. Reacts to state of control object. Also displays health bar for named objects under the cross hair.

class
GuiCursor

Acts as a skin for the cursor, where each GuiCursor object can have its own look and click-zone.

class
GuiDirectoryFileListCtrl

A control that displays a list of files from within a single directory in the game file system.

class
GuiDragAndDropControl

A container control that can be used to implement drag&drop behavior.

class
GuiDynamicCtrlArrayControl

A container that arranges children into a grid.

class
GuiFadeinBitmapCtrl

A GUI control which renders a black square over a bitmap image. The black square will fade out, then fade back in after a determined time. This control is especially useful for transitions and splash screens.

class
GuiFrameSetCtrl

A gui control allowing a window to be subdivided into panes, each of which displays a gui control child of the GuiFrameSetCtrl.

class
GuiGameListMenuCtrl

A base class for cross platform menu controls that are gamepad friendly.

class
GuiGameListMenuProfile

A GuiControlProfile with additional fields specific to GuiGameListMenuCtrl.

class
GuiGameListOptionsCtrl

A control for showing pages of options that are gamepad friendly.

class
GuiGameListOptionsProfile

A GuiControlProfile with additional fields specific to GuiGameListOptionsCtrl.

class
GuiGraphCtrl

A control that plots one or more curves in a chart.

class
GuiHealthBarHud

A basic health bar. Shows the damage value of the current PlayerObjectType control object.

class
GuiHealthTextHud

Shows the health or energy value of the current PlayerObjectType control object.

class
GuiIconButtonCtrl

Draws the bitmap within a special button control. Only a single bitmap is used and the button will be drawn in a highlighted mode when the mouse hovers over it or when it has been clicked.

class
GuiInputCtrl

A control that locks the mouse and reports all keyboard input events to script.

class
GuiListBoxCtrl

A list of text items.

class
GuiMenuBar

GUI Control which displays a horizontal bar with individual drop-down menu items. Each menu item may also have submenu items.

class
GuiMessageVectorCtrl

A chat HUD control that displays messages from a MessageVector.

class
GuiMLTextCtrl

A text control that uses the Gui Markup Language ('ML') tags to dynamically change the text.

class
GuiMLTextEditCtrl

A text entry control that accepts the Gui Markup Language ('ML') tags and multiple lines.

class
GuiMouseEventCtrl

Used to overlaps a 'hot region' where you want to catch inputs with and have specific events occur based on individual callbacks.

class
GuiObjectView

GUI control which displays a 3D model.

class
GuiOffscreenCanvas
class
GuiPaneControl

A collapsable pane control.

class
GuiPanel

The GuiPanel panel is a container that when opaque will draw a left to right gradient using its profile fill and fill highlight colors.

class
GuiPopUpMenuCtrl

A control that allows to select a value from a drop-down list.

class
GuiPopUpMenuCtrlEx

A control that allows to select a value from a drop-down list.

class
GuiProgressBitmapCtrl

A horizontal progress bar rendered from a repeating image.

class
GuiProgressCtrl

GUI Control which displays a horizontal bar which increases as the progress value of 0.0 - 1.0 increases.

class
GuiRadioCtrl

A button based around the radio concept.

class
GuiRenderTargetVizCtrl

The most widely used button class.

class
GuiRolloutCtrl

A container that shows a single child with an optional header bar that can be used to collapse and expand the rollout.

class
GuiScriptNotifyCtrl

A control which adds several reactions to other GUIs via callbacks.

class
GuiScrollCtrl

A container that allows to view one or more possibly larger controls inside its area by providing horizontal and/or vertical scroll bars.

class
GuiSeparatorCtrl

A control that renders a horizontal or vertical separator with an optional text label (horizontal only)

class
GuiShapeNameHud

Displays name and damage of ShapeBase objects in its bounds. Must be a child of a GuiTSCtrl and a server connection must be present.

class
GuiSliderCtrl

A control that displays a value between its minimal and maximal bounds using a slider placed on a vertical or horizontal axis.

class
GuiSpeedometerHud

Displays the speed of the current Vehicle based control object.

class
GuiSplitContainer

A container that splits its area between two child controls.

class
GuiStackControl

A container that stacks its children horizontally or vertically.

class
GuiSwatchButtonCtrl

A button that is used to represent color; often used in correlation with a color picker.

class
GuiTabBookCtrl

A container.

class
GuiTabPageCtrl

A single page in a GuiTabBookCtrl.

class
GuiTextCtrl

GUI control object this displays a single line of text, without TorqueML.

class
GuiTextEditCtrl

A component that places a text entry box on the screen.

class
GuiTextEditSliderBitmapCtrl

GUI Control which displays a numerical value which can be increased or decreased using a pair of bitmap up/down buttons.

class
GuiTextEditSliderCtrl

GUI Control which displays a numerical value which can be increased or decreased using a pair of arrows.

class
GuiTextListCtrl

GUI control that displays a list of text. Text items in the list can be individually selected.

class
GuiTheoraCtrl

A control to playing Theora videos.

class
GuiTickCtrl

Brief Description.

class
GuiToggleButtonCtrl

Deprecated gui control.

class
GuiTreeViewCtrl

Hierarchical list of text items with optional icons.

class
GuiTSCtrl

Abstract base class for controls that render 3D scenes.

class
GuiWindowCtrl

A window with a title bar and an optional set of buttons.

class
HoverVehicle

A hovering vehicle.

class
HoverVehicleData

Defines the properties of a HoverVehicle.

class
HTTPObject

Allows communications between the game and a server using HTTP.

class
ImageAsset
class
Item

Base Item class. Uses the ItemData datablock for common properties.

class
ItemData

Stores properties for an individual Item type.

class
LangTable

Provides the code necessary to handle the low level management of the string tables for localization.

class
LevelAsset
class
LevelInfo

Stores and controls the rendering and status information for a game level.

class
LightAnimData

A datablock which defines and performs light animation, such as rotation, brightness fade, and colorization.

class
LightBase

This is the base class for light objects.

class
LightDescription

A helper datablock used by classes (such as shapebase) that submit lights to the scene but do not use actual "LightBase" objects.

class
LightFlareData

Defines a light flare effect usable by scene lights.

class
Lightning

An emitter for lightning bolts.

class
LightningData

Common data for a Lightning emitter object.

class
LightningStrikeEvent

Network event that triggers a lightning strike on the client when it is received.

class
Marker

A single joint, or knot, along a path. Should be stored inside a Path container object. A path markers can be one of three primary movement types: "normal", "Position Only", or "Kink".

class
Material

A material in Torque 3D is a data structure that describes a surface.

class
MaterialAsset
class
MeshRoad

A strip of rectangular mesh segments defined by a 3D spline for prototyping road-shaped objects in your scene.

class
Message

Base class for messages.

class
MessageForwarder

Forward messages from one queue to another.

class
MessageVector

Store a list of chat messages.

class
MissionArea

Level object which defines the boundaries of the level.

class
MissionMarker

This is a base class for all "marker" related objets. It is a 3D representation of a point in the level.

class
MissionMarkerData

A very basic class containing information used by MissionMarker objects for rendering.

class
ModuleDefinition
class
ModuleManager
class
ModuleMergeDefinition
class
NavMesh
class
NavPath
class
NetConnection

Provides the basis for implementing a multiplayer game protocol.

class
NetObject

Superclass for all ghostable networked objects.

class
NotesObject
class
OcclusionVolume

An invisible shape that causes objects hidden from view behind it to not be rendered.

class
OpenFileDialog

Derived from FileDialog, this class is responsible for opening a file browser with the intention of opening a file.

class
OpenFolderDialog

OS level dialog used for browsing folder structures.

class
ParticleAsset
class
ParticleData

Contains information for how specific particles should look and react including particle colors, particle imagemap, acceleration value for individual particles and spin information.

class
ParticleEmitter

This object is responsible for spawning particles.

class
ParticleEmitterData

Defines particle emission properties such as ejection angle, period and velocity for a ParticleEmitter.

class
ParticleEmitterNode

A particle emitter object that can be positioned in the world and dynamically enabled or disabled.

class
ParticleEmitterNodeData

Contains additional data to be associated with a ParticleEmitterNode.

class
Path

A spline along which various objects can move along. The spline object acts like a container for Marker objects, which make up the joints, or knots, along the path. Paths can be assigned a speed, can be looping or non-looping. Each of a path's markers can be one of three primary movement types: "normal", "Position Only", or "Kink".

class
PathCamera

A camera that moves along a path. The camera can then be made to travel along this path forwards or backwards.

class
PathCameraData

General interface to control a PathCamera object from the script level.

class
PathShape
class
PathShapeData
class
PfxVis

Singleton class that exposes ConsoleStaticFunctions for debug visualizing PostEffects.

class
PhysicalZone

Physical Zones are areas that modify the player's gravity and/or velocity and/or applied force.

class
PhysicsDebris

Represents one or more rigid bodies defined in a single mesh file with a limited lifetime.

class
PhysicsDebrisData

Defines the properties of a PhysicsDebris object.

class
PhysicsForce

Helper object for gameplay physical forces.

class
PhysicsShape

Represents a destructible physical object simulated through the plugin system.

class
PhysicsShapeData

Defines the properties of a PhysicsShape.

class
Player
class
PlayerData

Defines properties for a Player object.

class
PointLight

Lighting object that radiates light in all directions.

class
Portal

An object that provides a "window" into a zone, allowing a viewer to see what's rendered in the zone.

class
PostEffect

A fullscreen shader effect.

class
PostEffectAsset
class
Precipitation

Defines a precipitation based storm (rain, snow, etc).

class
PrecipitationData

Defines the droplets used in a storm (raindrops, snowflakes, etc).

class
Prefab

A collection of arbitrary objects which can be allocated and manipulated as a group.

class
Projectile

Base projectile class. Uses the ProjectileData class for properties of individual projectiles.

class
ProjectileData

Stores properties for an individual projectile type.

class
ProximityMine

A simple proximity mine.

class
ProximityMineData

Stores common properties for a ProximityMine.

class
RadialImpulseEvent

Creates a physics-based impulse effect from a defined central point and magnitude.

class
ReferencedAssets
class
ReflectionProbe

An example scene object which renders a mesh.

class
ReflectorDesc

A datablock which defines performance and quality properties for dynamic reflections.

class
RenderBinManager

The abstract base for all render bins.

class
RenderDeferredMgr

The render bin which performs a z+normals deferred used in Advanced Lighting.

class
RenderFormatToken

Used to change the render target format when rendering in AL.

class
RenderGlowMgr

A render bin for the glow pass.

class
RenderImposterMgr

A render bin for batch rendering imposters.

class
RenderMeshExample

An example scene object which renders a mesh.

class
RenderMeshMgr

A render bin for mesh rendering.

class
RenderObjectExample

An example scene object which renders using a callback.

class
RenderObjectMgr

A render bin which uses object callbacks for rendering.

class
RenderOcclusionMgr

A render bin which renders occlusion query requests.

class
RenderParticleMgr

A render bin which renders particle geometry.

class
RenderPassManager

A grouping of render bin managers which forms a render pass.

class
RenderPassStateBin

A non-rendering render bin used to enable/disable a RenderPassStateToken.

class
RenderPassStateToken

Abstract base class for RenderFormatToken, used to manipulate what goes on in the render manager.

class
RenderProbeMgr

A render bin which uses object callbacks for rendering.

class
RenderShapeExample

An example scene object which renders a DTS.

class
RenderTerrainMgr

A render bin for terrain mesh rendering.

class
RenderTexTargetBinManager

An abstract base class for render bin managers that render to a named textue target.

class
RenderTranslucentMgr

A render bin for rendering translucent meshes.

class
Ribbon
class
RibbonData
class
RibbonNode
class
RibbonNodeData

Contains additional data to be associated with a RibbonNode.

class
RigidShape

The RigidShape class implements rigid-body physics for DTS objects in the world.

class
RigidShapeData

Defines the physics properties for an individual RigidShapeData physics object.

class
River

A water volume defined by a 3D spline.

class
SaveFileDialog

Derived from FileDialog, this class is responsible for opening a file browser with the intention of saving a file.

class
ScatterSky

Represents both the sun and sky for scenes with a dynamic time of day.

class
Scene
class
SceneObject

A networkable object that exists in the 3D world.

class
ScriptAsset
class
ScriptGroup

Essentially a SimGroup, but with onAdd and onRemove script callbacks.

class
ScriptMsgListener

Script accessible version of Dispatcher::IMessageListener. Often used in conjunction with EventManager.

class
ScriptObject

A script-level OOP object which allows binding of a class, superClass and arguments along with declaration of methods.

class
ScriptTickObject

A ScriptObject that responds to tick and frame events.

class
SDLInputManager
class
SFXAmbience

A datablock that describes an ambient sound space.

class
SFXController

A sound source that drives multi-source playback.

class
SFXDescription

A description for how a sound should be played.

class
SFXEmitter

An invisible 3D object that emits sound.

class
SFXEnvironment

Description of a reverb environment.

class
SFXParameter

A sound channel value that can be bound to multiple sound sources.

class
SFXPlayList

A datablock describing a playback pattern of sounds.

class
SFXProfile

Encapsulates a single sound file for playback by the sound system.

class
SFXSound

A sound controller that directly plays a single sound file.

class
SFXSource

Playback controller for a sound source.

class
SFXSpace

A volume in space that defines an ambient sound zone.

class
SFXState

A boolean switch used to modify playlist behavior.

class
SFXTrack

Abstract base class for sound data that can be played back by the sound system.

class
sgLightObjectData

Allows legacy sgLightObjectData datablocks to appear in scripts.

class
ShaderData

Special type of data block that stores information about a handwritten shader.

class
ShapeAnimationAsset
class
ShapeAsset
class
ShapeBase
class
ShapeBaseData

Defines properties for a ShapeBase object.

class
ShapeBaseImageData

Represents geometry to be mounted to a ShapeBase object.

class
SimDataBlock
class
SimGroup

A collection of SimObjects that are owned by the group.

class
SimObject

Base class for almost all objects involved in the simulation.

class
SimpleMessageEvent

A very simple example of a network event.

class
SimpleNetObject

A very simple example of a class derived from NetObject.

class
SimSet

A collection of SimObjects.

class
SimXMLDocument

File I/O object used for creating, reading, and writing XML documents.

class
SkyBox

Represents the sky with an artist-created cubemap.

class
Skylight

An example scene object which renders a mesh.

class
SoundAsset
class
SpawnSphere

This class is used for creating any type of game object, assigning it a class, datablock, and other properties when it is spawned.

class
SphereEnvironmentProbe

An example scene object which renders a mesh.

class
Splash

Manages the ring used for a Splash effect.

class
SplashData

Acts as the physical point in space in white a Splash is created from.

class
SpotLight

Lighting object which emits conical light in a direction.

class
StateMachineAsset
class
StaticShape

The most basic 3D shape with a datablock available in Torque 3D.

class
StaticShapeData

The most basic ShapeBaseData derrived shape datablock available in Torque 3D.

class
StreamObject

Base class for working with streams.

class
Sun

A global light affecting your entire scene and optionally renders a corona effect.

class
Taml
class
TCPObject

Allows communications between the game and a server using TCP/IP protocols.

class
TerrainAsset
class
TerrainBlock

Represent a terrain object in a Torque 3D level.

class
TerrainMaterial

The TerrainMaterial class orginizes the material settings for a single terrain material layer.

class
TerrainMaterialAsset
class
TheoraTextureObject

Definition of a named texture target playing a Theora video.

class
TimeOfDay

Environmental object that triggers a day/night cycle in level.

class
Trigger

A Trigger is a volume of space that initiates script callbacks when objects pass through the Trigger.

class
TriggerData

Defines shared properties for Trigger objects.

class
TSForestItemData

Concrete implementation of ForestItemData which loads and renders dts format shapeFiles.

class
TSShapeConstructor

An object used to modify a DTS or COLLADA shape model after it has been loaded by Torque.

class
TSStatic

A static object derived from a 3D model file and placed within the game world.

class
TurretShape
class
TurretShapeData

Defines properties for a TurretShape object.

class
VActor
class
VActorData
class
VCameraGroup
class
VCameraShakeEvent
class
VCameraShakeNetEvent
class
VCameraShakeTrack
class
VCameraTrack
class
VController
class
VDirectorEvent
class
VDirectorGroup
class
VDirectorTrack
class
VEditorButton
class
VEditorScrollControl
class
VEditorWindow
class
Vehicle

Base functionality shared by all Vehicles (FlyingVehicle, HoverVehicle, WheeledVehicle).

class
VehicleData

Base properties shared by all Vehicles (FlyingVehicle, HoverVehicle, WheeledVehicle).

class
VEvent
class
VFadeControl
class
VFadeEvent
class
VFadeTrack
class
VGroup
class
VHumanoidActor
class
VHumanoidActorData
class
VLightObjectAnimationEvent
class
VLightObjectAnimationTrack
class
VLightObjectGroup
class
VLightObjectToggleEvent
class
VLightObjectToggleTrack
class
VMotionEvent
class
VMotionTrack
class
VObject
class
VolumetricFog

Volumetric Fog Object class. Main class defining the Volumetric Fog objects in the scene. Used in conjunction with the VolumetricFogRTManager class which is responsible for the required rendertargets.

class
VolumetricFogRTManager

Creates and maintains one set of rendertargets to be used by every VolumetricFog object in the scene.

class
VParticleEffectGroup
class
VParticleEffectToggleEvent
class
VParticleEffectToggleTrack
class
VPath
class
VPathEditor
class
VPostEffectNetEvent
class
VPostEffectToggleEvent
class
VPostEffectToggleTrack
class
VSceneJumpEvent
class
VSceneJumpTrack
class
VSceneObjectEvent
class
VSceneObjectGroup
class
VSceneObjectTrack
class
VScriptEvent
class
VScriptEventTrack
class
VShapeAnimationEvent
class
VShapeAnimationTrack
class
VSlowMoEvent
class
VSlowMoTrack
class
VSoundEffectEvent
class
VSoundEffectNetEvent
class
VSoundEffectTrack
class
VSpawnSphereGroup
class
VSpawnSphereSpawnTargetEvent
class
VSpawnSphereSpawnTargetTrack
class
VTimeLineControl
class
VTrack
class
WaterBlock

A block shaped water volume defined by a 3D scale and orientation.

class
WaterObject

Abstract base class for representing a body of water.

class
WaterPlane

Represents a large body of water stretching to the horizon in all directions.

class
WayPoint

Special type of marker, distinguished by a name and team ID number.

class
WheeledVehicle

A wheeled vehicle.

class
WheeledVehicleData

Defines the properties of a WheeledVehicle.

class
WheeledVehicleSpring

Defines the properties of a WheeledVehicle spring.

class
WheeledVehicleTire

Defines the properties of a WheeledVehicle tire.

class
ZipObject

Provides access to a zip file.

class
Zone

An object that represents an interior space.

Namespaces:

namespace
$AL
namespace
$BasicLightManager
namespace
$BasicLightManagerStats
namespace
$Con
namespace
$Core
namespace
$Decals
namespace
$Ease
namespace
$gfx
namespace
$Light
namespace
$Physics
namespace
$platform
namespace
$pref
namespace
$Pref
namespace
$pref::AFX
namespace
$pref::afxCamera
namespace
$pref::afxSpellButton
namespace
$pref::afxZodiac
namespace
$pref::Audio
namespace
$pref::Camera
namespace
$pref::Client
namespace
$pref::Decals
namespace
$pref::GroundCover
namespace
$pref::imposter
namespace
$pref::Input
namespace
$pref::Net
namespace
$pref::Physics
namespace
$pref::PhysicsDebris
namespace
$pref::Player
namespace
$pref::ProjectedShadow
namespace
$pref::PSSM
namespace
$pref::Reflect
namespace
$Pref::Server
namespace
$Pref::Server::AFX
namespace
$pref::Shadows
namespace
$pref::shadows
namespace
$pref::Terrain
namespace
$pref::TS
namespace
$pref::TSShapeConstructor
namespace
$pref::Video
namespace
$pref::VolumetricFog
namespace
$pref::Water
namespace
$pref::WorldEditor
namespace
$ProxMine
namespace
$rigidPhysics
namespace
$Sampler
namespace
$SB
namespace
$SFX
namespace
$Shadows
namespace
$Stats
namespace
$TSControl

Public Enumerations

enum
_TamlFormatMode {
  xml 
  binary 
}
enum
afxBillboard_BlendStyle {
  NORMAL 
  ADDITIVE 
  SUBTRACTIVE 
  PREMULTALPHA 
}

Possible blending types.

enum
afxParticleEmitterPath_OriginType {
  origin 
  point 
  vector 
  tangent 
}

Possible particle emitter path origin types.

enum
afxParticlePool_PoolType {
  normal 
  pass 
  twopass 
}

Possible particle pool types.

enum
afxPath3DLoopType {
  constant 
  cycle 
  oscillate 
}

Possible loop types for an afxPath.

enum
afxPhraseEffect_MatchType {
  any 
  all 
}

Possible phrase effect match types.

enum
afxPhraseEffect_PhraseType {
  triggered 
  continuous 
}

Possible phrase effect types.

enum
afxPhraseEffect_StateType {
  on 
  off 
  both 
}

Possible phrase effect state types.

enum
afxPlayerMovement_OpType {
  add 
  multiply 
  replace 
  mult 
}

Possible player movement operation types.

enum
afxProjectile_LaunchDirType {
  towardPos2Constraint 
  orientConstraint 
  launchDirField 
}

Possible projectile launch direction types.

enum
afxRPGMagicSpell_TargetType {
  nothing 
  self 
  friend 
  enemy 
  corpse 
  free 
}

Possible RPG spell target types.

enum
afxXM_BoxConformType {
  x 
  x 
  y 
  y 
  z 
  z 
  x 
  y 
  z 
}

Possible box conform alignment types.

enum
afxXM_WaveFormType {
  none 
  sine 
  square 
  triangle 
  sawtooth 
  noise 
  one 
}

Possible waveform types.

enum
afxXM_WaveOpType {
  add 
  multiply 
  replace 
  mult 
}

Possible wave operation types.

enum
afxXM_WaveParamType {
  none 
  pos 
  x 
  y 
  z 
  ori 
  pos2 
  x 
  y 
  z 
  scale 
  x 
  y 
  z 
  color 
  red 
  green 
  blue 
  alpha 
  vis 
  position 
  x 
  y 
  z 
  orientation 
  position2 
  x 
  y 
  z 
  r 
  g 
  b 
  a 
  visibility 
}

Possible wave parameter types.

enum
afxZodiac_BlendType {
  normal 
  additive 
  subtractive 
}

Possible zodiac blend types.

enum
afxZodiacPlane_BlendType {
  normal 
  additive 
  subtractive 
}

Possible zodiac blend types.

enum
afxZodiacPlane_FacingType {
  up 
  down 
  forward 
  backward 
  right 
  left 
  front 
  back 
}

Possible zodiac plane facing types.

enum
baseTexFormat {
  NONE 
  DDS 
  PNG 
}

Description.

enum
CameraMotionMode {
  Stationary 
  FreeRotate 
  Fly 
  OrbitObject 
  OrbitPoint 
  TrackObject 
  Overhead 
  EditOrbit 
}

Movement behavior type for Camera.

enum
CoverPointSize {
  Prone 
  Crouch 
  Stand 
}

The size of a cover point.

enum
GFXAdapterType {
  OpenGL 
  D3D11 
  NullDevice 
}

Back-end graphics API used by the GFX subsystem.

enum
GFXBlend {
  GFXBlendZero 
  GFXBlendOne 
  GFXBlendSrcColor 
  GFXBlendInvSrcColor 
  GFXBlendSrcAlpha 
  GFXBlendInvSrcAlpha 
  GFXBlendDestAlpha 
  GFXBlendInvDestAlpha 
  GFXBlendDestColor 
  GFXBlendInvDestColor 
  GFXBlendSrcAlphaSat 
}

The supported blend modes.

enum
GFXBlendOp {
  GFXBlendOpAdd 
  GFXBlendOpSubtract 
  GFXBlendOpRevSubtract 
  GFXBlendOpMin 
  GFXBlendOpMax 
}

The blend operators.

enum
GFXCmpFunc {
  GFXCmpNever 
  GFXCmpLess 
  GFXCmpEqual 
  GFXCmpLessEqual 
  GFXCmpGreater 
  GFXCmpNotEqual 
  GFXCmpGreaterEqual 
  GFXCmpAlways 
}

The supported comparison functions.

enum
GFXCullMode {
  GFXCullNone 
  GFXCullCW 
  GFXCullCCW 
}

The render cull modes.

enum
GFXFormat {
  GFXFormatR8G8B8 
  GFXFormatR8G8B8A8 
  GFXFormatR8G8B8A8_SRGB 
  GFXFormatR8G8B8X8 
  GFXFormatR32F 
  GFXFormatR5G6B5 
  GFXFormatR5G5B5A1 
  GFXFormatR5G5B5X1 
  GFXFormatA4L4 
  GFXFormatA8L8 
  GFXFormatA8 
  GFXFormatL8 
  GFXFormatBC1 
  GFXFormatBC2 
  GFXFormatBC3 
  GFXFormatBC4 
  GFXFormatBC5 
  GFXFormatD32 
  GFXFormatD24X8 
  GFXFormatD24S8 
  GFXFormatD24FS8 
  GFXFormatD16 
  GFXFormatR32G32B32A32F 
  GFXFormatR16G16B16A16F 
  GFXFormatL16 
  GFXFormatR16G16B16A16 
  GFXFormatR16G16 
  GFXFormatR16F 
  GFXFormatR16G16F 
  GFXFormatR10G10B10A2 
}

The texture formats.

enum
GFXStencilOp {
  GFXStencilOpKeep 
  GFXStencilOpZero 
  GFXStencilOpReplace 
  GFXStencilOpIncrSat 
  GFXStencilOpDecrSat 
  GFXStencilOpInvert 
  GFXStencilOpIncr 
  GFXStencilOpDecr 
}

The stencil operators.

enum
GFXTextureAddressMode {
  GFXAddressWrap 
  GFXAddressMirror 
  GFXAddressClamp 
  GFXAddressBorder 
  GFXAddressMirrorOnce 
}

The texture address modes.

enum
GFXTextureFilterType {
  GFXTextureFilterNone 
  GFXTextureFilterPoint 
  GFXTextureFilterLinear 
  GFXTextureFilterAnisotropic 
}

The texture filter types.

enum
GuiAlignmentType {
  Left 
  Center 
  Right 
  Top 
  Bottom 
}
enum
GuiAutoScrollDirection {
  Up 
  Down 
  Left 
  Right 
}

Direction in which to scroll the child control.

enum
GuiBitmapMode {
  Stretched 
  Centered 
}

Rendering behavior when placing bitmaps in controls.

enum
GuiButtonType {
  PushButton 
  ToggleButton 
  RadioButton 
}

Type of button control.

enum
GuiDockingType {
  None 
  Client 
  Top 
  Bottom 
  Left 
  Right 
}
enum
GuiFontCharset {
  ANSI 
  SYMBOL 
  SHIFTJIS 
  HANGEUL 
  HANGUL 
  GB2312 
  CHINESEBIG5 
  OEM 
  JOHAB 
  HEBREW 
  ARABIC 
  GREEK 
  TURKISH 
  VIETNAMESE 
  THAI 
  EASTEUROPE 
  RUSSIAN 
  MAC 
  BALTIC 
}
enum
GuiFrameState {
  alwaysOn 
  alwaysOff 
  dynamic 
}
enum
GuiGraphType {
  Bar 
  Filled 
  Point 
  PolyLine 
}

The charting style of a single plotting curve in a GuiGraphCtrl.

enum
GuiHorizontalSizing {
  right 
  width 
  left 
  center 
  relative 
  aspectLeft 
  aspectRight 
  aspectCenter 
  windowRelative 
}

Horizontal sizing behavior of a GuiControl.

enum
GuiHorizontalStackingType {
  Right 
  Left 
}

Determines how child controls are stacked horizontally.

enum
GuiIconButtonIconLocation {
  None 
  Left 
  Right 
  Center 
}
enum
GuiIconButtonTextLocation {
  None 
  Bottom 
  Right 
  Top 
  Left 
  Center 
}
enum
GuiScrollBarBehavior {
  alwaysOn 
  alwaysOff 
  dynamic 
}

Display behavior of a scroll bar. Determines when a scrollbar will be visible.

enum
GuiSeparatorType {
  Vertical 
  Horizontal 
}

GuiSeparatorCtrl orientations.

enum
GuiSplitFixedPanel {
  None 
  FirstPanel 
  SecondPanel 
}

Which side of the splitter to keep at a fixed size (if any).

enum
GuiSplitOrientation {
  Vertical 
  Horizontal 
}

Axis along which to divide the container's space.

enum
GuiStackingType {
  Vertical 
  Horizontal 
  Dynamic 
}

Stacking method used to position child controls.

enum
GuiTabPosition {
  Top 
  Bottom 
}

Where the control should put the tab headers for selecting individual pages.

enum
GuiTheoraTranscoder {
  Auto 
  Generic 
  SSE2420RGBA 
}

Routine to use for converting Theora's Y'CbCr pixel format to RGB color space.

enum
GuiTSRenderStyles {
  standard 
  side 
  separate 
}

Style of rendering for a GuiTSCtrl.

enum
GuiVerticalSizing {
  bottom 
  height 
  top 
  center 
  relative 
  aspectTop 
  aspectBottom 
  aspectCenter 
  windowRelative 
}

Vertical sizing behavior of a GuiControl.

enum
GuiVerticalStackingType {
  Bottom 
  Top 
}

Determines how child controls are stacked vertically.

enum
ImageAssetType {
  Albedo 
  Normal 
  ORMConfig 
  GUI 
  Roughness 
  AO 
  Metalness 
  Glow 
  Particle 
  Decal 
  Cubemap 
}

Type of mesh data available in a shape.

enum
ItemLightType {
  NoLight 
  ConstantLight 
  PulsingLight 
}

The type of light the Item has.

enum
LogLevel {
  normal 
  warning 
  error 
}

Priority levels for logging entries.

enum
MarkerKnotType {
  Normal 
  Only 
  Kink 
}

The type of knot that this marker will be.

enum
MarkerSmoothingType {
  Spline 
  Linear 
}

The type of smoothing this marker will have for pathed objects.

enum
MaterialAnimType {
  Scroll 
  Rotate 
  Wave 
  Scale 
  Sequence 
}

The type of animation effect to apply to this material.

enum
MaterialBlendOp {
  None 
  Mul 
  PreMul 
  Add 
  AddAlpha 
  Sub 
  LerpAlpha 
}

The type of graphical blending operation to apply to this material.

enum
MaterialWaveType {
  Sin 
  Triangle 
  Square 
}

When using the Wave material animation, one of these Wave Types will be used to determine the type of wave to display.

enum
MBButtons {
  Ok 
  OkCancel 
  RetryCancel 
  SaveDontSave 
  SaveDontSaveCancel 
}

Which buttons to display on a message box.

enum
MBIcons {
  Information 
  Warning 
  Stop 
  Question 
}

What icon to show on a message box.

enum
MBReturnVal {
  OK 
  Cancelled 
  Retry 
  DontSave 
}

Return value for messageBox() indicating which button was pressed by the user.

enum
NavMeshWaterMethod {
  Ignore 
  Solid 
  Impassable 
}

The method used to include water surfaces in the NavMesh.

enum
ParticleBlendStyle {
  NORMAL 
  ADDITIVE 
  SUBTRACTIVE 
  PREMULTALPHA 
}

The type of visual blending style to apply to the particles.

enum
PFXRenderTime {
  PFXBeforeBin 
  PFXAfterBin 
  PFXAfterDiffuse 
  PFXEndOfFrame 
  PFXTexGenOnDemand 
}

When to process this effect during the frame.

enum
PFXTargetClear {
  PFXTargetClear_None 
  PFXTargetClear_OnCreate 
  PFXTargetClear_OnDraw 
}

Describes when the target texture should be cleared.

enum
PFXTargetViewport {
  PFXTargetViewport_TargetSize 
  PFXTargetViewport_GFXViewport 
  PFXTargetViewport_NamedInTexture0 
}

Specifies how the viewport should be set up for a PostEffect's target.

enum
PhysicalZone_ForceType {
  vector 
  spherical 
  cylindrical 
  sphere 
  cylinder 
}

Possible physical zone force types.

enum
PhysicsSimType {
  ClientOnly 
  ServerOnly 
  ClientServer 
}

How to handle the physics simulation with the client's and server.

enum
PlayerPose {
  Stand 
  Sprint 
  Crouch 
  Prone 
  Swim 
}

The pose of the Player.

enum
ReflectionModeEnum {
  Reflections 
  Cubemap 
  Cubemap 
}

Type of mesh data available in a shape.

enum
ReflectProbeType {
  Sphere 
  Box 
}

Type of mesh data available in a shape.

enum
RenderTexTargetSize {
  windowsize 
  windowsizescaled 
  fixedsize 
}

What size to render the target texture. Sizes are based on the Window the render is occuring in.

enum
SDLJoystickType {
  Unknown 
  Controller 
  Wheel 
  Stick 
  Stick 
  Pad 
  Guitar 
  Kit 
  Pad 
  Throttle 
}

The type of device connected.

enum
SDLPowerEnum {
  Unknown 
  Empty 
  Low 
  Medium 
  Full 
  Wired 
  Max 
}

An enumeration of battery levels of a joystick.

enum
SFXChannel {
  Volume 
  Pitch 
  Priority 
  PositionX 
  PositionY 
  PositionZ 
  RotationX 
  RotationY 
  RotationZ 
  VelocityX 
  VelocityY 
  VelocityZ 
  ReferenceDistance 
  MaxDistance 
  ConeInsideAngle 
  ConeOutsideAngle 
  ConeOutsideVolume 
  Cursor 
  Status 
  User0 
  User1 
  User2 
  User3 
}

Channels are individual properties of sound sources that may be animated over time.

enum
SFXDistanceModel {
  Linear 
  Logarithmic 
  Exponential 
}

Type of volume distance attenuation curve.

enum
SFXPlayListLoopMode {
  All 
  Single 
}

Playlist behavior when description is set to loop.

enum
SFXPlayListRandomMode {
  NotRandom 
  StrictRandom 
  OrderedRandom 
}

Randomization pattern to apply to playlist slot playback order.

enum
SFXPlayListReplayMode {
  IgnorePlaying 
  RestartPlaying 
  KeepPlaying 
  StartNew 
  SkipIfPlaying 
}

Behavior when hitting the play stage of a slot that is still playing from a previous cycle.

enum
SFXPlayListStateMode {
  StopWhenDeactivated 
  PauseWhenDeactivated 
  IgnoreWhenDeactivated 
}

Reaction behavior when a state is changed incompatibly on a slot that has already started playing.

enum
SFXPlayListTransitionMode {
  None 
  Wait 
  WaitAll 
  Stop 
  StopAll 
}

Playlist behavior when transitioning in and out of invididual slots.

enum
SFXStatus {
  Playing 
  Stopped 
  Paused 
}

Playback status of sound source.

enum
ShadowFilterMode {
  None 
  SoftShadow 
  SoftShadowHighQuality 
}

The shadow filtering modes for Advanced Lighting shadows.

enum
ShadowType {
  Spot 
  PSSM 
  DualParaboloidSinglePass 
  DualParaboloid 
  CubeMap 
}
enum
ShapeBaseImageLightType {
  NoLight 
  ConstantLight 
  SpotLight 
  PulsingLight 
  WeaponFireLight 
}

The type of light to attach to this ShapeBaseImage.

enum
ShapeBaseImageLoadedState {
  Ignore 
  Loaded 
  Empty 
}

The loaded state of this ShapeBaseImage.

enum
ShapeBaseImageRecoilState {
  NoRecoil 
  LightRecoil 
  MediumRecoil 
  HeavyRecoil 
}

What kind of recoil this ShapeBaseImage should emit when fired.

enum
ShapeBaseImageSpinState {
  Ignore 
  Stop 
  SpinUp 
  SpinDown 
  FullSpeed 
}

How the spin animation should be played.

enum
TSMeshType {
  None 
  Bounds 
  Mesh 
  Mesh 
}

Type of mesh data available in a shape.

enum
TSShapeConstructorAnimType {
  Frames 
  Seconds 
  Milliseconds 
}
enum
TSShapeConstructorLodType {
  DetectDTS 
  SingleSize 
  TrailingNumber 
}
enum
TSShapeConstructorUpAxis {
  X_AXIS 
  Y_AXIS 
  Z_AXIS 
  DEFAULT 
}

Axis to use for upwards direction when importing from Collada.

enum
TurretShapeFireLinkType {
  FireTogether 
  GroupedFire 
  IndividualFire 
}

How the weapons are linked to triggers for this TurretShape.

enum
VActionToggle {
  ON 
  OFF 
}
enum
VDataTableDataType {
  EXPRESSION 
  STATIC 
  VARIABLE 
}
enum
VPathEditorMode {
  GIZMO 
  ADDNODE 
  DELETENODE 
}
enum
VPathNodeOrientationType {
  FREE 
  TOPOINT 
}
enum
VPathObjectOrientationType {
  FREE 
  INTERPOLATE 
  TOPATH 
  TOOBJECT 
  TOPOINT 
}
enum
VPathType {
  BEZIER 
  LINEAR 
}
enum
VScriptEventCommandType {
  EXPRESSION 
  METHOD 
}

Public Variables

bool

$_forceAllMainThread

Force all work items to execute on main thread. turns this into a single-threaded system. Primarily useful to find whether malfunctions are caused by parallel execution or not.

float

$cameraFov

The camera's Field of View.

int

$frameSkip

Sets the number of frames to skip while rendering the scene.

string

$instantGroup

The group that objects will be added to when they are created.

float

$mvBackwardAction

Backwards movement speed for the active player.

bool

$mvDeviceIsKeyboardMouse

Boolean state for it the system is using a keyboard and mouse or not.

float

$mvDownAction

Downwards movement speed for the active player.

float

$mvForwardAction

Forwards movement speed for the active player.

bool

$mvFreeLook

Boolean state for if freelook is active or not.

float

$mvLeftAction

Left movement speed for the active player.

float

$mvPitch

Current pitch value, typically applied through input devices, such as a mouse.

float

$mvPitchDownSpeed

Downwards pitch speed.

float

$mvPitchUpSpeed

Upwards pitch speed.

float

$mvRightAction

Right movement speed for the active player.

float

$mvRoll

Current roll value, typically applied through input devices, such as a mouse.

float

$mvRollLeftSpeed

Left roll speed.

float

$mvRollRightSpeed

Right roll speed.

int

$mvTriggerCount0

Used to determine the trigger counts of buttons. Namely used for input actions such as jumping and weapons firing.

int

$mvTriggerCount1

Used to determine the trigger counts of buttons. Namely used for input actions such as jumping and weapons firing.

int

$mvTriggerCount2

Used to determine the trigger counts of buttons. Namely used for input actions such as jumping and weapons firing.

int

$mvTriggerCount3

Used to determine the trigger counts of buttons. Namely used for input actions such as jumping and weapons firing.

int

$mvTriggerCount4

Used to determine the trigger counts of buttons. Namely used for input actions such as jumping and weapons firing.

int

$mvTriggerCount5

Used to determine the trigger counts of buttons. Namely used for input actions such as jumping and weapons firing.

float

$mvUpAction

Upwards movement speed for the active player.

float

$mvXAxis_L

Left thumbstick X axis position on a dual-analog gamepad.

float

$mvXAxis_R

Right thumbstick X axis position on a dual-analog gamepad.

float

$mvYaw

Current yaw value, typically applied through input devices, such as a mouse.

float

$mvYawLeftSpeed

Left Yaw speed.

float

$mvYawRightSpeed

Right Yaw speed.

float

$mvYAxis_L

Left thumbstick Y axis position on a dual-analog gamepad.

float

$mvYAxis_R

Right thumbstick Y axis position on a dual-analog gamepad.

GuiControl

$ThisControl

The control for which a command is currently being evaluated. Only set during 'command' and altCommand callbacks to the control for which the command or altCommand is invoked.

int

$timeAdvance

The speed at which system processing time advances.

float

$timeScale

Animation time scale.

void

addCaseSensitiveStrings

[string1, string2, ...]Adds case sensitive strings to the StringTable.

void

restartInstance

restartInstance()

int

schedule

schedule(time, refobject|0, command, )

Public Functions

void

activateDirectInput()

Activates DirectInput.

void

activatePackage(String packageName)

Activates an existing package.

bool

addBadWord(string badWord)

Add a string to the bad word filter.

void

addGlobalShaderMacro(string name, string value)

Adds a global shader macro which will be merged with the script defined macros on every shader. The macro will replace the value of an existing macro of the same name. For the new macro to take effect all the shaders in the system need to be reloaded.

void

addMaterialMapping(string texName, string matName)

Maps the given texture to the given material.

RotationF

AddRotation(RotationF a, RotationF b)

Adds two rotations together.

string

addTaggedString(string str)

Use the addTaggedString function to tag a new string and add it to the NetStringTable.

void

afxEndMissionNotify()

...

string

afxGetEngine()

...

string

afxGetVersion()

...

int

aiAddPlayer(string name, string ns)

'playerName'[, 'AIClassType'] );

int

aiConnect(... )

Creates a new AIConnection, and passes arguments to its onConnect script callback.

void

allowConnections(bool allow)

Sets whether or not the global NetInterface allows connections from remote hosts.

void

Assert(bool condition, string message)

Fatal Script Assertion.

void

backtrace()

Prints the scripting call stack to the console log.

void

beginSampling(string location, string backend)

Takes a string informing the backend where to store sample data and optionally a name of the specific logging backend to use. The default is the CSV backend. In most cases, the logging store will be a file name.

string

buildTaggedString(string format, ... )

Build a string using the specified tagged string format.

float

calcExplosionCoverage(Point3F pos, int id, uint covMask)

Calculates how much an explosion effects a specific object.

string

call(string functionName, string args...)

Apply the given arguments to the specified global function and return the result of the call.

void

cancel(int eventId)

cancel(eventId)

void

cancelAll(string objectId)

cancelAll(objectId): cancel pending events on the specified object. Events will be automatically cancelled if object is deleted.

void

cancelServerQuery()

cancelServerQuery();

int

castSpell(afxMagicSpellData datablock, ShapeBase caster, SceneObject target, SimObject extra)

Instantiates the magic spell defined by datablock and cast by caster.

void

cleanupTexturePool()

Release the unused pooled textures in texture manager freeing up video memory.

void

clearClientPaths()

void

clearGFXResourceFlags()

Clears the flagged state on all allocated GFX resources. See flagCurrentGFXResources for usage details.

void

clearServerPaths()

void

closeNetPort()

Closes the current network port.

void

closeSplashWindow()

Close our startup splash window.

void

cls()

Clears the console output.

string

collapseEscape(string text)

Replace all escape sequences in text with their respective character codes.

ColorI

ColorFloatToInt(LinearColorF color)

Convert from a float color to an integer color (0.0 - 1.0 to 0 to 255).

ColorI

ColorHEXToRGB(string hex)

Convert from a hex color value to an integer RGB (red, green, blue) color (00 - FF to 0 to 255).

ColorI

ColorHSBToRGB(Point3I hsb)

Convert from a HSB (hue, saturation, brightness) to an integer RGB (red, green, blue) color. HSB is also know as HSL or HSV as well, with the last letter standing for lightness or value.

LinearColorF

ColorIntToFloat(ColorI color)

Convert from a integer color to an float color (0 to 255 to 0.0 - 1.0).

string

ColorRGBToHEX(ColorI color)

Convert from a integer RGB (red, green, blue) color to hex color value (0 to 255 to 00 - FF).

string

ColorRGBToHSB(ColorI color)

Convert from a integer RGB (red, green, blue) color to HSB (hue, saturation, brightness). HSB is also know as HSL or HSV as well, with the last letter standing for lightness or value.

string

ColorScale(LinearColorF color, float scalar)

Returns color scaled by scalar (color*scalar).

void

commandToClient(NetConnection client, string func, ... )

Send a command from the server to the client.

void

commandToServer(string func, ... )

Send a command to the server.

bool

compile(string fileName, bool overrideNoDSO)

Compile a file to bytecode.

void

CompileLanguage(string inputFile, bool createMap)

Compiles a LSO language file. if createIndex is true, will also create languageMap.cs with the global variables for each string index. The input file must follow this example layout: TXT_HELLO_WORLD = Hello world in english!

bool

containerBoxEmpty(uint mask, Point3F center, float xRadius, float yRadius, float zRadius, bool useClientContainer)

See if any objects of the given types are present in box of given extent.

string

containerFindFirst(uint typeMask, Point3F origin, Point3F size)

Find objects matching the bitmask type within a box centered at point, with extents x, y, z.

string

containerFindNext()

Get more results from a previous call to containerFindFirst().

string

containerRayCast(Point3F start, Point3F end, uint mask, SceneObject pExempt, bool useClientContainer)

Cast a ray from start to end, checking for collision against items matching mask.

float

containerSearchCurrDist(bool useClientContainer)

Get distance of the center of the current item from the center of the current initContainerRadiusSearch.

float

containerSearchCurrRadiusDist(bool useClientContainer)

Get the distance of the closest point of the current item from the center of the current initContainerRadiusSearch.

SceneObject

containerSearchNext(bool useClientContainer)

Get next item from a search started with initContainerRadiusSearch() or initContainerTypeSearch().

bool

containsBadWords(string text)

Checks to see if text is a bad word.

int

countBits(int v)

Count the number of bits that are set in the given 32 bit integer.

bool

createPath(string path)

Create the given directory or the path leading to the given filename.

void

deactivateDirectInput()

Disables DirectInput.

void

deactivatePackage(String packageName)

Deactivates a previously activated package.

void

debug()

Drops the engine into the native C++ debugger.

void

debugDumpAllObjects()

Dumps all current EngineObject instances to the console.

void

debugEnumInstances(string className, string functionName)

Call the given function for each instance of the given class.

void

debugv(string variableName)

Logs the value of the given variable to the console.

int

decalManagerAddDecal(Point3F position, Point3F normal, float rot, float scale, DecalData decalData, bool isImmortal)

Adds a new decal to the decal manager.

void

decalManagerClear()

Removes all decals currently loaded in the decal manager.

bool

decalManagerDirty()

Returns whether the decal manager has unsaved modifications.

bool

decalManagerEditDecal(int decalID, Point3F pos, Point3F normal, float rotAroundNormal, float decalScale)

Edit specified decal of the decal manager.

bool

decalManagerLoad(string fileName)

Clears existing decals and replaces them with decals loaded from the specified file.

bool

decalManagerRemoveDecal(int decalID)

Remove specified decal from the scene.

void

decalManagerSave(String decalSaveFile)

Saves the decals for the active mission in the entered filename.

void

deleteDataBlocks()

Delete all the datablocks we've downloaded.

void

deleteVariables(string pattern)

Undefine all global variables matching the given name pattern.

void

describeGFXResources(string resourceTypes, string filePath, bool unflaggedOnly)

Dumps a description of GFX resources to a file or the console.

void

describeGFXStateBlocks(string filePath)

Dumps a description of all state blocks.

string

detag(string str)

Returns the string from a tag string.

bool

dispatchMessage(string queueName, string message, string data)

Dispatch a message to a queue.

bool

dispatchMessageObject(string queueName, string message)

Dispatch a message object to a queue.

bool

displaySplashWindow(string path)

Display a startup splash window suitable for showing while the engine still starts up.

void

DNetSetLogging(bool enabled)

Enables logging of the connection protocols.

void

dumpActivePostFX()

void

dumpAlloc(int allocNum)

Dumps information about the given allocated memory block.

void

dumpConsoleClasses(bool dumpScript, bool dumpEngine)

Dumps all declared console classes to the console.

void

dumpConsoleFunctions(bool dumpScript, bool dumpEngine)

Dumps all declared console functions to the console.

bool

dumpEngineDocs(string outputFile)

Dumps the engine scripting documentation to the specified file overwriting any existing content.

void

dumpFontCacheStatus()

Dumps to the console a full description of all cached fonts, along with info on the codepoints each contains.

void

dumpMaterialInstances()

Dumps a formatted list of currently allocated material instances to the console.

void

dumpMemSnapshot(string fileName)

Dumps a snapshot of current memory to a file.

void

dumpNetStats()

Dumps network statistics for each class to the console.

void

dumpNetStringTable()

Dump the current contents of the networked string table to the console.

void

dumpProcessList()

Dumps all ProcessObjects in ServerProcessList and ClientProcessList to the console.

void

dumpRandomNormalMap()

Creates a 64x64 normal map texture filled with noise. The texture is saved to randNormTex.png in the location of the game executable.

void

dumpStringMemStats()

Dumps information about String memory usage.

void

dumpTextureObjects()

Dumps a list of all active texture objects to the console.

void

dumpUnflaggedAllocs(string fileName)

Dumps all unflagged memory allocations.

void

duplicateCachedFont(string oldFontName, int oldFontSize, string newFontName)

Copy the specified old font to a new name. The new copy will not have a platform font backing it, and so will never have characters added to it. But this is useful for making copies of fonts to add postprocessing effects to via exportCachedFont.

void

echo(string message...)

Logs a message to the console.

string

echoThru(string passthru, string text...)

Like echo(), but first argument is returned.

void

enableSamples(string pattern, bool state)

Enable sampling for all keys that match the given name pattern. Slashes are treated as separators.

void

enableWinConsole(bool _enable)

enableWinConsole(bool);

bool

endsWith(string str, string suffix, bool caseSensitive)

Test whether the given string ends with the given suffix.

void

error(string message...)

Logs an error message to the console.

string

errorThru(string passthru, string text...)

Like error(), but first argument is returned.

string

eval(string consoleString)

eval(consoleString)

bool

excludeOtherInstance(string appIdentifer)

Used to exclude/prevent all other instances using the same identifier specified.

bool

exec(string fileName, bool noCalls, bool journalScript)

Execute the given script file.

bool

execPrefs(string relativeFileName, bool noCalls, bool journalScript)

Manually execute a special script file that contains game or editor preferences.

string

expandEscape(string text)

Replace all characters in text that need to be escaped for the string to be a valid string literal with their respective escape sequences.

string

expandFilename(string filename)

Grabs the full path of a specified file.

string

expandOldFilename(string filename)

Retrofits a filepath that uses old Torque style.

void

export(string pattern, string filename, bool append)

Write out the definitions of all global variables matching the given name pattern.

void

exportCachedFont(string faceName, int fontSize, string fileName, int padding, int kerning)

Export specified font to the specified filename as a PNG. The image can then be processed in Photoshop or another tool and reimported using importCachedFont. Characters in the font are exported as one long strip.

SimXMLDocument

exportEngineAPIToXML()

Create a XML document containing a dump of the entire exported engine API.

int

extractDatablockCacheCRC(string fileName)

String

fileBase(string fileName)

Get the base of a file name (removes extension and path)

String

fileCreatedTime(string fileName)

Returns a platform specific formatted string with the creation time for the file.

bool

fileDelete(string path)

Delete a file from the hard drive.

String

fileExt(string fileName)

Get the extension of a file.

String

fileModifiedTime(string fileName)

Returns a platform specific formatted string with the last modified time for the file.

String

fileName(string fileName)

Get only the file name of a path and file name string (removes path)

String

filePath(string fileName)

Get the path of a file (removes name and extension)

int

fileSize(string fileName)

Determines the size of a file on disk.

string

filterString(string baseString, string replacementChars)

Replaces the characters in a string with designated text.

String

findFirstFile(string pattern, bool recurse)

Returns the first file in the directory system matching the given pattern.

String

findFirstFileMultiExpr(string pattern, bool recurse)

Returns the first file in the directory system matching the given patterns.

String

findNextFile(string pattern)

Returns the next file matching a search begun in findFirstFile().

String

findNextFileMultiExpr(string pattern)

Returns the next file matching a search begun in findFirstFileMultiExpr().

string

firstWord(string text)

Return the first word in text.

void

flagCurrentAllocs()

Flags all current memory allocations.

void

flagCurrentGFXResources()

Flags all currently allocated GFX resources. Used for resource allocation and leak tracking by flagging current resources then dumping a list of unflagged resources at some later point in execution.

void

flushTextureCache()

Releases all textures and resurrects the texture manager.

void

freeMemoryDump()

Dumps some useful statistics regarding free memory.

bool

GenerateTamlSchema()

Generate a TAML schema file of all engine types.

Torque::UUID

generateUUID()

Generate a new universally unique identifier (UUID).

int

getActiveDDSFiles()

Returns the count of active DDSs files in memory.

string

getActiveLightManager()

Returns the active light manager name.

int

getAppVersionNumber()

Get the version of the application build, as a string.

string

getAppVersionString()

Get the version of the aplication build, as a human readable string.

GFXFormat

getBestHDRFormat()

Returns the best texture format for storage of HDR data for the active device.

String

getBitmapInfo(string filename)

Returns image info in the following format: width TAB height TAB bytesPerPixel TAB format. It will return an empty string if the file is not found.

Point3F

getBoxCenter(Box3F box)

Get the center point of an axis-aligned box.

string

getBuildString()

Get the type of build, "Debug" or "Release".

string

getCategoryOfClass(string className)

Returns the category of the given class.

string

getColorFromHSV(float hue, float sat, float val, float alpha)

Coverts an HSV formatted color into an RBG color.

string

getCompileTimeString()

Get the time of compilation.

int

getCoreLangTable()

Gets the primary LangTable used by the game.

ActionMap

getCurrentActionMap()

Returns the current ActionMap.

String

getCurrentDirectory()

Return the current working directory.

int

getDatablockCacheCRC()

string

getDescriptionOfClass(string className)

Returns the description string for the named class.

Point3F

getDesktopResolution()

Returns the width, height, and bitdepth of the screen/desktop.

String

getDirectoryList(string path, int depth)

Gathers a list of directories starting at the given path.

string

getDisplayDeviceInformation()

Get the string describing the active GFX device.

String

getDisplayDeviceList()

Returns a tab-seperated string of the detected devices across all adapters.

GFXAdapterType

getDisplayDeviceType()

Get the string describing the active GFX device type.

string

getDSOPath(string scriptFileName)

Get the absolute path to the file in which the compiled code for the given script file will be stored.

string

getEngineName()

Get the name of the engine product that this is running from, as a string.

int

getEventTimeLeft(int scheduleId)

getEventTimeLeft(scheduleId) Get the time left in ms until this event will trigger.

String

getExecutableName()

Gets the name of the game's executable.

string

getField(string text, int index)

Extract the field at the given index in the newline and/or tab separated list in text.

int

getFieldCount(string text)

Return the number of newline and/or tab separated fields in text.

string

getFields(string text, int startIndex, int endIndex)

Extract a range of fields from the given startIndex onwards thru endIndex.

int

getFileCount(string pattern, bool recurse)

Returns the number of files in the directory tree that match the given patterns.

int

getFileCountMultiExpr(string pattern, bool recurse)

Returns the number of files in the directory tree that match the given patterns.

int

getFileCRC(string fileName)

Provides the CRC checksum of the given file.

String

getFirstNumber(string str)

Get the first occuring number from str.

string

getFormatExtensions()

Returns a list of supported shape format extensions separated by tabs.Example output: *.dsq TAB *.dae TAB.

string

getFormatFilters()

Returns a list of supported shape formats in filter form.

Point3F

getFreeTargetPosition()

Returns the current location of the free target.

string

getFunctionPackage(string funcName)

Provides the name of the package the function belongs to.

String

getLightManagerNames()

Returns a tab seperated list of light manager names.

string

getLocalTime()

Return the current local time as: weekday month day year hour min sec.

String

getMainDotCsDir()

Get the absolute path to the directory that contains the main.cs script from which the engine was started.

void

getMaterialInstances(BaseMaterialDefinition target, GuiTreeViewCtrl tree)

Dumps a formatted list of currently allocated material instances to the console.

string

getMaterialMapping(string texName)

Returns the name of the material mapped to this texture.

float

getMax(float v1, float v2)

Calculate the greater of two specified numbers.

int

getMaxDynamicVerts()

Get max number of allowable dynamic vertices in a single vertex buffer.

float

getMaxF(float a, float b)

Returns the greater of the two arguments.

int

getMaxFrameAllocation()

string

getMethodPackage(string nameSpace, string method)

Provides the name of the package the method belongs to.

float

getMin(float v1, float v2)

Calculate the lesser of two specified numbers.

float

getMinF(float a, float b)

Returns the lesser of the two arguments.

MissionArea

getMissionAreaServerObject()

Get the MissionArea object, if any.

String

getNamedTargetList()

int

getNavMeshEventManager()

Get the EventManager object for all NavMesh updates.

string

getPackageList()

Returns a space delimited list of the active packages in stack order.

float

getPixelShaderVersion()

Returns the pixel shader version for the active device.

float

getRandom(int a, int b)

Returns a random number based on parameters passed in..

Point3F

getRandomDir(Point3F axis, float thetaMin, float thetaMax, float phiMin, float phiMax)

Get a random direction vector.

float

getRandomF(float a, float b)

Get a random float number between a and b.

int

getRandomSeed()

Get the current seed used by the random number generator.

int

getRealTime()

Return the current real time in milliseconds.

string

getRecord(string text, int index)

Extract the record at the given index in the newline-separated list in text.

int

getRecordCount(string text)

Return the number of newline-separated records in text.

string

getRecords(string text, int startIndex, int endIndex)

Extract a range of records from the given startIndex onwards thru endIndex.

int

getRootScene()

Get the root Scene object that is loaded.

Point3F

getRotationDirection(RotationF rot)

Gets the direction from the rotation's angles.

VectorF

getRotationForwardVector(RotationF rot)

Get the forward vector of a rotation.

VectorF

getRotationRightVector(RotationF rot)

Gets the right vector of a rotation.

VectorF

getRotationUpVector(RotationF rot)

Gets the up vector of a rotation.

Scene

getScene(uint sceneId)

Get the root Scene object that is loaded.

int

getSceneCount()

Get the number of active Scene objects that are loaded.

int

getScheduleDuration(int scheduleId)

getScheduleDuration(scheduleId);

int

getServerCount()

getServerCount();

int

getServerPathSet()

int

getSimTime()

Sim time is time since the game started.

int

getStockColorCount()

Gets a count of available stock colors.

LinearColorF

getStockColorF(string stockColorName)

Gets a floating-point-based stock color by name.

ColorI

getStockColorI(string stockColorName)

Gets a byte-based stock color by name.

string

getStockColorName(int stockColorIndex)

Gets the stock color name at the specified index.

string

getSubStr(string str, int start, int numChars)

Return a substring of str starting at start and continuing either through to the end of str (if numChars is -1) or for numChars characters (except if this would exceed the actual source string length).

string

getTag(string textTagString)

Extracts the tag from a tagged string.

string

getTaggedString(string tag)

Use the getTaggedString function to convert a tag to a string.

bool

getTerrainHeight(F32 x, F32 y)

Gets the terrain height at the specified position.

bool

getTerrainHeight(Point2I position)

Gets the terrain height at the specified position.

bool

getTerrainHeightBelowPosition(F32 x, F32 y)

Takes a world point and find the "highest" terrain underneath it.

bool

getTerrainHeightBelowPosition(Point2I position)

Takes a world point and find the "highest" terrain underneath it.

bool

getTerrainUnderWorldPoint(F32 x, F32 y, F32 z)

Takes a world point and find the "highest" terrain underneath it.

bool

getTerrainUnderWorldPoint(Point3F position)

Gets the terrain block that is located under the given world point.

String

getTextureProfileStats()

Returns a list of texture profiles in the format: ProfileName TextureCount TextureMB.

int

getTimeSinceStart(int scheduleId)

getTimeSinceStart(scheduleId);

string

getToken(string text, string delimiters, int index)

Extract the substring at the given index in the delimiters separated list in text.

int

getTokenCount(string text, string delimiters)

Return the number of delimiters substrings in text.

string

getTokens(string text, string delimiters, int startIndex, int endIndex)

Extract a range of substrings separated by delimiters at the given startIndex onwards thru endIndex.

int

getTrailingNumber(string str)

Get the numeric suffix of the given input string.

string

getUserDataDirectory()

getUserDataDirectory()

string

getUserHomeDirectory()

getUserHomeDirectory()

string

getVariable(string varName)

Returns the value of the named variable or an empty string if not found.

int

getVersionNumber()

Get the version of the engine build, as a string.

string

getVersionString()

Get the version of the engine build, as a human readable string.

bool

getWebDeployment()

Test whether Torque is running in web-deployment mode.

string

getWord(string text, int index)

Extract the word at the given index in the whitespace-separated list in text.

int

getWordCount(string text)

Return the number of whitespace-separated words in text.

string

getWords(string text, int startIndex, int endIndex)

Extract a range of words from the given startIndex onwards thru endIndex.

String

getWorkingDirectory()

Reports the current directory.

void

gotoWebPage(string address)

Open the given URL or file in the user's web browser.

void

importCachedFont(string faceName, int fontSize, string fileName, int padding, int kerning)

Import an image strip from exportCachedFont. Call with the same parameters you called exportCachedFont.

void

initContainerRadiusSearch(Point3F pos, float radius, uint mask, bool useClientContainer)

Start a search for items at the given position and within the given radius, filtering by mask.

void

initContainerTypeSearch(uint mask, bool useClientContainer)

Start a search for all items of the types specified by the bitset mask.

RotationF

InterpolateRotation(RotationF a, RotationF b, float factor)

Interpolates between two rotations.

bool

isAddressTypeAvailable(int addressType)

Determines if a specified address type can be reached.

bool

isalnum(string str, int index)

Test whether the character at the given position is an alpha-numeric character.

bool

isClass(string identifier)

Returns true if the passed identifier is the name of a declared class.

bool

isDatablockCacheSaved()

bool

isDebugBuild()

Test whether the engine has been compiled with TORQUE_DEBUG, i.e. if it includes debugging functionality.

bool

isDefined(string varName, string varValue)

Determines if a variable exists and contains a value.

bool

IsDirectory(string directory)

Determines if a specified directory exists or not.

bool

isEventPending(int scheduleId)

isEventPending(scheduleId);

bool

isFile(string fileName)

Determines if the specified file exists or not.

bool

isFloat(string str, bool sciOk)

Returns true if the string is a float.

bool

isFunction(string funcName)

Determines if a function exists or not.

bool

isInt(string str)

Returns true if the string is an integer.

bool

isMemberOfClass(string className, string superClassName)

Returns true if the class is derived from the super class.

bool

isMethod(string nameSpace, string method)

Determines if a class/namespace method exists.

bool

isObject(string objectName)

isObject(object)

bool

isPackage(String identifier)

Returns true if the identifier is the name of a declared package.

bool

isQueueRegistered(string queueName)

Determines if a dispatcher queue exists.

bool

isShippingBuild()

Test whether the engine has been compiled with TORQUE_SHIPPING, i.e. in a form meant for final release.

bool

isspace(string str, int index)

Test whether the character at the given position is a whitespace character.

bool

isStockColor(string stockColorName)

Gets whether the specified name is a stock color or not.

bool

isSupportedFormat(string extension)

bool

isToolBuild()

Test whether the engine has been compiled with TORQUE_TOOLS, i.e. if it includes tool-related functionality.

bool

isValidIP(string str)

Returns true if the string is a valid ip address, excepts localhost.

bool

isValidObjectName(string name)

Return true if the given name makes for a valid object name.

bool

isValidPort(string str)

Returns true if the string is a valid port number.

bool

isWriteableFileName(string fileName)

Determines if a file name can be written to using File I/O.

bool

lightScene(string completeCallbackFn, string mode)

Will generate static lighting for the scene if supported by the active light manager.

void

listGFXResources(bool unflaggedOnly)

Returns a list of the unflagged GFX resources. See flagCurrentGFXResources for usage details.

SimObject

loadObject(string filename)

Loads a serialized object from a file.

void

lockMouse(bool isLocked)

Lock or unlock the mouse to the window.

void

log(string message)

Logs a message to the console.

void

logError(string message)

Logs an error message to the console.

void

logWarning(string message)

Logs a warning message to the console.

string

ltrim(string str)

Remove leading whitespace from the string.

float

m2Pi()

Return the value of 2*PI (full-circle in radians).

float

mAbs(float v)

Calculate absolute value of specified value.

float

mAcos(float v)

Calculate the arc-cosine of v.

String

makeFullPath(string path, string cwd)

Converts a relative file path to a full path.

String

makeRelativePath(string path, string to)

Turns a full or local path to a relative one.

void

markDataBlocks()

Called before a series of datablocks are reloaded to help distinguish reloaded datablocks from already loaded ones.

float

mAsin(float v)

Calculate the arc-sine of v.

float

mAtan(float rise, float run)

Calculate the arc-tangent (slope) of a line defined by rise and run.

string

materialRayCast(Point3F start, Point3F end, uint mask, SceneObject pExempt, bool useClientContainer)

Cast a ray from start to end, checking for collision against items matching mask.

void

mathInit(... )

Install the math library with specified extensions.

TransformF

MatrixCreate(VectorF position, AngAxisF orientation)

Create a transform from the given translation and orientation.

TransformF

MatrixCreateFromEuler(Point3F angles)

@Create a matrix from the given rotations.

Point3F

MatrixInverseMulVector(MatrixF xfrm, Point3F vector)

Multiply the vector by the affine inverse of the transform.

Point3F

MatrixMulPoint(TransformF transform, Point3F point)

Multiply the given point by the given transform assuming that w=1.

TransformF

MatrixMultiply(TransformF left, TransformF right)

Multiply the two matrices.

VectorF

MatrixMulVector(TransformF transform, VectorF vector)

Multiply the vector by the transform assuming that w=0.

int

mCeil(float v)

Round v up to the nearest integer.

float

mClamp(float v, float min, float max)

Clamp the specified value between two bounds.

float

mCos(float v)

Calculate the cosine of v.

float

mDegToRad(float degrees)

Convert specified degrees into radians.

int

messageBox(string title, string message, MBButtons buttons, MBIcons icons)

Display a modal message box using the platform's native message box implementation.

string

mFloatLength(float v, uint precision)

Formats the specified number to the given number of decimal places.

int

mFloor(float v)

Round v down to the nearest integer.

float

mFMod(float v, float d)

Calculate the remainder of v/d.

float

mGetAngleBetweenVectors(VectorF vecA, VectorF vecB)

Returns angle between two vectors.

float

mGetSignedAngleBetweenVectors(VectorF vecA, VectorF vecB, VectorF norm)

Returns signed angle between two vectors, using a normal for orientation.

bool

mIsPow2(int v)

Returns whether the value is an exact power of two.

float

mLerp(float v1, float v2, float time)

Calculate linearly interpolated value between two specified numbers using specified normalized time.

float

mLog(float v)

Calculate the natural logarithm of v.

String

monthNumToStr(int num, bool abbreviate)

returns month as a word given a number or "" if number is bad

MatrixF

moveTransformAbs(MatrixF xfrm, Point3F pos)

Move the transform to the new absolute position.

MatrixF

moveTransformRel(MatrixF xfrm, Point3F pos)

Move the transform to the new relative position.

float

mPi()

Return the value of PI (half-circle in radians).

float

mPow(float v, float p)

Calculate b raised to the p-th power.

float

mRadToDeg(float radians)

Convert specified radians into degrees.

Point3F

mRandomDir(Point3F axis, float angleMin, float angleMax)

Returns a randomized direction based on a starting axis and the min/max angles.

Point3F

mRandomPointInSphere(float radius)

Returns a randomized point inside a sphere of a given radius.

int

mRound(float v)

Round v to the nth decimal place or the nearest whole number by default.

float

mRoundColour(float v, int n)

Round v to the nth decimal place or the nearest whole number by default.

int

mRoundDelta(float v, int d)

Round v to the nearest number based on the delta.

float

mSaturate(float v)

Clamp the specified value between 0 and 1 (inclusive).

float

mSin(float v)

Calculate the sine of v.

string

mSolveCubic(float a, float b, float c, float d)

Solve a cubic equation (3rd degree polynomial) of form a*x^3 + b*x^2 + c*x + d = 0.

string

mSolveQuadratic(float a, float b, float c)

Solve a quadratic equation (2nd degree polynomial) of form a*x^2 + b*x + c = 0.

string

mSolveQuartic(float a, float b, float c, float d, float e)

Solve a quartic equation (4th degree polynomial) of form a*x^4 + b*x^3 + c*x^2 + d*x + e = 0.

float

mSqrt(float v)

Calculate the square-root of v.

float

mTan(float v)

Calculate the tangent of v.

int

mWrap(int v, int min, int max)

Wrap the specified value between two bounds.

float

mWrapF(float v, float min, float max)

Wrap the specified value between two bounds.

int

nameToID(string objectName)

nameToID(object)

void

NavMeshIgnore(int objid, bool _ignore)

Flag this object as not generating a navmesh result.

void

NavMeshUpdateAll(int objid, bool remove)

Update all NavMesh tiles that intersect the given object's world box.

void

NavMeshUpdateAroundObject(int objid, bool remove)

Update all NavMesh tiles that intersect the given object's world box.

void

NavMeshUpdateOne(int meshid, int objid, bool remove)

Update all tiles in a given NavMesh that intersect the given object's world box.

string

nextToken(string str1, string token, string delim)

Tokenize a string using a set of delimiting characters.

void

openFile(string file)

Open the given file through the system. This will usually open the file in its associated application.

void

openFolder(string path)

Open the given folder in the system's file manager.

String

pathConcat(string path, string file)

Combines two separate strings containing a file path and file name together into a single string.

bool

pathCopy(string fromFile, string toFile, bool noOverwrite)

Copy a file to a new location.

void

pathOnMissionLoadDone()

Load all Path information from the mission.

void

physicsDebugDraw(bool enable)

physicsDebugDraw( bool enable )

void

physicsDestroy()

physicsDestroy()

void

physicsDestroyWorld(string worldName)

physicsDestroyWorld( String worldName )

float

physicsGetTimeScale()

physicsGetTimeScale()

bool

physicsInit(string library)

physicsInit( [string library] )

bool

physicsInitWorld(string worldName)

physicsInitWorld( String worldName )

bool

physicsPluginPresent()

Returns true if a physics plugin exists and is initialized.

void

physicsRestoreState()

physicsRestoreState()

void

physicsSetTimeScale(float scale)

physicsSetTimeScale( F32 scale )

bool

physicsSimulationEnabled()

physicsStopSimulation( String worldName )

void

physicsStartSimulation(string worldName)

physicsStartSimulation( String worldName )

void

physicsStopSimulation(string worldName)

physicsStopSimulation( String worldName )

void

physicsStoreState()

physicsStoreState()

void

playJournal(string filename)

Begin playback of a journal from a specified field.

void

playJournalToVideo(string journalFile, string videoFile, string encoder, float framerate, Point2I resolution)

Load a journal file and capture it video.

void

populateAllFontCacheRange(uint rangeStart, uint rangeEnd)

Populate the font cache for all fonts with Unicode code points in the specified range.

void

populateAllFontCacheString(string string)

Populate the font cache for all fonts with characters from the specified string.

void

populateFontCacheRange(string faceName, int fontSize, uint rangeStart, uint rangeEnd)

Populate the font cache for the specified font with Unicode code points in the specified range.

void

populateFontCacheString(string faceName, int fontSize, string string)

Populate the font cache for the specified font with characters from the specified string.

void

preloadClientDataBlocks()

Preload all datablocks in client mode.

void

profilerDump()

Dumps current profiling stats to the console window.

void

profilerDumpToFile(string fileName)

Dumps current profiling stats to a file.

void

profilerEnable(bool enable)

Enables or disables the profiler.

void

profilerMarkerEnable(string markerName, bool enable)

Enable or disable a specific profile.

void

profilerReset()

Resets the profiler, clearing it of all its data.

void

queryAllServers(uint lanPort, uint flags, string gameType, string missionType, uint minPlayers, uint maxPlayers, uint maxBots, uint regionMask, uint maxPing, uint minCPU, uint filterFlags)

queryAllServers(...);

void

queryLanServers(uint lanPort, uint flags, string gameType, string missionType, uint minPlayers, uint maxPlayers, uint maxBots, uint regionMask, uint maxPing, uint minCPU, uint filterFlags)

queryLanServers(...);

void

queryMasterServer(uint flags, string gameType, string missionType, uint minPlayers, uint maxPlayers, uint maxBots, uint regionMask, uint maxPing, uint minCPU, uint filterFlags)

queryMasterServer(...);

void

querySingleServer(string addrText, U8 flags)

querySingleServer(address, flags);

void

quit()

Shut down the engine and exit its process.

void

quitWithErrorMessage(string message, int status)

Display an error message box showing the given message and then shut down the engine and exit its process.

void

quitWithStatus(int status)

Shut down the engine and exit its process.

void

realQuit()

bool

registerMessageListener(string queueName, string listenerName)

Registers an event message.

void

registerMessageQueue(string queueName)

Registeres a dispatcher queue.

void

reInitMaterials()

Flushes all procedural shaders and re-initializes all active material instances.

void

reloadTextures()

Reload all the textures from disk.

string

removeField(string text, int index)

Remove the field in text at the given index.

void

removeGlobalShaderMacro(string name)

Removes an existing global macro by name.

string

removeRecord(string text, int index)

Remove the record in text at the given index.

void

removeTaggedString(int tag)

Remove a tagged string from the Net String Table.

string

removeToken(string text, string delimiters, int index)

Remove the substring in text separated by delimiters at the given index.

string

removeWord(string text, int index)

Remove the word in text at the given index.

void

resetDatablockCache()

void

resetFPSTracker()

Reset FPS stats (fps::)

void

ResetGFX()

forces the gbuffer to be reinitialized in cases of improper/lack of buffer clears.

void

resetLightManager()

Deactivates and then activates the currently active light manager.This causes most shaders to be regenerated and is often used when global rendering changes have occured.

string

restWords(string text)

Return all but the first word in text.

int

rolloverRayCast(Point3F start, Point3F end, uint mask)

Performs a raycast from points start to end and returns the ID of nearest intersecting object with a type found in the specified mask. Returns -1 if no object is found.

RotationF

RotationLookAt(Point3F origin, Point3F target, Point3F up)

Provides a rotation orientation to look at a target from a given position.

string

rtrim(string str)

Remove trailing whitespace from the string.

void

saveCompositeTexture(string pathR, string pathG, string pathB, string pathA, string inputKeyString, string saveAs)

File1,file2,file3,file4,[chanels for r g b and a locations],saveAs.

void

saveJournal(string filename)

Save the journal to the specified file.

bool

saveObject(SimObject object, string filename)

Serialize the object to a file.

void

sbmDumpStats()

void

sbmDumpStrings()

void

sceneDumpZoneStates(bool updateFirst)

Dump the current zoning states of all zone spaces in the scene to the console.

SceneObject

sceneGetZoneOwner(uint zoneId)

Return the SceneObject that contains the given zone.

void

screenShot(string file, string format, uint tileCount, float tileOverlap)

Takes a screenshot with optional tiling to produce huge screenshots.

void

setCoreLangTable(string lgTable)

Sets the primary LangTable used by the game.

bool

setCurrentDirectory(string path)

Set the current working directory.

void

setDatablockCacheCRC(uint crc)

void

setDefaultFov(float defaultFOV)

Set the default FOV for a camera.

string

setField(string text, int index, string replacement)

Replace the field in text at the given index with replacement.

int

SetFogVolumeQuality(uint new_quality)

Resizes the rendertargets of the Volumetric Fog object. @params new_quality new quality for the rendertargets 1 = full size, 2 = halfsize, 3 = 1/3, 4 = 1/4 ...

void

setFov(float FOV)

Set the FOV of the camera.

bool

setLightManager(string name)

Finds and activates the named light manager.

void

setLogMode(int mode)

Determines how log files are written.

void

setMainDotCsDir(string path)

setMainDotCsDir()

bool

setNetPort(int port, bool bind)

Set the network port for the game to use.

void

setPixelShaderVersion(float version)

Sets the pixel shader version for the active device. This can be used to force a lower pixel shader version than is supported by the device for testing or performance optimization.

void

setRandomSeed(int seed)

Set the current seed for the random number generator.

string

setRecord(string text, int index, string replacement)

Replace the record in text at the given index with replacement.

void

setReflectFormat(GFXFormat format)

Set the reflection texture format.

RotationF

setRotationRightVector(RotationF rot, VectorF rightVec)

Sets the right vector of the rotation.

RotationF

setRotationUpVector(RotationF rot, VectorF upVec)

Sets the up vector of the rotation.

bool

setServerInfo(uint index)

setServerInfo(index);

bool

setShadowManager(string sShadowSystemName)

string sShadowSystemName

string

setShadowVizLight(string name)

string

setToken(string text, string delimiters, int index, string replacement)

Replace the substring in text separated by delimiters at the given index with replacement.

void

setVariable(string varName, string value)

Sets the value of the named variable.

string

setWord(string text, int index, string replacement)

Replace the word in text at the given index with replacement.

void

setZoomSpeed(int speed)

Set the zoom speed of the camera. This affects how quickly the camera changes from one field of view to another.

bool

sfxCreateDevice(string provider, string device, bool useHardware, int maxBuffers)

Try to create a new sound device using the given properties.

SFXSound

sfxCreateSource(SFXDescription description, string filename)

Create a temporary SFXProfile from the given description and filename and then create and return a new source that plays the profile.

SFXSound

sfxCreateSource(SFXDescription description, string filename, float x, float y, float z)

Create a temporary SFXProfile from the given description and filename and then create and return a new source that plays the profile. Position the sound source at the given coordinates (if it is a 3D sound).

SFXSource

sfxCreateSource(SFXTrack track)

Create a new source that plays the given track.

SFXSource

sfxCreateSource(SFXTrack track, float x, float y, float z)

Create a new source that plays the given track and position its 3D sounds source at the given coordinates (if it is a 3D sound).

void

sfxDeleteDevice()

Delete the currently active sound device and release all its resources.

void

sfxDeleteWhenStopped(SFXSource source)

Mark the given source for deletion as soon as it moves into stopped state.

void

sfxDumpSources(bool includeGroups)

Dump information about all current SFXSource instances to the console.

string

sfxDumpSourcesToString(bool includeGroups)

Dump information about all current SFXSource instances to a string.

string

sfxGetActiveStates()

Return a newline-separated list of all active states.

string

sfxGetAvailableDevices()

Get a list of all available sound devices.

string

sfxGetDeviceInfo()

Return information about the currently active sound device.

SFXDistanceModel

sfxGetDistanceModel()

Get the falloff curve type currently being applied to 3D sounds.

float

sfxGetDopplerFactor()

Get the current global doppler effect setting.

float

sfxGetRolloffFactor()

Get the current global scale factor applied to volume attenuation of 3D sounds in the logarithmic model.

SFXSource

sfxPlay(SFXSource source)

Start playback of the given source.

void

sfxPlay(SFXTrack track)

Create a new play-once source for the given track and start playback of the source.

void

sfxPlay(SFXTrack track, float x, float y, float z)

Create a new play-once source for the given track, position its 3D sound at the given coordinates (if the track's description is set up for 3D sound) and start playback of the source.

SFXSource

sfxPlayOnce(SFXDescription description, string filename)

Create a new temporary SFXProfile from the given description and filename, then create a play-once source for it and start playback.

SFXSource

sfxPlayOnce(SFXDescription description, string filename, float x, float y, float z, float fadeInTime)

Create a new temporary SFXProfile from the given description and filename, then create a play-once source for it and start playback. Position the source's 3D sound at the given coordinates (only if the description is set up for 3D sound).

SFXSource

sfxPlayOnce(SFXTrack track)

Create a play-once source for the given track.

SFXSource

sfxPlayOnce(SFXTrack track, float x, float y, float z, float fadeInTime)

Create a play-once source for the given given track and position the source's 3D sound at the given coordinates only if the track's description is set up for 3D sound).

void

sfxSetDistanceModel(SFXDistanceModel model)

Set the falloff curve type to use for distance-based volume attenuation of 3D sounds.

void

sfxSetDopplerFactor(float value)

Set the global doppler effect scale factor.

void

sfxSetRolloffFactor(float value)

Set the global scale factor to apply to volume attenuation of 3D sounds in the logarithmic model.

void

sfxStop(SFXSource source)

Stop playback of the given source.

void

sfxStopAndDelete(SFXSource source)

Stop playback of the given source (if it is not already stopped) and delete the source.

void

ShakeCamera(float duration, float falloff, VectorF amplitude, VectorF frequency)

int

sizeof(string objectOrClass)

Determines the memory consumption of a class or object.

void

snapToggle()

Prevents mouse movement from being processed.

bool

spawnObject(class )

Global function used for spawning any type of object.

void

StartClientReplication()

Activates the shape replicator.

int

startEffectron(afxEffectronData datablock, string constraintSource, string constraintName, SimObject extra)

Instantiates the effectron defined by datablock.

void

startFileChangeNotifications()

Start watching resources for file changes.

void

StartFoliageReplication()

Activates the foliage replicator.

void

startHeartbeat()

startHeartbeat();

int

startPrecisionTimer()

startPrecisionTimer() - Create and start a high resolution platform timer. Returns the timer id.

int

startSelectron(SceneObject selectedObj, unsigned int subcode, SimObject extra)

Instantiates a selectron.

bool

startsWith(string str, string prefix, bool caseSensitive)

Test whether the given string begins with the given prefix.

void

startVideoCapture(GuiCanvas canvas, string filename, string encoder, float framerate, Point2I resolution)

Begins a video capture session.

void

stopFileChangeNotifications()

Stop watching resources for file changes.

void

stopHeartbeat()

stopHeartbeat();

int

stopPrecisionTimer(int id)

stopPrecisionTimer( S32 id ) - Stop and destroy timer with the passed id. Returns the elapsed milliseconds.

void

stopSampling()

Stops the rendering sampler.

void

stopServerQuery()

stopServerQuery();

void

stopVideoCapture()

Stops the video capture session.

int

strasc(string chr)

Return the integer character code value corresponding to the first character in the given string.

string

strchr(string str, string chr)

Find the first occurrence of the given character in str.

int

strchrpos(string str, string chr, int start)

Find the first occurrence of the given character in the given string.

int

strcmp(string str1, string str2)

Compares two strings using case-sensitive comparison.

string

strformat(string format, string value)

Format the given value as a string using printf-style formatting.

int

stricmp(string str1, string str2)

Compares two strings using case-insensitive comparison.

int

strinatcmp(string str1, string str2)

Compares two strings using "natural order" case-insensitive comparison.

string

stripChars(string str, string chars)

Remove all occurrences of characters contained in chars from str.

string

StripMLControlChars(string inString)

Strip TorqueML control characters from the specified string, returning a 'clean' version.

String

stripTrailingNumber(string str)

Strip a numeric suffix from the given string.

bool

strIsMatchExpr(string pattern, string str, bool caseSensitive)

Match a pattern against a string.

bool

strIsMatchMultipleExpr(string patterns, string str, bool caseSensitive)

Match a multiple patterns against a single string.

int

strlen(string str)

Get the length of the given string in bytes.

int

strlenskip(string str, string first, string last)

Calculate the length of a string in characters, skipping everything between and including first and last.

string

strlwr(string str)

Return an all lower-case version of the given string.

int

strnatcmp(string str1, string str2)

Compares two strings using "natural order" case-sensitive comparison.

int

strpos(string haystack, string needle, int offset)

Find the start of needle in haystack searching from left to right beginning at the given offset.

int

strposr(string haystack, string needle, int offset)

Find the start of needle in haystack searching from right to left beginning at the given offset.

string

strrchr(string str, string chr)

Find the last occurrence of the given character in str.

int

strrchrpos(string str, string chr, int start)

Find the last occurrence of the given character in the given string.

string

strrepeat(string str, int numTimes, string delimiter)

Return a string that repeats str numTimes number of times delimiting each occurrence with delimiter.

string

strreplace(string source, string from, string to)

Replace all occurrences of from in source with to.

int

strstr(string string, string substring)

Find the start of substring in the given string searching from left to right.

string

strToggleCaseToWords(string str)

Parse a Toggle Case word into separate words.

string

strToPlayerName(string ptr)

strToPlayerName(string);

string

strupr(string str)

Return an all upper-case version of the given string.

RotationF

SubtractRotation(RotationF a, RotationF b)

Subtracts two rotations.

string

TamlRead(string filename, string format)

Read an object from a file using Taml.

bool

TamlWrite(SimObject simObject, string filename, string format, bool compressed)

Writes an object to a file using Taml.

void

telnetSetParameters(int port, string consolePass, string listenPass, bool remoteEcho)

Initializes and open the telnet console.

void

touchDataBlocks()

Called after a series of datablocks are reloaded to trigger some important actions on the reloaded datablocks.

void

trace(bool enable)

Enable or disable tracing in the script code VM.

string

trim(string str)

Remove leading and trailing whitespace from the string.

void

tsUpdateImposterImages(bool forceUpdate)

tsUpdateImposterImages( bool forceupdate )

void

unregisterMessageListener(string queueName, string listenerName)

Unregisters an event message.

void

unregisterMessageQueue(string queueName)

Unregisters a dispatcher queue.

void

validateMemory()

Used to validate memory space for the game.

VectorF

VectorAdd(VectorF a, VectorF b)

Add two vectors.

VectorF

VectorCross(VectorF a, VectorF b)

Calculcate the cross product of two vectors.

float

VectorDist(VectorF a, VectorF b)

Compute the distance between two vectors.

VectorF

VectorDiv(VectorF a, VectorF b)

Divide two vectors.

float

VectorDot(VectorF a, VectorF b)

Compute the dot product of two vectors.

float

VectorLen(VectorF v)

Calculate the magnitude of the given vector.

VectorF

VectorLerp(VectorF a, VectorF b, float t)

Linearly interpolate between two vectors by t.

VectorF

VectorMidPoint(VectorF a, VectorF b)

Gets the midpoint between the two vectors.

VectorF

VectorMul(VectorF a, VectorF b)

Multiplies two vectors.

VectorF

VectorNormalize(VectorF v)

Brings a vector into its unit form, i.e. such that it has the magnitute 1.

MatrixF

VectorOrthoBasis(AngAxisF aa)

Create an orthogonal basis from the given vector.

VectorF

VectorReflect(VectorF vec, VectorF normal)

Compute the reflection of a vector based on a normal.

string

VectorRot(Point3F v, float angle)

rotate a vector in 2d

VectorF

VectorScale(VectorF a, float scalar)

Scales a vector by a scalar.

VectorF

VectorSub(VectorF a, VectorF b)

Subtract two vectors.

void

warn(string message...)

Logs a warning message to the console.

string

warnThru(string passthru, string text...)

Like warn(), but first argument is returned.

bool

wasSyntaxError()

Returns true if script compiler had a syntax error. Useful for detecting syntax errors after reloading a script.

String

weekdayNumToStr(int num, bool abbreviate)

returns weekday as a word given a number or "" if number is bad

void

writeFontCache()

Force all cached fonts to serialize themselves to the cache.

Detailed Description

Public Enumerations

_TamlFormatMode

Enumerator

xml
binary 
afxBillboard_BlendStyle

Enumerator

NORMAL

...

No blending style.

ADDITIVE

...

Adds the color of the pixel to the frame buffer with full alpha for each pixel.

SUBTRACTIVE

...

Subtractive Blending. Reverses the color model, causing dark colors to have a stronger visual effect.

PREMULTALPHA

...

Color blends with the colors of the imagemap rather than the alpha.

Possible blending types.

afxParticleEmitterPath_OriginType

Enumerator

origin

...

point

...

vector

...

tangent

...

Possible particle emitter path origin types.

afxParticlePool_PoolType

Enumerator

normal

...

Lowest priority level, no highlighting.

pass

...

twopass

...

Possible particle pool types.

afxPath3DLoopType

Enumerator

constant

...

cycle

...

oscillate

...

Possible loop types for an afxPath.

afxPhraseEffect_MatchType

Enumerator

any

...

all

...

Possible phrase effect match types.

afxPhraseEffect_PhraseType

Enumerator

triggered

...

continuous

...

Possible phrase effect types.

afxPhraseEffect_StateType

Enumerator

on

...

off

...

both

...

Possible phrase effect state types.

afxPlayerMovement_OpType

Enumerator

add

...

multiply

...

replace

...

mult

...

Possible player movement operation types.

afxProjectile_LaunchDirType

Enumerator

towardPos2Constraint

...

orientConstraint

...

launchDirField

...

Possible projectile launch direction types.

afxRPGMagicSpell_TargetType

Enumerator

nothing

...

self

...

friend

...

enemy

...

corpse

...

free

...

Possible RPG spell target types.

afxXM_BoxConformType

Enumerator

x

...

x

...

y

...

y

...

z

...

z

...

x

...

y

...

z

...

Possible box conform alignment types.

afxXM_WaveFormType

Enumerator

none

...

sine

...

square

...

triangle

...

sawtooth

...

noise

...

one

...

Possible waveform types.

afxXM_WaveOpType

Enumerator

add

...

multiply

...

replace

...

mult

...

Possible wave operation types.

afxXM_WaveParamType

Enumerator

none

...

pos

...

x

...

y

...

z

...

ori

...

pos2

...

x

...

y

...

z

...

scale

...

x

...

y

...

z

...

color

...

red

...

green

...

blue

...

alpha

...

vis

...

position

...

x

...

y

...

z

...

orientation

...

position2

...

x

...

y

...

z

...

r

...

g

...

b

...

a

...

visibility

...

Possible wave parameter types.

afxZodiac_BlendType

Enumerator

normal

...

Lowest priority level, no highlighting.

additive

...

subtractive

...

Possible zodiac blend types.

afxZodiacPlane_BlendType

Enumerator

normal

...

Lowest priority level, no highlighting.

additive

...

subtractive

...

Possible zodiac blend types.

afxZodiacPlane_FacingType

Enumerator

up

...

down

...

forward

...

backward

...

right

...

left

...

front

...

back

...

Possible zodiac plane facing types.

baseTexFormat

Enumerator

NONE

No cached terrain.

DDS

Cache the terrain in a DDS format.

PNG

Cache the terrain in a PNG format.

Description.

?

CameraMotionMode

Enumerator

Stationary

Camera does not rotate or move.

FreeRotate

Camera may rotate but does not move.

Fly

Camera may rotate and move freely.

OrbitObject

Camera orbits about a given object. Damage flash and white out is determined by the object being orbited. See Camera::setOrbitMode() to set the orbit object and other parameters.

OrbitPoint

Camera orbits about a given point. See Camera::setOrbitMode() to set the orbit point and other parameters.

TrackObject

Camera always faces a given object. See Camera::setTrackObject() to set the object to track and a distance to remain from the object.

Overhead

Camera moves in the XY plane.

EditOrbit

Used by the World Editor to orbit about a point. When first activated, the camera is rotated to face the orbit point rather than move to it.

Movement behavior type for Camera.

CoverPointSize

Enumerator

Prone

Only provides cover when prone.

Prone pose.

Crouch

Only provides cover when crouching.

Crouch pose.

Stand

Provides cover when standing.

Standard movement pose.

The size of a cover point.

GFXAdapterType

Enumerator

OpenGL

OpenGL.

D3D11

Direct3D 11.

NullDevice

Null device for dedicated servers.

Back-end graphics API used by the GFX subsystem.

GFXBlend

Enumerator

GFXBlendZero

(0, 0, 0, 0)

GFXBlendOne

(1, 1, 1, 1)

GFXBlendSrcColor

(Rs, Gs, Bs, As)

GFXBlendInvSrcColor

(1 - Rs, 1 - Gs, 1 - Bs, 1 - As)

GFXBlendSrcAlpha

(As, As, As, As)

GFXBlendInvSrcAlpha

( 1 - As, 1 - As, 1 - As, 1 - As)

GFXBlendDestAlpha

(Ad Ad Ad Ad)

GFXBlendInvDestAlpha

(1 - Ad 1 - Ad 1 - Ad 1 - Ad)

GFXBlendDestColor

(Rd, Gd, Bd, Ad)

GFXBlendInvDestColor

(1 - Rd, 1 - Gd, 1 - Bd, 1 - Ad)

GFXBlendSrcAlphaSat

(f, f, f, 1) where f = min(As, 1 - Ad)

The supported blend modes.

GFXBlendOp

Enumerator

GFXBlendOpAdd
GFXBlendOpSubtract
GFXBlendOpRevSubtract
GFXBlendOpMin
GFXBlendOpMax

The blend operators.

GFXCmpFunc

Enumerator

GFXCmpNever
GFXCmpLess
GFXCmpEqual
GFXCmpLessEqual
GFXCmpGreater
GFXCmpNotEqual
GFXCmpGreaterEqual
GFXCmpAlways

The supported comparison functions.

GFXCullMode

Enumerator

GFXCullNone
GFXCullCW
GFXCullCCW

The render cull modes.

GFXFormat

Enumerator

GFXFormatR8G8B8
GFXFormatR8G8B8A8
GFXFormatR8G8B8A8_SRGB
GFXFormatR8G8B8X8
GFXFormatR32F
GFXFormatR5G6B5
GFXFormatR5G5B5A1
GFXFormatR5G5B5X1
GFXFormatA4L4
GFXFormatA8L8
GFXFormatA8
GFXFormatL8
GFXFormatBC1
GFXFormatBC2
GFXFormatBC3
GFXFormatBC4
GFXFormatBC5
GFXFormatD32
GFXFormatD24X8
GFXFormatD24S8
GFXFormatD24FS8
GFXFormatD16
GFXFormatR32G32B32A32F
GFXFormatR16G16B16A16F
GFXFormatL16
GFXFormatR16G16B16A16
GFXFormatR16G16
GFXFormatR16F
GFXFormatR16G16F
GFXFormatR10G10B10A2

The texture formats.

note:

Not all formats are supported on all platforms.

GFXStencilOp

Enumerator

GFXStencilOpKeep
GFXStencilOpZero
GFXStencilOpReplace
GFXStencilOpIncrSat
GFXStencilOpDecrSat
GFXStencilOpInvert
GFXStencilOpIncr
GFXStencilOpDecr

The stencil operators.

GFXTextureAddressMode

Enumerator

GFXAddressWrap
GFXAddressMirror
GFXAddressClamp
GFXAddressBorder
GFXAddressMirrorOnce

The texture address modes.

GFXTextureFilterType

Enumerator

GFXTextureFilterNone
GFXTextureFilterPoint
GFXTextureFilterLinear
GFXTextureFilterAnisotropic

The texture filter types.

GuiAlignmentType

Enumerator

Left

Child controls are positioned in order from right to left (right-most control is first)

Scroll from right towards left.

Center
Right

Child controls are positioned in order from left to right (left-most control is first)

Scroll from left towards right.

Top

Tab headers on top edge.

Child controls are positioned in order from bottom to top (bottom-most control is first)

Bottom

Tab headers on bottom edge.

Child controls are positioned in order from top to bottom (top-most control is first)

GuiAutoScrollDirection

Enumerator

Up

Scroll from bottom towards top.

Down

Scroll from top towards bottom.

Left

Child controls are positioned in order from right to left (right-most control is first)

Scroll from right towards left.

Right

Child controls are positioned in order from left to right (left-most control is first)

Scroll from left towards right.

Direction in which to scroll the child control.

GuiBitmapMode

Enumerator

Stretched

Stretch bitmap to fit control extents.

Centered

Center bitmap in control.

Rendering behavior when placing bitmaps in controls.

GuiButtonType

Enumerator

PushButton

A button that triggers an action when clicked.

ToggleButton

A button that is toggled between on and off state.

RadioButton

A button placed in groups for presenting choices.

Type of button control.

GuiDockingType

Enumerator

None

Simple point sampled filtering. This is the fastest and lowest quality mode.

No transition. Immediately move on to processing the slot or immediately move on to the next slot.

Allow both childs to resize (default).

Disable blending for this material.

No mesh data.

Client
Top

Tab headers on top edge.

Child controls are positioned in order from bottom to top (bottom-most control is first)

Bottom

Tab headers on bottom edge.

Child controls are positioned in order from top to bottom (top-most control is first)

Left

Child controls are positioned in order from right to left (right-most control is first)

Scroll from right towards left.

Right

Child controls are positioned in order from left to right (left-most control is first)

Scroll from left towards right.

GuiFontCharset

Enumerator

ANSI
SYMBOL
SHIFTJIS
HANGEUL
HANGUL
GB2312
CHINESEBIG5
OEM
JOHAB
HEBREW
ARABIC
GREEK
TURKISH
VIETNAMESE
THAI
EASTEUROPE
RUSSIAN
MAC
BALTIC 
GuiFrameState

Enumerator

alwaysOn

Always visible.

alwaysOff

Never visible.

dynamic

Only visible when actually needed, i.e. when the child control(s) exceed the visible space on the given axis.

GuiGraphType

Enumerator

Bar

Plot the curve as a bar chart.

Filled

Plot a filled poly graph that connects the data points on the curve.

Point

Plot each data point on the curve as a single dot.

PolyLine

Plot straight lines through the data points of the curve.

The charting style of a single plotting curve in a GuiGraphCtrl.

GuiHorizontalSizing

Enumerator

right

...

width
left

...

center
relative
aspectLeft
aspectRight
aspectCenter
windowRelative

Horizontal sizing behavior of a GuiControl.

GuiHorizontalStackingType

Enumerator

Right

Child controls are positioned in order from left to right (left-most control is first)

Scroll from left towards right.

Left

Child controls are positioned in order from right to left (right-most control is first)

Scroll from right towards left.

Determines how child controls are stacked horizontally.

GuiIconButtonIconLocation

Enumerator

None

Simple point sampled filtering. This is the fastest and lowest quality mode.

No transition. Immediately move on to processing the slot or immediately move on to the next slot.

Allow both childs to resize (default).

Disable blending for this material.

No mesh data.

Left

Child controls are positioned in order from right to left (right-most control is first)

Scroll from right towards left.

Right

Child controls are positioned in order from left to right (left-most control is first)

Scroll from left towards right.

Center 
GuiIconButtonTextLocation

Enumerator

None

Simple point sampled filtering. This is the fastest and lowest quality mode.

No transition. Immediately move on to processing the slot or immediately move on to the next slot.

Allow both childs to resize (default).

Disable blending for this material.

No mesh data.

Bottom

Tab headers on bottom edge.

Child controls are positioned in order from top to bottom (top-most control is first)

Right

Child controls are positioned in order from left to right (left-most control is first)

Scroll from left towards right.

Top

Tab headers on top edge.

Child controls are positioned in order from bottom to top (bottom-most control is first)

Left

Child controls are positioned in order from right to left (right-most control is first)

Scroll from right towards left.

Center 
GuiScrollBarBehavior

Enumerator

alwaysOn

Always visible.

alwaysOff

Never visible.

dynamic

Only visible when actually needed, i.e. when the child control(s) exceed the visible space on the given axis.

Display behavior of a scroll bar. Determines when a scrollbar will be visible.

GuiSeparatorType

Enumerator

Vertical

Stack children vertically by setting their Y position.

Divide vertically placing one child left and one child right.

Horizontal

Stack children horizontall by setting their X position.

Divide horizontally placing one child on top and one child below.

GuiSeparatorCtrl orientations.

GuiSplitFixedPanel

Enumerator

None

Simple point sampled filtering. This is the fastest and lowest quality mode.

No transition. Immediately move on to processing the slot or immediately move on to the next slot.

Allow both childs to resize (default).

Disable blending for this material.

No mesh data.

FirstPanel

Keep.

SecondPanel

Which side of the splitter to keep at a fixed size (if any).

GuiSplitOrientation

Enumerator

Vertical

Stack children vertically by setting their Y position.

Divide vertically placing one child left and one child right.

Horizontal

Stack children horizontall by setting their X position.

Divide horizontally placing one child on top and one child below.

Axis along which to divide the container's space.

GuiStackingType

Enumerator

Vertical

Stack children vertically by setting their Y position.

Divide vertically placing one child left and one child right.

Horizontal

Stack children horizontall by setting their X position.

Divide horizontally placing one child on top and one child below.

Dynamic

Automatically switch between Vertical and Horizontal stacking. Vertical stacking is chosen when the stack control is taller than it is wide, horizontal stacking is chosen when the stack control is wider than it is tall.

Stacking method used to position child controls.

GuiTabPosition

Enumerator

Top

Tab headers on top edge.

Child controls are positioned in order from bottom to top (bottom-most control is first)

Bottom

Tab headers on bottom edge.

Child controls are positioned in order from top to bottom (top-most control is first)

Where the control should put the tab headers for selecting individual pages.

GuiTheoraTranscoder

Enumerator

Auto

Automatically detect most appropriate setting.

Generic

Slower but beneric transcoder that can convert all Y'CbCr input formats to RGB or RGBA output.

SSE2420RGBA

Fast SSE2-based transcoder with fixed conversion from 4:2:0 Y'CbCr to RGBA.

Routine to use for converting Theora's Y'CbCr pixel format to RGB color space.

GuiTSRenderStyles

Enumerator

standard
side
separate

Style of rendering for a GuiTSCtrl.

GuiVerticalSizing

Enumerator

bottom
height
top
center
relative
aspectTop
aspectBottom
aspectCenter
windowRelative

Vertical sizing behavior of a GuiControl.

GuiVerticalStackingType

Enumerator

Bottom

Tab headers on bottom edge.

Child controls are positioned in order from top to bottom (top-most control is first)

Top

Tab headers on top edge.

Child controls are positioned in order from bottom to top (bottom-most control is first)

Determines how child controls are stacked vertically.

ImageAssetType

Enumerator

Albedo
Normal

Knot will have a smooth camera translation/rotation effect.

ORMConfig
GUI
Roughness
AO
Metalness
Glow
Particle
Decal
Cubemap

Uses a static CubemapData.

Uses a cubemap baked from the probe's current position.

Type of mesh data available in a shape.

ItemLightType

Enumerator

NoLight

No light is attached.

The item has no light attached.

ConstantLight

A constant emitting light is attached.

The item has a constantly emitting light attached.

PulsingLight

A pusling light is attached.

The item has a pulsing light attached.

The type of light the Item has.

LogLevel

Enumerator

normal

...

Lowest priority level, no highlighting.

warning

Mid level priority, tags and highlights possible issues in blue.

error

Highest priority level, extreme emphasis on this entry. Highlighted in red.

Priority levels for logging entries.

MarkerKnotType

Enumerator

Normal

Knot will have a smooth camera translation/rotation effect.

Only

Will do the same for translations, leaving rotation un-touched.

Kink

The rotation will take effect immediately for an abrupt rotation change.

The type of knot that this marker will be.

MarkerSmoothingType

Enumerator

Spline

Marker will cause the movements of the pathed object to be smooth.

Linear

Marker will have no smoothing effect.

Volume attenuates linearly from the references distance onwards to max distance where it reaches zero.

The type of smoothing this marker will have for pathed objects.

MaterialAnimType

Enumerator

Scroll

Scroll the material along the X/Y axis.

Rotate

Rotate the material around a point.

Wave

Warps the material with an animation using Sin, Triangle or Square mathematics.

Scale

Scales the material larger and smaller with a pulsing effect.

Sequence

Enables the material to have multiple frames of animation in its imagemap.

The type of animation effect to apply to this material.

MaterialBlendOp

Enumerator

None

Simple point sampled filtering. This is the fastest and lowest quality mode.

No transition. Immediately move on to processing the slot or immediately move on to the next slot.

Allow both childs to resize (default).

Disable blending for this material.

No mesh data.

Mul

Multiplicative blending.

PreMul

Premultiplied alpha.

Add

Adds the color of the material to the frame buffer with full alpha for each pixel.

AddAlpha

The color is modulated by the alpha channel before being added to the frame buffer.

Sub

Subtractive Blending. Reverses the color model, causing dark colors to have a stronger visual effect.

LerpAlpha

Linearly interpolates between Material color and frame buffer color based on alpha.

The type of graphical blending operation to apply to this material.

MaterialWaveType

Enumerator

Sin

Warps the material along a curved Sin Wave.

Triangle

Warps the material along a sharp Triangle Wave.

Square

Warps the material along a wave which transitions between two oppposite states. As a Square Wave, the transition is quick and sudden.

When using the Wave material animation, one of these Wave Types will be used to determine the type of wave to display.

MBButtons

Enumerator

Ok
OkCancel
RetryCancel
SaveDontSave
SaveDontSaveCancel

Which buttons to display on a message box.

MBIcons

Enumerator

Information
Warning
Stop

Stops the spin sequence at its current position.

Stop the sound source spawned last by this playlist. Then proceed.

Question

What icon to show on a message box.

MBReturnVal

Enumerator

OK
Cancelled
Retry
DontSave

Return value for messageBox() indicating which button was pressed by the user.

NavMeshWaterMethod

Enumerator

Ignore

Ignore all water surfaces.

Ignore the loaded state.

No changes to the spin sequence.

Solid

Treat water surfaces as solid and walkable.

Impassable

Treat water as an impassable obstacle.

The method used to include water surfaces in the NavMesh.

ParticleBlendStyle

Enumerator

NORMAL

...

No blending style.

ADDITIVE

...

Adds the color of the pixel to the frame buffer with full alpha for each pixel.

SUBTRACTIVE

...

Subtractive Blending. Reverses the color model, causing dark colors to have a stronger visual effect.

PREMULTALPHA

...

Color blends with the colors of the imagemap rather than the alpha.

The type of visual blending style to apply to the particles.

PFXRenderTime

Enumerator

PFXBeforeBin

Before a RenderInstManager bin.

PFXAfterBin

After a RenderInstManager bin.

PFXAfterDiffuse

After the diffuse rendering pass.

PFXEndOfFrame

When the end of the frame is reached.

PFXTexGenOnDemand

This PostEffect is not processed by the manager. It will generate its texture when it is requested.

When to process this effect during the frame.

PFXTargetClear

Enumerator

PFXTargetClear_None

Never clear the PostEffect target.

PFXTargetClear_OnCreate

Clear once on create.

PFXTargetClear_OnDraw

Clear before every draw.

Describes when the target texture should be cleared.

PFXTargetViewport

Enumerator

PFXTargetViewport_TargetSize

Set viewport to match target size (default).

PFXTargetViewport_GFXViewport

Use the current GFX viewport (scaled to match target size).

PFXTargetViewport_NamedInTexture0

Use the input texture 0 if it is named (scaled to match target size), otherwise revert to PFXTargetViewport_TargetSize if there is none.

Specifies how the viewport should be set up for a PostEffect's target.

note:

Applies to both the diffuse target and the depth target (if defined).

PhysicalZone_ForceType

Enumerator

vector

...

spherical

...

cylindrical

...

sphere

...

cylinder

...

Possible physical zone force types.

PhysicsSimType

Enumerator

ClientOnly

Only handle physics on the client.

ServerOnly

Only handle physics on the server.

ClientServer

Handle physics on both the client and server.

How to handle the physics simulation with the client's and server.

PlayerPose

Enumerator

Stand

Provides cover when standing.

Standard movement pose.

Sprint

Sprinting pose.

Crouch

Only provides cover when crouching.

Crouch pose.

Prone

Only provides cover when prone.

Prone pose.

Swim

Swimming pose.

The pose of the Player.

ReflectionModeEnum

Enumerator

Reflections

This probe does not provide any local reflection data.

Cubemap

Uses a static CubemapData.

Uses a cubemap baked from the probe's current position.

Cubemap

Uses a static CubemapData.

Uses a cubemap baked from the probe's current position.

Type of mesh data available in a shape.

ReflectProbeType

Enumerator

Sphere

Sphere shaped.

Box

Box shape.

Type of mesh data available in a shape.

RenderTexTargetSize

Enumerator

windowsize

Render to the size of the window.

windowsizescaled

Render to the size of the window, scaled to the render target's size.

fixedsize

Don't scale the target texture, and render to its default size.

What size to render the target texture. Sizes are based on the Window the render is occuring in.

SDLJoystickType

Enumerator

Unknown
Controller
Wheel
Stick
Stick
Pad
Guitar
Kit
Pad
Throttle

The type of device connected.

SDLPowerEnum

Enumerator

Unknown
Empty

ShapeBaseImage is not loaded.

Low
Medium
Full
Wired
Max

An enumeration of battery levels of a joystick.

SFXChannel

Enumerator

Volume

Channel controls volume level of attached sound sources.

see:

SFXDescription::volume

Pitch

Channel controls pitch of attached sound sources.

see:

SFXDescription::pitch

Priority

Channel controls virtualizaton priority level of attached sound sources.

see:

SFXDescription::priority

PositionX

Channel controls X coordinate of 3D sound position of attached sources.

PositionY

Channel controls Y coordinate of 3D sound position of attached sources.

PositionZ

Channel controls Z coordinate of 3D sound position of attached sources.

RotationX

Channel controls X rotation (in degrees) of 3D sound orientation of attached sources.

RotationY

Channel controls Y rotation (in degrees) of 3D sound orientation of attached sources.

RotationZ

Channel controls Z rotation (in degrees) of 3D sound orientation of attached sources.

VelocityX

Channel controls X coordinate of 3D sound velocity vector of attached sources.

VelocityY

Channel controls Y coordinate of 3D sound velocity vector of attached sources.

VelocityZ

Channel controls Z coordinate of 3D sound velocity vector of attached sources.

ReferenceDistance

Channel controls reference distance of 3D sound of attached sources.

see:

SFXDescription::referenceDistance

MaxDistance

Channel controls max volume attenuation distance of 3D sound of attached sources.

see:

SFXDescription::maxDistance

ConeInsideAngle

Channel controls angle (in degrees) of 3D sound inner volume cone of attached sources.

see:

SFXDescription::coneInsideAngle

ConeOutsideAngle

Channel controls angle (in degrees) of 3D sound outer volume cone of attached sources.

see:

SFXDescription::coneOutsideAngle

ConeOutsideVolume

Channel controls volume outside of 3D sound outer cone of attached sources.

see:

SFXDescription::coneOutsideVolume

Cursor

Channel controls playback cursor of attached sound sources.

note:

Be aware that different types of sound sources interpret play cursor positions differently or do not actually have play cursors (these sources will ignore the channel).

Status

Channel controls playback status of attached sound sources.

The channel's value is rounded down to the nearest integer and interpreted in the following way:

  • 1: Play

  • 2: Stop

  • 3: Pause

User0

Channel available for custom use. By default ignored by sources.

note:

For FMOD Designer event sources (SFXFMODEventSource), this channel is used for event parameters defined in FMOD Designer and should not be used otherwise.

see:

SFXSource::onParameterValueChange

User1

Channel available for custom use. By default ignored by sources.

see:

SFXSource::onParameterValueChange

User2

Channel available for custom use. By default ignored by sources.

see:

SFXSource::onParameterValueChange

User3

Channel available for custom use. By default ignored by sources.

see:

SFXSource::onParameterValueChange

Channels are individual properties of sound sources that may be animated over time.

see:

SFXParameter

SFX_interactive

SFXDistanceModel

Enumerator

Linear

Marker will have no smoothing effect.

Volume attenuates linearly from the references distance onwards to max distance where it reaches zero.

Logarithmic

Volume attenuates logarithmically starting from the reference distance and halving every reference distance step from there on. Attenuation stops at max distance but volume won't reach zero.

Exponential

Volume attenuates exponentially starting from the reference distance and attenuating every reference distance step by the rolloff factor. Attenuation stops at max distance but volume won't reach zero.

Type of volume distance attenuation curve.

The distance model determines the falloff curve applied to the volume of 3D sounds over distance.

Volume Attenuation

SFX_3d

SFXPlayListLoopMode

Enumerator

All

Loop over all slots, i.e. jump from last to first slot after all slots have played.

Single

Loop infinitely over the current slot. Only useful in combination with either states or manual playlist control.

Playlist behavior when description is set to loop.

see:

SFXDescription::isLooping

see:

SFXPlayList::loopMode

SFXPlayListRandomMode

Enumerator

NotRandom

Play slots in sequential order. No randomization.

StrictRandom

Play a strictly random selection of slots.

In this mode, a set of numSlotsToPlay random numbers between 0 and numSlotsToPlay-1 (inclusive), i.e. in the range of valid slot indices, is generated and playlist slots are played back in the order of this list. This allows the same slot to occur multiple times in a list and, consequentially, allows for other slots to not appear at all in a given slot ordering.

OrderedRandom

Play all slots in the list in a random order.

In this mode, the

numSlotsToPlay
slots from the list with valid tracks assigned are put into a random order and played. This guarantees that each slots is played exactly once albeit at a random position in the total ordering.

Randomization pattern to apply to playlist slot playback order.

see:

SFXPlayList::random

SFXPlayListReplayMode

Enumerator

IgnorePlaying

Ignore any sources that may already be playing on the slot and just create a new source.

RestartPlaying

Restart all sources that was last created for the slot.

KeepPlaying

Keep playing the current source(s) as if the source started last on the slot was created in this cycle. For this, the sources associated with the slot are brought to the top of the play stack.

StartNew

Stop all sources currently playing on the slot and then create a new source.

SkipIfPlaying

If there are sources already playing on the slot, skip the play stage.

Behavior when hitting the play stage of a slot that is still playing from a previous cycle.

see:

SFXPlayList::replay

SFXPlayListStateMode

Enumerator

StopWhenDeactivated

Stop the sources playing on the slot when a state changes to a setting that is incompatible with the slot's state setting.

PauseWhenDeactivated

Pause all sources playing on the slot when a state changes to a setting that is incompatible with the slot's state setting.

When the slot's state is reactivated again, the sources will resume playback.

IgnoreWhenDeactivated

Ignore when a state changes to a setting incompatible with the slot's state setting and just keep playing sources attached to the slot.

Reaction behavior when a state is changed incompatibly on a slot that has already started playing.

see:

SFXPlayList::stateMode

SFXPlayListTransitionMode

Enumerator

None

Simple point sampled filtering. This is the fastest and lowest quality mode.

No transition. Immediately move on to processing the slot or immediately move on to the next slot.

Allow both childs to resize (default).

Disable blending for this material.

No mesh data.

Wait

Wait for the sound source spawned last by this playlist to finish playing. Then proceed.

WaitAll

Wait for all sound sources currently spawned by the playlist to finish playing. Then proceed.

Stop

Stops the spin sequence at its current position.

Stop the sound source spawned last by this playlist. Then proceed.

StopAll

Stop all sound sources spawned by the playlist. Then proceed.

Playlist behavior when transitioning in and out of invididual slots.

Transition behaviors apply when the playback controller starts processing a playlist slot and when it ends processing a slot. Using transition behaviors, playback can be synchronized.

see:

SFXPlayList::transitionIn

see:

SFXPlayList::transitionOut

SFXStatus

Enumerator

Playing

The source is currently playing.

Stopped

Playback of the source is stopped. When transitioning to Playing state, playback will start at the beginning of the source.

Paused

Playback of the source is paused. Resuming playback will play from the current playback position.

Playback status of sound source.

ShadowFilterMode

Enumerator

None

Simple point sampled filtering. This is the fastest and lowest quality mode.

No transition. Immediately move on to processing the slot or immediately move on to the next slot.

Allow both childs to resize (default).

Disable blending for this material.

No mesh data.

SoftShadow

A variable tap rotated poisson disk soft shadow filter. It performs 4 taps to classify the point as in shadow, out of shadow, or along a shadow edge. Samples on the edge get an additional 8 taps to soften them.

SoftShadowHighQuality

A 12 tap rotated poisson disk soft shadow filter. It performs all the taps for every point without any early rejection.

The shadow filtering modes for Advanced Lighting shadows.

ShadowType

Enumerator

Spot
PSSM
DualParaboloidSinglePass
DualParaboloid
CubeMap 
ShapeBaseImageLightType

Enumerator

NoLight

No light is attached.

The item has no light attached.

ConstantLight

A constant emitting light is attached.

The item has a constantly emitting light attached.

SpotLight

A spotlight is attached.

PulsingLight

A pusling light is attached.

The item has a pulsing light attached.

WeaponFireLight

Light emits when the weapon is fired, then dissipates.

The type of light to attach to this ShapeBaseImage.

ShapeBaseImageLoadedState

Enumerator

Ignore

Ignore all water surfaces.

Ignore the loaded state.

No changes to the spin sequence.

Loaded

ShapeBaseImage is loaded.

Empty

ShapeBaseImage is not loaded.

The loaded state of this ShapeBaseImage.

ShapeBaseImageRecoilState

Enumerator

NoRecoil

No recoil occurs.

LightRecoil

A light recoil occurs.

MediumRecoil

A medium recoil occurs.

HeavyRecoil

A heavy recoil occurs.

What kind of recoil this ShapeBaseImage should emit when fired.

ShapeBaseImageSpinState

Enumerator

Ignore

Ignore all water surfaces.

Ignore the loaded state.

No changes to the spin sequence.

Stop

Stops the spin sequence at its current position.

Stop the sound source spawned last by this playlist. Then proceed.

SpinUp

Increase spin sequence timeScale from 0 (on state entry) to 1 (after stateTimeoutValue seconds).

SpinDown

Decrease spin sequence timeScale from 1 (on state entry) to 0 (after stateTimeoutValue seconds).

FullSpeed

Resume the spin sequence playback at its current position with timeScale = 1.

How the spin animation should be played.

TSMeshType

Enumerator

None

Simple point sampled filtering. This is the fastest and lowest quality mode.

No transition. Immediately move on to processing the slot or immediately move on to the next slot.

Allow both childs to resize (default).

Disable blending for this material.

No mesh data.

Bounds

Bounding box of the shape.

Mesh

Specifically desingated "collision" meshes.

Rendered mesh polygons.

Mesh

Specifically desingated "collision" meshes.

Rendered mesh polygons.

Type of mesh data available in a shape.

TSShapeConstructorAnimType

Enumerator

Frames
Seconds
Milliseconds 
TSShapeConstructorLodType

Enumerator

DetectDTS
SingleSize
TrailingNumber 
TSShapeConstructorUpAxis

Enumerator

X_AXIS
Y_AXIS
Z_AXIS
DEFAULT

Axis to use for upwards direction when importing from Collada.

TurretShapeFireLinkType

Enumerator

FireTogether

All weapons fire under trigger 0.

GroupedFire

Weapon mounts 0,2 fire under trigger 0, mounts 1,3 fire under trigger 1.

IndividualFire

Each weapon mount fires under its own trigger 0-3.

How the weapons are linked to triggers for this TurretShape.

VActionToggle

Enumerator

ON
OFF 
VDataTableDataType

Enumerator

EXPRESSION
STATIC
VARIABLE 
VPathEditorMode

Enumerator

GIZMO
ADDNODE
DELETENODE 
VPathNodeOrientationType

Enumerator

FREE
TOPOINT 
VPathObjectOrientationType

Enumerator

FREE
INTERPOLATE
TOPATH
TOOBJECT
TOPOINT 
VPathType

Enumerator

BEZIER
LINEAR 
VScriptEventCommandType

Enumerator

EXPRESSION
METHOD

Public Variables

bool $_forceAllMainThread

Force all work items to execute on main thread. turns this into a single-threaded system. Primarily useful to find whether malfunctions are caused by parallel execution or not.

float $cameraFov

The camera's Field of View.

int $frameSkip

Sets the number of frames to skip while rendering the scene.

string $instantGroup

The group that objects will be added to when they are created.

float $mvBackwardAction

Backwards movement speed for the active player.

bool $mvDeviceIsKeyboardMouse

Boolean state for it the system is using a keyboard and mouse or not.

float $mvDownAction

Downwards movement speed for the active player.

float $mvForwardAction

Forwards movement speed for the active player.

bool $mvFreeLook

Boolean state for if freelook is active or not.

float $mvLeftAction

Left movement speed for the active player.

float $mvPitch

Current pitch value, typically applied through input devices, such as a mouse.

float $mvPitchDownSpeed

Downwards pitch speed.

float $mvPitchUpSpeed

Upwards pitch speed.

float $mvRightAction

Right movement speed for the active player.

float $mvRoll

Current roll value, typically applied through input devices, such as a mouse.

float $mvRollLeftSpeed

Left roll speed.

float $mvRollRightSpeed

Right roll speed.

int $mvTriggerCount0

Used to determine the trigger counts of buttons. Namely used for input actions such as jumping and weapons firing.

int $mvTriggerCount1

Used to determine the trigger counts of buttons. Namely used for input actions such as jumping and weapons firing.

int $mvTriggerCount2

Used to determine the trigger counts of buttons. Namely used for input actions such as jumping and weapons firing.

int $mvTriggerCount3

Used to determine the trigger counts of buttons. Namely used for input actions such as jumping and weapons firing.

int $mvTriggerCount4

Used to determine the trigger counts of buttons. Namely used for input actions such as jumping and weapons firing.

int $mvTriggerCount5

Used to determine the trigger counts of buttons. Namely used for input actions such as jumping and weapons firing.

float $mvUpAction

Upwards movement speed for the active player.

float $mvXAxis_L

Left thumbstick X axis position on a dual-analog gamepad.

float $mvXAxis_R

Right thumbstick X axis position on a dual-analog gamepad.

float $mvYaw

Current yaw value, typically applied through input devices, such as a mouse.

float $mvYawLeftSpeed

Left Yaw speed.

float $mvYawRightSpeed

Right Yaw speed.

float $mvYAxis_L

Left thumbstick Y axis position on a dual-analog gamepad.

float $mvYAxis_R

Right thumbstick Y axis position on a dual-analog gamepad.

GuiControl $ThisControl

The control for which a command is currently being evaluated. Only set during 'command' and altCommand callbacks to the control for which the command or altCommand is invoked.

int $timeAdvance

The speed at which system processing time advances.

float $timeScale

Animation time scale.

void addCaseSensitiveStrings

[string1, string2, ...]Adds case sensitive strings to the StringTable.

void restartInstance

restartInstance()

int schedule

schedule(time, refobject|0, command, )

Public Functions

activateDirectInput()

Activates DirectInput.

Also activates any connected joysticks.

activatePackage(String packageName)

Activates an existing package.

The activation occurs by updating the namespace linkage of existing functions and methods. If the package is already activated the function does nothing.

addBadWord(string badWord)

Add a string to the bad word filter.

The bad word filter is a table containing words which will not be displayed in chat windows. Instead, a designated replacement string will be displayed. There are already a number of bad words automatically defined.

Parameters:

badWord

Exact text of the word to restrict.

return:

True if word was successfully added, false if the word or a subset of it already exists in the table

see:

filterString()

// In this game, "Foobar" is banned
%badWord = "Foobar";

// Returns true, word was successfully added
addBadWord(%badWord);

// Returns false, word has already been added
addBadWord("Foobar");


addGlobalShaderMacro(string name, string value)

Adds a global shader macro which will be merged with the script defined macros on every shader. The macro will replace the value of an existing macro of the same name. For the new macro to take effect all the shaders in the system need to be reloaded.

see:

resetLightManager, removeGlobalShaderMacro

addMaterialMapping(string texName, string matName)

Maps the given texture to the given material.

Generates a console warning before overwriting.

Material maps are used by terrain and interiors for triggering effects when an object moves onto a terrain block or interior surface using the associated texture.

AddRotation(RotationF a, RotationF b)

Adds two rotations together.

Parameters:

a

Rotation one.

b

Rotation two.

return:

v sum of both rotations.

addTaggedString(string str)

Use the addTaggedString function to tag a new string and add it to the NetStringTable.

Parameters:

str

The string to be tagged and placed in the NetStringTable. Tagging ignores case, so tagging the same string (excluding case differences) will be ignored as a duplicated tag.

return:

Returns a string( containing a numeric value) equivalent to the string ID for the newly tagged string

see:

syntaxDataTypes under Tagged Strings

see:

removeTaggedString()

see:

getTaggedString()

afxEndMissionNotify()

...

afxGetEngine()

...

afxGetVersion()

...

aiAddPlayer(string name, string ns)

'playerName'[, 'AIClassType'] );

aiConnect(... )

Creates a new AIConnection, and passes arguments to its onConnect script callback.

return:

The newly created AIConnection

see:

GameConnection for parameter information

allowConnections(bool allow)

Sets whether or not the global NetInterface allows connections from remote hosts.

allowConnections(bool allow)

Parameters:

allow

Set to true to allow remote connections.

Assert(bool condition, string message)

Fatal Script Assertion.

backtrace()

Prints the scripting call stack to the console log.

Used to trace functions called from within functions. Can help discover what functions were called (and not yet exited) before the current point in scripts.

beginSampling(string location, string backend)

Takes a string informing the backend where to store sample data and optionally a name of the specific logging backend to use. The default is the CSV backend. In most cases, the logging store will be a file name.

beginSampling( "mysamples.csv" );


buildTaggedString(string format, ... )

Build a string using the specified tagged string format.

This function takes an already tagged string (passed in as a tagged string ID) and one or more additional strings. If the tagged string contains argument tags that range from %%1 through %%9, then each additional string will be substituted into the tagged string. The final (non-tagged) combined string will be returned. The maximum length of the tagged string plus any inserted additional strings is 511 characters.

Parameters:

format

A tagged string ID that contains zero or more argument tags, in the form of %%1 through %%9.

...

A variable number of arguments that are insterted into the tagged string based on the argument tags within the format string.

return:

An ordinary string that is a combination of the original tagged string with any additional strings passed in inserted in place of each argument tag.

// Create a tagged string with argument tags
%taggedStringID = addTaggedString("Welcome %1 to the game!");

// Some point later, combine the tagged string with some other string
%string = buildTaggedString(%taggedStringID, %playerName);
echo(%string);

see:

syntaxDataTypes under Tagged Strings

see:

addTaggedString()

see:

getTaggedString()

calcExplosionCoverage(Point3F pos, int id, uint covMask)

Calculates how much an explosion effects a specific object.

Use this to determine how much damage to apply to objects based on their distance from the explosion's center point, and whether the explosion is blocked by other objects.

Parameters:

pos

Center position of the explosion.

id

Id of the object of which to check coverage.

covMask

Mask of object types that may block the explosion.

return:

Coverage value from 0 (not affected by the explosion) to 1 (fully affected)

// Get the position of the explosion.
%position = %explosion.getPosition();

// Set a list of TypeMasks (defined in gameFunctioncs.cpp), seperated by the | character.
%TypeMasks = $TypeMasks::StaticObjectType | $TypeMasks::ItemObjectType

// Acquire the damage value from 0.0f - 1.0f.
%coverage = calcExplosionCoverage( %position, %sceneObject, %TypeMasks );

// Apply damage to object
%sceneObject.applyDamage( %coverage * 20 );


call(string functionName, string args...)

Apply the given arguments to the specified global function and return the result of the call.

Parameters:

functionName

The name of the function to call. This function must be in the global namespace, i.e. you cannot call a function in a namespace through call. Use eval() for that.

return:

The result of the function call.

function myFunction( %arg )
{
  return ( %arg SPC "World!" );
}

echo( call( "myFunction", "Hello" ) ); // Prints "Hello World!" to the console.


cancel(int eventId)

cancel(eventId)

cancelAll(string objectId)

cancelAll(objectId): cancel pending events on the specified object. Events will be automatically cancelled if object is deleted.

cancelServerQuery()

cancelServerQuery();

castSpell(afxMagicSpellData datablock, ShapeBase caster, SceneObject target, SimObject extra)

Instantiates the magic spell defined by datablock and cast by caster.

cleanupTexturePool()

Release the unused pooled textures in texture manager freeing up video memory.

clearClientPaths()

UNDOCUMENTED!

clearGFXResourceFlags()

Clears the flagged state on all allocated GFX resources. See flagCurrentGFXResources for usage details.

see:

flagCurrentGFXResources, listGFXResources, describeGFXResources

clearServerPaths()

UNDOCUMENTED!

closeNetPort()

Closes the current network port.

closeSplashWindow()

Close our startup splash window.

note:

This is currently only implemented on Windows.

cls()

Clears the console output.

collapseEscape(string text)

Replace all escape sequences in text with their respective character codes.

This function replaces all escape sequences (\n, \t, etc) in the given string with the respective characters they represent.

The primary use of this function is for converting strings from their literal form into their compiled/translated form, as is normally done by the TorqueScript compiler.

Parameters:

text

A string.

return:

A duplicate of text with all escape sequences replaced by their respective character codes.

// Print:
//
//    str
//    ing
//
// to the console.  Note how the backslash in the string must be escaped here
// in order to prevent the TorqueScript compiler from collapsing the escape
// sequence in the resulting string.
echo( collapseEscape( "str\ning" ) );

see:

expandEscape

ColorFloatToInt(LinearColorF color)

Convert from a float color to an integer color (0.0 - 1.0 to 0 to 255).

Parameters:

color

Float color value to be converted in the form "R G B A", where R is red, G is green, B is blue, and A is alpha.

return:

Converted color value (0 - 255)

ColorFloatToInt( "0 0 1 0.5" ) // Returns "0 0 255 128".


ColorHEXToRGB(string hex)

Convert from a hex color value to an integer RGB (red, green, blue) color (00 - FF to 0 to 255).

Parameters:

hex

Hex color value (#000000 - #FFFFFF) to be converted to an RGB (red, green, blue) value.

return:

Integer color value to be converted in the form "R G B A", where R is red, G is green, B is blue, and A is alpha. Alpha isn't handled/converted so only pay attention to the RGB value

ColorHEXToRGB( "#0000FF" ) // Returns "0 0 255 0".


ColorHSBToRGB(Point3I hsb)

Convert from a HSB (hue, saturation, brightness) to an integer RGB (red, green, blue) color. HSB is also know as HSL or HSV as well, with the last letter standing for lightness or value.

Parameters:

hsb

HSB (hue, saturation, brightness) value to be converted.

return:

Integer color value to be converted in the form "R G B A", where R is red, G is green, B is blue, and A is alpha. Alpha isn't handled/converted so only pay attention to the RGB value

ColorHSBToRGB( "240 100 100" ) // Returns "0 0 255 0".


ColorIntToFloat(ColorI color)

Convert from a integer color to an float color (0 to 255 to 0.0 - 1.0).

Parameters:

color

Integer color value to be converted in the form "R G B A", where R is red, G is green, B is blue, and A is alpha.

return:

Converted color value (0.0 - 1.0)

ColorIntToFloat( "0 0 255 128" ) // Returns "0 0 1 0.5".


ColorRGBToHEX(ColorI color)

Convert from a integer RGB (red, green, blue) color to hex color value (0 to 255 to 00 - FF).

Parameters:

color

Integer color value to be converted in the form "R G B A", where R is red, G is green, B is blue, and A is alpha. It excepts an alpha, but keep in mind this will not be converted.

return:

Hex color value (#000000 - #FFFFFF), alpha isn't handled/converted so it is only the RGB value

ColorRBGToHEX( "0 0 255 128" ) // Returns "#0000FF".


ColorRGBToHSB(ColorI color)

Convert from a integer RGB (red, green, blue) color to HSB (hue, saturation, brightness). HSB is also know as HSL or HSV as well, with the last letter standing for lightness or value.

Parameters:

color

Integer color value to be converted in the form "R G B A", where R is red, G is green, B is blue, and A is alpha. It excepts an alpha, but keep in mind this will not be converted.

return:

HSB color value, alpha isn't handled/converted so it is only the RGB value

ColorRBGToHSB( "0 0 255 128" ) // Returns "240 100 100".


ColorScale(LinearColorF color, float scalar)

Returns color scaled by scalar (color*scalar).

Parameters:

color

The color to be scaled.

scalar

The amount to scale the color.

commandToClient(NetConnection client, string func, ... )

Send a command from the server to the client.

Parameters:

client

The numeric ID of a client GameConnection

func

Name of the client function being called

...

Various parameters being passed to client command

// Set up the client command.  Needs to be executed on the client, such as
// within scripts/client/client.cs
// Update the Ammo Counter with current ammo, if not any then hide the counter.
function clientCmdSetAmmoAmountHud(%amount)
{
   if (!%amount)
     AmmoAmount.setVisible(false);
   else
   {
     AmmoAmount.setVisible(true);
     AmmoAmount.setText("Ammo: "@%amount);
   }
}

// Call it from a server function.  Needs to be executed on the server, 
//such as within scripts/server/game.cs
function GameConnection::setAmmoAmountHud(%client, %amount)
{
   commandToClient(%client, 'SetAmmoAmountHud', %amount);
}


commandToServer(string func, ... )

Send a command to the server.

Parameters:

func

Name of the server command being called

...

Various parameters being passed to server command

// Create a standard function.  Needs to be executed on the client, such 
// as within scripts/client/default.bind.cs
function toggleCamera(%val)
{
   // If key was down, call a server command named 'ToggleCamera'
   if (%val)
      commandToServer('ToggleCamera');
}

// Server command being called from above.  Needs to be executed on the 
// server, such as within scripts/server/commands.cs
function serverCmdToggleCamera(%client)
{
   if (%client.getControlObject() == %client.player)
   {
     %client.camera.setVelocity("0 0 0");
     %control = %client.camera;
   }
   else
   {
     %client.player.setVelocity("0 0 0");
     %control = %client.player;
  }
   %client.setControlObject(%control);
   clientCmdSyncEditorGui();
}


compile(string fileName, bool overrideNoDSO)

Compile a file to bytecode.

This function will read the TorqueScript code in the specified file, compile it to internal bytecode, and, if DSO generation is enabled or overrideNoDDSO is true, will store the compiled code in a .dso file in the current DSO path mirrorring the path of fileName.

Parameters:

fileName

Path to the file to compile to bytecode.

overrideNoDSO

If true, force generation of DSOs even if the engine is compiled to not generate write compiled code to DSO files.

return:

True if the file was successfully compiled, false if not.

note:

The definitions contained in the given file will not be made available and no code will actually be executed. Use exec() for that.

see:

getDSOPath

see:

exec

CompileLanguage(string inputFile, bool createMap)

Compiles a LSO language file. if createIndex is true, will also create languageMap.cs with the global variables for each string index. The input file must follow this example layout: TXT_HELLO_WORLD = Hello world in english!

containerBoxEmpty(uint mask, Point3F center, float xRadius, float yRadius, float zRadius, bool useClientContainer)

See if any objects of the given types are present in box of given extent.

note:

Extent parameter is last since only one radius is often needed. If one radius is provided, the yRadius and zRadius are assumed to be the same. Unfortunately, if you need to use the client container, you'll need to set all of the radius parameters. Fortunately, this function is mostly used on the server.

Parameters:
mask

Indicates the type of objects we are checking against.

center

Center of box.

xRadius

Search radius in the x-axis. See note above.

yRadius

Search radius in the y-axis. See note above.

zRadius

Search radius in the z-axis. See note above.

useClientContainer

Optionally indicates the search should be within the client container.

return:

true if the box is empty, false if any object is found.

containerFindFirst(uint typeMask, Point3F origin, Point3F size)

Find objects matching the bitmask type within a box centered at point, with extents x, y, z.

return:

The first object found, or an empty string if nothing was found. Thereafter, you can get more results using containerFindNext().

see:

containerFindNext

containerFindNext()

Get more results from a previous call to containerFindFirst().

note:

You must call containerFindFirst() to begin the search.

return:

The next object found, or an empty string if nothing else was found.

see:

containerFindFirst()

containerRayCast(Point3F start, Point3F end, uint mask, SceneObject pExempt, bool useClientContainer)

Cast a ray from start to end, checking for collision against items matching mask.

If pExempt is specified, then it is temporarily excluded from collision checks (For instance, you might want to exclude the player if said player was firing a weapon.) Parameters:

start

An XYZ vector containing the tail position of the ray.

end

An XYZ vector containing the head position of the ray

mask

A bitmask corresponding to the type of objects to check for

pExempt

An optional ID for a single object that ignored for this raycast

useClientContainer

Optionally indicates the search should be within the client container.

return:

A string containing either null, if nothing was struck, or these fields:

  • The ID of the object that was struck.

  • The x, y, z position that it was struck.

  • The x, y, z of the normal of the face that was struck.

  • The distance between the start point and the position we hit.

containerSearchCurrDist(bool useClientContainer)

Get distance of the center of the current item from the center of the current initContainerRadiusSearch.

Parameters:

useClientContainer

Optionally indicates the search should be within the client container.

return:

distance from the center of the current object to the center of the search

see:

containerSearchNext

containerSearchCurrRadiusDist(bool useClientContainer)

Get the distance of the closest point of the current item from the center of the current initContainerRadiusSearch.

Parameters:

useClientContainer

Optionally indicates the search should be within the client container.

return:

distance from the closest point of the current object to the center of the search

see:

containerSearchNext

containerSearchNext(bool useClientContainer)

Get next item from a search started with initContainerRadiusSearch() or initContainerTypeSearch().

Parameters:

useClientContainer

Optionally indicates the search should be within the client container.

return:

the next object found in the search, or null if no more

// print the names of all nearby ShapeBase derived objects
%position = %obj.getPosition;
%radius = 20;
%mask = $TypeMasks::ShapeBaseObjectType;
initContainerRadiusSearch( %position, %radius, %mask );
while ( (%targetObject = containerSearchNext()) != 0 )
{
   echo( "Found: " @ %targetObject.getName() );
}

see:

initContainerRadiusSearch()

see:

initContainerTypeSearch()

containsBadWords(string text)

Checks to see if text is a bad word.

The text is considered to be a bad word if it has been added to the bad word filter.

Parameters:

text

Text to scan for bad words

return:

True if the text has bad word(s), false if it is clean

see:

addBadWord()

see:

filterString()

// In this game, "Foobar" is banned
%badWord = "Foobar";

// Add a banned word to the bad word filter
addBadWord(%badWord);

// Create the base string, can come from anywhere like user chat
%userText = "Foobar";

// Create a string of random letters
%replacementChars = "knqwrtlzs";

// If the text contains a bad word, filter it before printing
// Otherwise print the original text
if(containsBadWords(%userText))
{
  // Filter the string
  %filteredText = filterString(%userText, %replacementChars);

  // Print filtered text
  echo(%filteredText);
}
else
  echo(%userText);


countBits(int v)

Count the number of bits that are set in the given 32 bit integer.

Parameters:

v

An integer value.

return:

The number of bits that are set in v.

createPath(string path)

Create the given directory or the path leading to the given filename.

If path ends in a trailing slash, then all components in the given path will be created as directories (if not already in place). If path, does not end in a trailing slash, then the last component of the path is taken to be a file name and only the directory components of the path will be created.

Parameters:

path

The path to create.

note:

Only present in a Tools build of Torque.

deactivateDirectInput()

Disables DirectInput.

Also deactivates any connected joysticks.

deactivatePackage(String packageName)

Deactivates a previously activated package.

The package is deactivated by removing its namespace linkages to any function or method. If there are any packages above this one in the stack they are deactivated as well. If the package is not on the stack this function does nothing.

debug()

Drops the engine into the native C++ debugger.

This function triggers a debug break and drops the process into the IDE's debugger. If the process is not running with a debugger attached it will generate a runtime error on most platforms.

note:

This function is not available in shipping builds.

debugDumpAllObjects()

Dumps all current EngineObject instances to the console.

note:

This function is only available in debug builds.

debugEnumInstances(string className, string functionName)

Call the given function for each instance of the given class.

Parameters:

className

Name of the class for which to enumerate instances.

functionName

Name of function to call and pass each instance of the given class.

note:

This function is only available in debug builds and primarily meant as an aid in debugging.

debugv(string variableName)

Logs the value of the given variable to the console.

Prints a string of the form " = " to the console.

Parameters:

variableName

Name of the local or global variable to print.

%var = 1;
debugv( "%var" ); // Prints "%var = 1"


decalManagerAddDecal(Point3F position, Point3F normal, float rot, float scale, DecalData decalData, bool isImmortal)

Adds a new decal to the decal manager.

Parameters:

position

World position for the decal.

normal

Decal normal vector (if the decal was a tire lying flat on a surface, this is the vector pointing in the direction of the axle).

rot

Angle (in radians) to rotate this decal around its normal vector.

scale

Scale factor applied to the decal.

decalData

DecalData datablock to use for the new decal.

isImmortal

Whether or not this decal is immortal. If immortal, it does not expire automatically and must be removed explicitly.

return:

Returns the ID of the new Decal object or -1 on failure.

// Specify the decal position
%position = "1.0 1.0 1.0";

// Specify the up vector
%normal = "0.0 0.0 1.0";

// Add the new decal.
%decalObj = decalManagerAddDecal( %position, %normal, 0.5, 0.35, ScorchBigDecal, false );


decalManagerClear()

Removes all decals currently loaded in the decal manager.

// Tell the decal manager to remove all existing decals.
decalManagerClear();


decalManagerDirty()

Returns whether the decal manager has unsaved modifications.

return:

True if the decal manager has unsaved modifications, false if everything has been saved.

// Ask the decal manager if it has unsaved modifications.
%hasUnsavedModifications = decalManagerDirty();


decalManagerEditDecal(int decalID, Point3F pos, Point3F normal, float rotAroundNormal, float decalScale)

Edit specified decal of the decal manager.

Parameters:

decalID

ID of the decal to edit.

pos

World position for the decal.

normal

Decal normal vector (if the decal was a tire lying flat on a surface, this is the vector pointing in the direction of the axle).

rotAroundNormal

Angle (in radians) to rotate this decal around its normal vector.

decalScale

Scale factor applied to the decal.

return:

Returns true if successful, false if decalID not found.

decalManagerLoad(string fileName)

Clears existing decals and replaces them with decals loaded from the specified file.

Parameters:

fileName

Filename to load the decals from.

return:

True if the decal manager was able to load the requested file, false if it could not.

// Set the filename to load the decals from.
%fileName = "./missionDecals.mis.decals";
// Inform the decal manager to load the decals from the entered filename.
decalManagerLoad( %fileName );


decalManagerRemoveDecal(int decalID)

Remove specified decal from the scene.

Parameters:

decalID

ID of the decal to remove.

return:

Returns true if successful, false if decal ID not found.

// Specify a decal ID to be removed
%decalID = 1;

// Tell the decal manager to remove the specified decal ID.
decalManagerRemoveDecal( %decalId )


decalManagerSave(String decalSaveFile)

Saves the decals for the active mission in the entered filename.

Parameters:

decalSaveFile

Filename to save the decals to.

// Set the filename to save the decals in. If no filename is set, then the
// decals will default to <activeMissionName>.mis.decals
%fileName = "./missionDecals.mis.decals";
// Inform the decal manager to save the decals for the active mission.
decalManagerSave( %fileName );


deleteDataBlocks()

Delete all the datablocks we've downloaded.

This is usually done in preparation of downloading a new set of datablocks, such as occurs on a mission change, but it's also good post-mission cleanup.

deleteVariables(string pattern)

Undefine all global variables matching the given name pattern.

Parameters:

pattern

A global variable name pattern. Must begin with '$'.

// Define a global variable in the "My" namespace.
$My::Variable = "value";

// Undefine all variable in the "My" namespace.
deleteVariables( "$My::*" );

see:

strIsMatchExpr

describeGFXResources(string resourceTypes, string filePath, bool unflaggedOnly)

Dumps a description of GFX resources to a file or the console.

Parameters:

resourceTypes

A space seperated list of resource types or an empty string for all resources.

filePath

A file to dump the list to or an empty string to write to the console.

unflaggedOnly

If true only unflagged resources are dumped. See flagCurrentGFXResources.

note:

The resource types can be one or more of the following:

  • texture

  • texture target

  • window target

  • vertex buffers

  • primitive buffers

  • fences

  • cubemaps

  • shaders

  • stateblocks

describeGFXStateBlocks(string filePath)

Dumps a description of all state blocks.

Parameters:

filePath

A file to dump the state blocks to or an empty string to write to the console.

detag(string str)

Returns the string from a tag string.

Should only be used within the context of a function that receives a tagged string, and is not meant to be used outside of this context. Use getTaggedString() to convert a tagged string ID back into a regular string at any time.

// From scripts/client/message. cs
function clientCmdChatMessage(%sender, %voice, %pitch, %msgString, %a1, %a2, %a3, %a4, %a5, %a6, %a7, %a8, %a9, %a10)
{
   onChatMessage(detag(%msgString), %voice, %pitch);
}

see:

syntaxDataTypes under Tagged Strings

see:

getTag()

see:

getTaggedString()

dispatchMessage(string queueName, string message, string data)

Dispatch a message to a queue.

Parameters:

queueName

Queue to dispatch the message to

message

Message to dispatch

data

Data for message

return:

True for success, false for failure

see:

dispatchMessageObject

dispatchMessageObject(string queueName, string message)

Dispatch a message object to a queue.

Parameters:

queueName

Queue to dispatch the message to

message

Message to dispatch

return:

true for success, false for failure

see:

dispatchMessage

displaySplashWindow(string path)

Display a startup splash window suitable for showing while the engine still starts up.

note:

This is currently only implemented on Windows.

Parameters:
path

relative path to splash screen image to display.

return:

True if the splash window could be successfully initialized.

DNetSetLogging(bool enabled)

Enables logging of the connection protocols.

When enabled a lot of network debugging information is sent to the console. Parameters:

enabled

True to enable, false to disable

dumpActivePostFX()

UNDOCUMENTED!

dumpAlloc(int allocNum)

Dumps information about the given allocated memory block.

Parameters:

allocNum

Memory block to dump information about.

note:

Available in debug builds only. In torqueConfig.h, TORQUE_DISABLE_MEMORY_MANAGER must be undefined to use this function.

dumpConsoleClasses(bool dumpScript, bool dumpEngine)

Dumps all declared console classes to the console.

Parameters:

dumpScript

Optional parameter specifying whether or not classes defined in script should be dumped.

dumpEngine

Optional parameter specifying whether or not classes defined in the engine should be dumped.

dumpConsoleFunctions(bool dumpScript, bool dumpEngine)

Dumps all declared console functions to the console.

Parameters:

dumpScript

Optional parameter specifying whether or not functions defined in script should be dumped.

dumpEngine

Optional parameter specitying whether or not functions defined in the engine should be dumped.

dumpEngineDocs(string outputFile)

Dumps the engine scripting documentation to the specified file overwriting any existing content.

Parameters:

outputFile

The relative or absolute output file path and name.

return:

Returns true if successful.

dumpFontCacheStatus()

Dumps to the console a full description of all cached fonts, along with info on the codepoints each contains.

dumpMaterialInstances()

Dumps a formatted list of currently allocated material instances to the console.

dumpMemSnapshot(string fileName)

Dumps a snapshot of current memory to a file.

The total memory used will also be output to the console. This function will attempt to create the file if it does not already exist. Parameters:

fileName

Name and path of file to save profiling stats to. Must use forward slashes (/)

dumpMemSnapshot( "C:/Torque/ProfilerLogs/profilerlog1.txt" );

note:

Available in debug builds only. In torqueConfig.h, TORQUE_DISABLE_MEMORY_MANAGER must be undefined to use this function.

dumpNetStats()

Dumps network statistics for each class to the console.

The returned avg, min and max values are in bits sent per update. The num value is the total number of events collected.

note:

This method only works when TORQUE_NET_STATS is defined in torqueConfig.h.

dumpNetStringTable()

Dump the current contents of the networked string table to the console.

The results are returned in three columns. The first column is the network string ID. The second column is the string itself. The third column is the reference count to the network string.

note:

This function is available only in debug builds.

dumpProcessList()

Dumps all ProcessObjects in ServerProcessList and ClientProcessList to the console.

dumpRandomNormalMap()

Creates a 64x64 normal map texture filled with noise. The texture is saved to randNormTex.png in the location of the game executable.

dumpStringMemStats()

Dumps information about String memory usage.

dumpTextureObjects()

Dumps a list of all active texture objects to the console.

note:

This function is only available in debug builds.

dumpUnflaggedAllocs(string fileName)

Dumps all unflagged memory allocations.

Dumps all memory allocations that were made after a call to flagCurrentAllocs(). Helpful when used with flagCurrentAllocs() for detecting memory leaks and analyzing general memory usage.

Parameters:

fileName

Optional file path and location to dump all memory allocations not flagged by flagCurrentAllocs(). If left blank, data will be dumped to the console.

dumpMemSnapshot(); // dumps info to console
dumpMemSnapshot( "C:/Torque/profilerlog1.txt" ); // dumps info to file

note:

Available in debug builds only. In torqueConfig.h, TORQUE_DISABLE_MEMORY_MANAGER must be undefined to use this function.

duplicateCachedFont(string oldFontName, int oldFontSize, string newFontName)

Copy the specified old font to a new name. The new copy will not have a platform font backing it, and so will never have characters added to it. But this is useful for making copies of fonts to add postprocessing effects to via exportCachedFont.

Parameters:

oldFontName

The name of the font face to copy.

oldFontSize

The size of the font to copy.

newFontName

The name of the new font face.

echo(string message...)

Logs a message to the console.

Concatenates all given arguments to a single string and prints the string to the console. A newline is added automatically after the text.

Parameters:

message

Any number of string arguments.

echoThru(string passthru, string text...)

Like echo(), but first argument is returned.

enableSamples(string pattern, bool state)

Enable sampling for all keys that match the given name pattern. Slashes are treated as separators.

enableWinConsole(bool _enable)

enableWinConsole(bool);

endsWith(string str, string suffix, bool caseSensitive)

Test whether the given string ends with the given suffix.

Parameters:

str

The string to test.

suffix

The potential suffix of str.

caseSensitive

If true, the comparison will be case-sensitive; if false, differences in casing will not be taken into account.

return:

True if the last characters in str match the complete contents of suffix; false otherwise.

startsWith( "TEST123", "123" ) // Returns true.

see:

startsWith

error(string message...)

Logs an error message to the console.

Concatenates all given arguments to a single string and prints the string to the console as an error message (in the in-game console, these will show up using a red font by default). A newline is added automatically after the text.

Parameters:

message

Any number of string arguments.

errorThru(string passthru, string text...)

Like error(), but first argument is returned.

eval(string consoleString)

eval(consoleString)

excludeOtherInstance(string appIdentifer)

Used to exclude/prevent all other instances using the same identifier specified.

note:

Not used on OSX, Xbox, or in Win debug builds

Parameters:
appIdentifier

Name of the app set up for exclusive use.

return:

False if another app is running that specified the same appIdentifier

exec(string fileName, bool noCalls, bool journalScript)

Execute the given script file.

Parameters:

fileName

Path to the file to execute

noCalls

Deprecated

journalScript

Deprecated

return:

True if the script was successfully executed, false if not.

// Execute the init.cs script file found in the same directory as the current script file.
exec( "./init.cs" );

see:

compile

see:

eval

execPrefs(string relativeFileName, bool noCalls, bool journalScript)

Manually execute a special script file that contains game or editor preferences.

Parameters:

relativeFileName

Name and path to file from project folder

noCalls

Deprecated

journalScript

Deprecated

return:

True if script was successfully executed

note:

Appears to be useless in Torque 3D, should be deprecated

expandEscape(string text)

Replace all characters in text that need to be escaped for the string to be a valid string literal with their respective escape sequences.

All characters in text that cannot appear in a string literal will be replaced by an escape sequence (\n, \t, etc).

The primary use of this function is for converting strings suitable for being passed as string literals to the TorqueScript compiler.

Parameters:

text

A string

return:

A duplicate of the text parameter with all unescaped characters that cannot appear in string literals replaced by their respective escape sequences.

@tsxample expandEscape( "str" NL "ing" ) // Returns "str\ning". @endtsxample

see:

collapseEscape

expandFilename(string filename)

Grabs the full path of a specified file.

Parameters:

filename

Name of the local file to locate

return:

String containing the full filepath on disk

expandOldFilename(string filename)

Retrofits a filepath that uses old Torque style.

return:

String containing filepath with new formatting

export(string pattern, string filename, bool append)

Write out the definitions of all global variables matching the given name pattern.

If fileName is not "", the variable definitions are written to the specified file. Otherwise the definitions will be printed to the console.

The output are valid TorqueScript statements that can be executed to restore the global variable values.

Parameters:

pattern

A global variable name pattern. Must begin with '$'.

filename

Path of the file to which to write the definitions or "" to write the definitions to the console.

append

If true and fileName is not "", then the definitions are appended to the specified file. Otherwise existing contents of the file (if any) will be overwritten.

// Write out all preference variables to a prefs.cs file.
export( "$prefs::*", "prefs.cs" );


exportCachedFont(string faceName, int fontSize, string fileName, int padding, int kerning)

Export specified font to the specified filename as a PNG. The image can then be processed in Photoshop or another tool and reimported using importCachedFont. Characters in the font are exported as one long strip.

Parameters:

faceName

The name of the font face.

fontSize

The size of the font in pixels.

fileName

The file name and path for the output PNG.

padding

The padding between characters.

kerning

The kerning between characters.

exportEngineAPIToXML()

Create a XML document containing a dump of the entire exported engine API.

return:

A SimXMLDocument containing a dump of the engine's export information or NULL if the operation failed.

extractDatablockCacheCRC(string fileName)

UNDOCUMENTED!

fileBase(string fileName)

Get the base of a file name (removes extension and path)

Parameters:

fileName

Name and path of file to check

return:

String containing the file name, minus extension and path

fileCreatedTime(string fileName)

Returns a platform specific formatted string with the creation time for the file.

Parameters:

fileName

Name and path of file to check

return:

Formatted string (OS specific) containing created time, "9/3/2010 12:33:47 PM" for example

fileDelete(string path)

Delete a file from the hard drive.

Parameters:

path

Name and path of the file to delete

note:

THERE IS NO RECOVERY FROM THIS. Deleted file is gone for good.

return:

True if file was successfully deleted

fileExt(string fileName)

Get the extension of a file.

Parameters:

fileName

Name and path of file

return:

String containing the extension, such as ".exe" or ".cs"

fileModifiedTime(string fileName)

Returns a platform specific formatted string with the last modified time for the file.

Parameters:

fileName

Name and path of file to check

return:

Formatted string (OS specific) containing modified time, "9/3/2010 12:33:47 PM" for example

fileName(string fileName)

Get only the file name of a path and file name string (removes path)

Parameters:

fileName

Name and path of file to check

return:

String containing the file name, minus the path

filePath(string fileName)

Get the path of a file (removes name and extension)

Parameters:

fileName

Name and path of file to check

return:

String containing the path, minus name and extension

fileSize(string fileName)

Determines the size of a file on disk.

Parameters:

fileName

Name and path of the file to check

return:

Returns filesize in bytes, or -1 if no file

filterString(string baseString, string replacementChars)

Replaces the characters in a string with designated text.

Uses the bad word filter to determine which characters within the string will be replaced.

Parameters:

baseString

The original string to filter.

replacementChars

A string containing letters you wish to swap in the baseString.

return:

The new scrambled string

see:

addBadWord()

see:

containsBadWords()

// Create the base string, can come from anywhere
%baseString = "Foobar";

// Create a string of random letters
%replacementChars = "knqwrtlzs";

// Filter the string
%newString = filterString(%baseString, %replacementChars);

// Print the new string to console
echo(%newString);


findFirstFile(string pattern, bool recurse)

Returns the first file in the directory system matching the given pattern.

Use the corresponding findNextFile() to step through the results. If you're only interested in the number of files returned by the pattern match, use getFileCount().

This function differs from findFirstFileMultiExpr() in that it supports a single search pattern being passed in.

note:

You cannot run multiple simultaneous file system searches with these functions. Each call to findFirstFile() and findFirstFileMultiExpr() initiates a new search and renders a previous search invalid.

Parameters:
pattern

The path and file name pattern to match against.

recurse

If true, the search will exhaustively recurse into subdirectories of the given path and match the given filename pattern.

return:

The path of the first file matched by the search or an empty string if no matching file could be found.

// Execute all .cs files in a subdirectory and its subdirectories.
for( %file = findFirstFile( "subdirectory/*.cs" ); %file !$= ""; %file = findNextFile() )
   exec( %file );

see:

findNextFile()

see:

getFileCount()

see:

findFirstFileMultiExpr()

findFirstFileMultiExpr(string pattern, bool recurse)

Returns the first file in the directory system matching the given patterns.

Use the corresponding findNextFileMultiExpr() to step through the results. If you're only interested in the number of files returned by the pattern match, use getFileCountMultiExpr().

This function differs from findFirstFile() in that it supports multiple search patterns to be passed in.

note:

You cannot run multiple simultaneous file system searches with these functions. Each call to findFirstFile() and findFirstFileMultiExpr() initiates a new search and renders a previous search invalid.

Parameters:
pattern

The path and file name pattern to match against, such as *.cs. Separate multiple patterns with TABs. For example: "*.cs" TAB "*.dso"

recurse

If true, the search will exhaustively recurse into subdirectories of the given path and match the given filename patterns.

return:

String of the first matching file path, or an empty string if no matching files were found.

// Find all DTS or Collada models
%filePatterns = "*.dts" TAB "*.dae";
%fullPath = findFirstFileMultiExpr( %filePatterns );
while ( %fullPath !$= "" )
{
   echo( %fullPath );
   %fullPath = findNextFileMultiExpr( %filePatterns );
}

see:

findNextFileMultiExpr()

see:

getFileCountMultiExpr()

see:

findFirstFile()

findNextFile(string pattern)

Returns the next file matching a search begun in findFirstFile().

Parameters:

pattern

The path and file name pattern to match against. This is optional and may be left out as it is not used by the code. It is here for legacy reasons.

return:

The path of the next filename matched by the search or an empty string if no more files match.

// Execute all .cs files in a subdirectory and its subdirectories.
for( %file = findFirstFile( "subdirectory/*.cs" ); %file !$= ""; %file = findNextFile() )
   exec( %file );

see:

findFirstFile()

findNextFileMultiExpr(string pattern)

Returns the next file matching a search begun in findFirstFileMultiExpr().

Parameters:

pattern

The path and file name pattern to match against. This is optional and may be left out as it is not used by the code. It is here for legacy reasons.

return:

String of the next matching file path, or an empty string if no matching files were found.

// Find all DTS or Collada models
%filePatterns = "*.dts" TAB "*.dae";
%fullPath = findFirstFileMultiExpr( %filePatterns );
while ( %fullPath !$= "" )
{
   echo( %fullPath );
   %fullPath = findNextFileMultiExpr( %filePatterns );
}

see:

findFirstFileMultiExpr()

firstWord(string text)

Return the first word in text.

Parameters:

text

A list of words separated by newlines, spaces, and/or tabs.

return:

The word at index 0 in text or "" if text is empty.

note:

This is equal to @tsexample_nopar getWord( text, 0 )

see:

getWord

flagCurrentAllocs()

Flags all current memory allocations.

Flags all current memory allocations for exclusion in subsequent calls to dumpUnflaggedAllocs(). Helpful in detecting memory leaks and analyzing memory usage.

flagCurrentGFXResources()

Flags all currently allocated GFX resources. Used for resource allocation and leak tracking by flagging current resources then dumping a list of unflagged resources at some later point in execution.

see:

listGFXResources, clearGFXResourceFlags, describeGFXResources

flushTextureCache()

Releases all textures and resurrects the texture manager.

freeMemoryDump()

Dumps some useful statistics regarding free memory.

Dumps an analysis of 'free chunks' of memory. Does not print how much memory is free.

GenerateTamlSchema()

Generate a TAML schema file of all engine types.

The schema file is specified using the console variable '$pref::T2D::TAMLSchema'.

return:

Whether the schema file was writtent or not.

generateUUID()

Generate a new universally unique identifier (UUID).

return:

A newly generated UUID.

getActiveDDSFiles()

Returns the count of active DDSs files in memory.

getActiveLightManager()

Returns the active light manager name.

getAppVersionNumber()

Get the version of the application build, as a string.

getAppVersionString()

Get the version of the aplication build, as a human readable string.

getBestHDRFormat()

Returns the best texture format for storage of HDR data for the active device.

getBitmapInfo(string filename)

Returns image info in the following format: width TAB height TAB bytesPerPixel TAB format. It will return an empty string if the file is not found.

getBoxCenter(Box3F box)

Get the center point of an axis-aligned box.

Parameters:

b

A Box3F, in string format using "minExtentX minExtentY minExtentZ maxExtentX maxExtentY maxExtentZ"

return:

Center of the box.

getBuildString()

Get the type of build, "Debug" or "Release".

getCategoryOfClass(string className)

Returns the category of the given class.

Parameters:

className

The name of the class.

getColorFromHSV(float hue, float sat, float val, float alpha)

Coverts an HSV formatted color into an RBG color.

Parameters:

hue

The hue of the color (0-360).

sat

The saturation of the color (0-1).

val

The value of the color (0-1).

alpha

The alpha of the color (0-1).

getCompileTimeString()

Get the time of compilation.

getCoreLangTable()

Gets the primary LangTable used by the game.

return:

ID of the core LangTable

getCurrentActionMap()

Returns the current ActionMap.

see:

ActionMap

getCurrentDirectory()

Return the current working directory.

return:

The absolute path of the current working directory.

note:

Only present in a Tools build of Torque.

see:

getWorkingDirectory()

getDatablockCacheCRC()

UNDOCUMENTED!

getDescriptionOfClass(string className)

Returns the description string for the named class.

Parameters:

className

The name of the class.

return:

The class description in string format.

getDesktopResolution()

Returns the width, height, and bitdepth of the screen/desktop.

getDirectoryList(string path, int depth)

Gathers a list of directories starting at the given path.

Parameters:

path

String containing the path of the directory

depth

Depth of search, as in how many subdirectories to parse through

return:

Tab delimited string containing list of directories found during search, "" if no files were found

getDisplayDeviceInformation()

Get the string describing the active GFX device.

getDisplayDeviceList()

Returns a tab-seperated string of the detected devices across all adapters.

getDisplayDeviceType()

Get the string describing the active GFX device type.

getDSOPath(string scriptFileName)

Get the absolute path to the file in which the compiled code for the given script file will be stored.

Parameters:

scriptFileName

Path to the .cs script file.

return:

The absolute path to the .dso file for the given script file.

note:

The compiler will store newly compiled DSOs in the prefs path but pre-existing DSOs will be loaded from the current paths.

see:

compile

see:

getPrefsPath

getEngineName()

Get the name of the engine product that this is running from, as a string.

getEventTimeLeft(int scheduleId)

getEventTimeLeft(scheduleId) Get the time left in ms until this event will trigger.

getExecutableName()

Gets the name of the game's executable.

return:

String containing this game's executable name

getField(string text, int index)

Extract the field at the given index in the newline and/or tab separated list in text.

Fields in text must be separated by newlines and/or tabs. Parameters:

text

A list of fields separated by newlines and/or tabs.

index

The zero-based index of the field to extract.

return:

The field at the given index or "" if the index is out of range.

getField( "a b" TAB "c d" TAB "e f", 1 ) // Returns "c d"

see:

getFields

see:

getFieldCount

see:

getWord

see:

getRecord

getFieldCount(string text)

Return the number of newline and/or tab separated fields in text.

Parameters:

text

A list of fields separated by newlines and/or tabs.

return:

The number of newline and/or tab sepearated elements in text.

getFieldCount( "a b" TAB "c d" TAB "e f" ) // Returns 3

see:

getWordCount

see:

getRecordCount

getFields(string text, int startIndex, int endIndex)

Extract a range of fields from the given startIndex onwards thru endIndex.

Fields in text must be separated by newlines and/or tabs. Parameters:

text

A list of fields separated by newlines and/or tabs.

startIndex

The zero-based index of the first field to extract from text.

endIndex

The zero-based index of the last field to extract from text. If this is -1, all fields beginning with startIndex are extracted from text.

return:

A string containing the specified range of fields from text or "" if startIndex is out of range or greater than endIndex.

getFields( "a b" TAB "c d" TAB "e f", 1 ) // Returns "c d" TAB "e f"

see:

getField

see:

getFieldCount

see:

getWords

see:

getRecords

getFileCount(string pattern, bool recurse)

Returns the number of files in the directory tree that match the given patterns.

This function differs from getFileCountMultiExpr() in that it supports a single search pattern being passed in.

If you're interested in a list of files that match the given pattern and not just the number of files, use findFirstFile() and findNextFile().

Parameters:

pattern

The path and file name pattern to match against.

recurse

If true, the search will exhaustively recurse into subdirectories of the given path and match the given filename pattern counting files in subdirectories.

return:

Number of files located using the pattern

// Count the number of .cs files in a subdirectory and its subdirectories.
getFileCount( "subdirectory/*.cs" );

see:

findFirstFile()

see:

findNextFile()

see:

getFileCountMultiExpr()

getFileCountMultiExpr(string pattern, bool recurse)

Returns the number of files in the directory tree that match the given patterns.

If you're interested in a list of files that match the given patterns and not just the number of files, use findFirstFileMultiExpr() and findNextFileMultiExpr().

Parameters:

pattern

The path and file name pattern to match against, such as *.cs. Separate multiple patterns with TABs. For example: "*.cs" TAB "*.dso"

recurse

If true, the search will exhaustively recurse into subdirectories of the given path and match the given filename pattern.

return:

Number of files located using the patterns

// Count all DTS or Collada models
%filePatterns = "*.dts" TAB "*.dae";
echo( "Nunmer of shape files:" SPC getFileCountMultiExpr( %filePatterns ) );

see:

findFirstFileMultiExpr()

see:

findNextFileMultiExpr()

getFileCRC(string fileName)

Provides the CRC checksum of the given file.

Parameters:

fileName

The path to the file.

return:

The calculated CRC checksum of the file, or -1 if the file could not be found.

getFirstNumber(string str)

Get the first occuring number from str.

Parameters:

str

The string from which to read out the first number.

return:

String representation of the number or if no number.

getFormatExtensions()

Returns a list of supported shape format extensions separated by tabs.Example output: *.dsq TAB *.dae TAB.

getFormatFilters()

Returns a list of supported shape formats in filter form.

Example output: DSQ Files|*.dsq|COLLADA Files|*.dae|

getFreeTargetPosition()

Returns the current location of the free target.

getFunctionPackage(string funcName)

Provides the name of the package the function belongs to.

Parameters:

funcName

String containing name of the function

return:

The name of the function's package

getLightManagerNames()

Returns a tab seperated list of light manager names.

getLocalTime()

Return the current local time as: weekday month day year hour min sec.

Local time is platform defined.

getMainDotCsDir()

Get the absolute path to the directory that contains the main.cs script from which the engine was started.

This directory will usually contain all the game assets and, in a user-side game installation, will usually be read-only.

return:

The path to the main game assets.

getMaterialInstances(BaseMaterialDefinition target, GuiTreeViewCtrl tree)

Dumps a formatted list of currently allocated material instances to the console.

getMaterialMapping(string texName)

Returns the name of the material mapped to this texture.

If no materials are found, an empty string is returned.

Parameters:

texName

Name of the texture

getMax(float v1, float v2)

Calculate the greater of two specified numbers.

Parameters:

v1

Input value.

v2

Input value.

return:

The greater value of the two specified values.

getMaxDynamicVerts()

Get max number of allowable dynamic vertices in a single vertex buffer.

return:

the max number of allowable dynamic vertices in a single vertex buffer

getMaxF(float a, float b)

Returns the greater of the two arguments.

getMaxFrameAllocation()

UNDOCUMENTED!

getMethodPackage(string nameSpace, string method)

Provides the name of the package the method belongs to.

Parameters:

namespace

Class or namespace, such as Player

method

Name of the funciton to search for

return:

The name of the method's package

getMin(float v1, float v2)

Calculate the lesser of two specified numbers.

Parameters:

v1

Input value.

v2

Input value.

return:

The lesser value of the two specified values.

getMinF(float a, float b)

Returns the lesser of the two arguments.

getMissionAreaServerObject()

Get the MissionArea object, if any.

getNamedTargetList()

UNDOCUMENTED!

getNavMeshEventManager()

Get the EventManager object for all NavMesh updates.

getPackageList()

Returns a space delimited list of the active packages in stack order.

getPixelShaderVersion()

Returns the pixel shader version for the active device.

getRandom(int a, int b)

Returns a random number based on parameters passed in..

If no parameters are passed in, getRandom() will return a float between 0.0 and 1.0. If one parameter is passed an integer between 0 and the passed in value will be returned. Two parameters will return an integer between the specified numbers.

Parameters:

a

If this is the only parameter, a number between 0 and a is returned. Elsewise represents the lower bound.

b

Upper bound on the random number. The random number will be <= b.

return:

A pseudo-random integer between a and b, between 0 and a, or a float between 0.0 and 1.1 depending on usage.

note:

All parameters are optional.

see:

setRandomSeed

getRandomDir(Point3F axis, float thetaMin, float thetaMax, float phiMin, float phiMax)

Get a random direction vector.

getRandomF(float a, float b)

Get a random float number between a and b.

getRandomSeed()

Get the current seed used by the random number generator.

return:

The current random number generator seed value.

getRealTime()

Return the current real time in milliseconds.

Real time is platform defined; typically time since the computer booted.

getRecord(string text, int index)

Extract the record at the given index in the newline-separated list in text.

Records in text must be separated by newlines. Parameters:

text

A list of records separated by newlines.

index

The zero-based index of the record to extract.

return:

The record at the given index or "" if index is out of range.

getRecord( "a b" NL "c d" NL "e f", 1 ) // Returns "c d"

see:

getRecords

see:

getRecordCount

see:

getWord

see:

getField

getRecordCount(string text)

Return the number of newline-separated records in text.

Parameters:

text

A list of records separated by newlines.

return:

The number of newline-sepearated elements in text.

getRecordCount( "a b" NL "c d" NL "e f" ) // Returns 3

see:

getWordCount

see:

getFieldCount

getRecords(string text, int startIndex, int endIndex)

Extract a range of records from the given startIndex onwards thru endIndex.

Records in text must be separated by newlines. Parameters:

text

A list of records separated by newlines.

startIndex

The zero-based index of the first record to extract from text.

endIndex

The zero-based index of the last record to extract from text. If this is -1, all records beginning with startIndex are extracted from text.

return:

A string containing the specified range of records from text or "" if startIndex is out of range or greater than endIndex.

getRecords( "a b" NL "c d" NL "e f", 1 ) // Returns "c d" NL "e f"

see:

getRecord

see:

getRecordCount

see:

getWords

see:

getFields

getRootScene()

Get the root Scene object that is loaded.

return:

The id of the Root Scene. Will be 0 if no root scene is loaded

getRotationDirection(RotationF rot)

Gets the direction from the rotation's angles.

Parameters:

Our

rotation.

getRotationForwardVector(RotationF rot)

Get the forward vector of a rotation.

getRotationRightVector(RotationF rot)

Gets the right vector of a rotation.

Parameters:

Our

rotation.

getRotationUpVector(RotationF rot)

Gets the up vector of a rotation.

Parameters:

Our

rotation.

getScene(uint sceneId)

Get the root Scene object that is loaded.

return:

The id of the Root Scene. Will be 0 if no root scene is loaded

getSceneCount()

Get the number of active Scene objects that are loaded.

return:

The number of active scenes

getScheduleDuration(int scheduleId)

getScheduleDuration(scheduleId);

getServerCount()

getServerCount();

getServerPathSet()

UNDOCUMENTED!

getSimTime()

Sim time is time since the game started.

Return the current sim time in milliseconds.

getStockColorCount()

Gets a count of available stock colors.

return:

A count of available stock colors.

getStockColorF(string stockColorName)

Gets a floating-point-based stock color by name.

Parameters:

stockColorName

- The stock color name to retrieve.

return:

The stock color that matches the specified color name. Returns nothing if the color name is not found.

getStockColorI(string stockColorName)

Gets a byte-based stock color by name.

Parameters:

stockColorName

- The stock color name to retrieve.

return:

The stock color that matches the specified color name. Returns nothing if the color name is not found.

getStockColorName(int stockColorIndex)

Gets the stock color name at the specified index.

Parameters:

stockColorIndex

The zero-based index of the stock color name to retrieve.

return:

The stock color name at the specified index or nothing if the string is invalid.

getSubStr(string str, int start, int numChars)

Return a substring of str starting at start and continuing either through to the end of str (if numChars is -1) or for numChars characters (except if this would exceed the actual source string length).

Parameters:

str

The string from which to extract a substring.

start

The offset at which to start copying out characters.

numChars

Optional argument to specify the number of characters to copy. If this is -1, all characters up the end of the input string are copied.

return:

A string that contains the given portion of the input string.

getSubStr( "foobar", 1, 2 ) // Returns "oo".


getTag(string textTagString)

Extracts the tag from a tagged string.

Should only be used within the context of a function that receives a tagged string, and is not meant to be used outside of this context.

Parameters:

textTagString

The tagged string to extract.

return:

The tag ID of the string.

see:

syntaxDataTypes under Tagged Strings

see:

detag()

getTaggedString(string tag)

Use the getTaggedString function to convert a tag to a string.

This is not the same as detag() which can only be used within the context of a function that receives a tag. This function can be used any time and anywhere to convert a tag to a string.

Parameters:

tag

A numeric tag ID.

return:

The string as found in the Net String table.

see:

syntaxDataTypes under Tagged Strings

see:

addTaggedString()

see:

removeTaggedString()

getTerrainHeight(F32 x, F32 y)

Gets the terrain height at the specified position.

Parameters:

x

The X coordinate in world space

y

The Y coordinate in world space

return:

Returns the terrain height at the given point as an F32 value.

getTerrainHeight(Point2I position)

Gets the terrain height at the specified position.

Parameters:

position

The world space point, minus the z (height) value. Formatted as ("x y")

return:

Returns the terrain height at the given point as an F32 value.

getTerrainHeightBelowPosition(F32 x, F32 y)

Takes a world point and find the "highest" terrain underneath it.

Parameters:

x

The X coordinate in world space

y

The Y coordinate in world space

return:

Returns the closest terrain height below the given point as an F32 value.

getTerrainHeightBelowPosition(Point2I position)

Takes a world point and find the "highest" terrain underneath it.

Parameters:

position

The world space point, minus the z (height) value. Formatted as ("x y")

return:

Returns the closest terrain height below the given point as an F32 value.

getTerrainUnderWorldPoint(F32 x, F32 y, F32 z)

Takes a world point and find the "highest" terrain underneath it.

Parameters:

x

The X coordinate in world space

y

The Y coordinate in world space

z

The Z coordinate in world space

return:

Returns the ID of the requested terrain block (0 if not found).

getTerrainUnderWorldPoint(Point3F position)

Gets the terrain block that is located under the given world point.

Parameters:

position

The world space coordinate you wish to query at. Formatted as ("x y z")

return:

Returns the ID of the requested terrain block (0 if not found).

getTextureProfileStats()

Returns a list of texture profiles in the format: ProfileName TextureCount TextureMB.

getTimeSinceStart(int scheduleId)

getTimeSinceStart(scheduleId);

getToken(string text, string delimiters, int index)

Extract the substring at the given index in the delimiters separated list in text.

Parameters:

text

A delimiters list of substrings.

delimiters

Character or characters that separate the list of substrings in text.

index

The zero-based index of the substring to extract.

return:

The substring at the given index or "" if the index is out of range.

getToken( "a b c d", " ", 2 ) // Returns "c"

see:

getTokens

see:

getTokenCount

see:

getWord

see:

getField

see:

getRecord

getTokenCount(string text, string delimiters)

Return the number of delimiters substrings in text.

Parameters:

text

A delimiters list of substrings.

delimiters

Character or characters that separate the list of substrings in text.

return:

The number of delimiters substrings in text.

getTokenCount( "a b c d e", " " ) // Returns 5

see:

getWordCount

see:

getFieldCount

see:

getRecordCount

getTokens(string text, string delimiters, int startIndex, int endIndex)

Extract a range of substrings separated by delimiters at the given startIndex onwards thru endIndex.

Parameters:

text

A delimiters list of substrings.

delimiters

Character or characters that separate the list of substrings in text.

startIndex

The zero-based index of the first substring to extract from text.

endIndex

The zero-based index of the last substring to extract from text. If this is -1, all words beginning with startIndex are extracted from text.

return:

A string containing the specified range of substrings from text or "" if startIndex is out of range or greater than endIndex.

getTokens( "a b c d", " ", 1, 2, ) // Returns "b c"

see:

getToken

see:

getTokenCount

see:

getWords

see:

getFields

see:

getRecords

getTrailingNumber(string str)

Get the numeric suffix of the given input string.

Parameters:

str

The string from which to read out the numeric suffix.

return:

The numeric value of the number suffix of str or -1 if str has no such suffix.

getTrailingNumber( "test123" ) // Returns '123'.

see:

stripTrailingNumber

getUserDataDirectory()

getUserDataDirectory()

getUserHomeDirectory()

getUserHomeDirectory()

getVariable(string varName)

Returns the value of the named variable or an empty string if not found.

@varName Name of the variable to search for

return:

Value contained by varName, "" if the variable does not exist

getVersionNumber()

Get the version of the engine build, as a string.

getVersionString()

Get the version of the engine build, as a human readable string.

getWebDeployment()

Test whether Torque is running in web-deployment mode.

In this mode, Torque will usually run within a browser and certain restrictions apply (e.g. Torque will not be able to enter fullscreen exclusive mode).

return:

True if Torque is running in web-deployment mode.

getWord(string text, int index)

Extract the word at the given index in the whitespace-separated list in text.

Words in text must be separated by newlines, spaces, and/or tabs. Parameters:

text

A whitespace-separated list of words.

index

The zero-based index of the word to extract.

return:

The word at the given index or "" if the index is out of range.

getWord( "a b c", 1 ) // Returns "b"

see:

getWords

see:

getWordCount

see:

getToken

see:

getField

see:

getRecord

getWordCount(string text)

Return the number of whitespace-separated words in text.

Words in text must be separated by newlines, spaces, and/or tabs. Parameters:

text

A whitespace-separated list of words.

return:

The number of whitespace-separated words in text.

getWordCount( "a b c d e" ) // Returns 5

see:

getTokenCount

see:

getFieldCount

see:

getRecordCount

getWords(string text, int startIndex, int endIndex)

Extract a range of words from the given startIndex onwards thru endIndex.

Words in text must be separated by newlines, spaces, and/or tabs. Parameters:

text

A whitespace-separated list of words.

startIndex

The zero-based index of the first word to extract from text.

endIndex

The zero-based index of the last word to extract from text. If this is -1, all words beginning with startIndex are extracted from text.

return:

A string containing the specified range of words from text or "" if startIndex is out of range or greater than endIndex.

getWords( "a b c d", 1, 2, ) // Returns "b c"

see:

getWord

see:

getWordCount

see:

getTokens

see:

getFields

see:

getRecords

getWorkingDirectory()

Reports the current directory.

return:

String containing full file path of working directory

gotoWebPage(string address)

Open the given URL or file in the user's web browser.

Parameters:

address

The address to open. If this is not prefixed by a protocol specifier ("...://"), then the function checks whether the address refers to a file or directory and if so, prepends "file://" to adress; if the file check fails, "http://" is prepended to address.

gotoWebPage( "http://www.garagegames.com" );


importCachedFont(string faceName, int fontSize, string fileName, int padding, int kerning)

Import an image strip from exportCachedFont. Call with the same parameters you called exportCachedFont.

Parameters:

faceName

The name of the font face.

fontSize

The size of the font in pixels.

fileName

The file name and path for the input PNG.

padding

The padding between characters.

kerning

The kerning between characters.

initContainerRadiusSearch(Point3F pos, float radius, uint mask, bool useClientContainer)

Start a search for items at the given position and within the given radius, filtering by mask.

Parameters:

pos

Center position for the search

radius

Search radius

mask

Bitmask of object types to include in the search

useClientContainer

Optionally indicates the search should be within the client container.

see:

containerSearchNext

initContainerTypeSearch(uint mask, bool useClientContainer)

Start a search for all items of the types specified by the bitset mask.

Parameters:

mask

Bitmask of object types to include in the search

useClientContainer

Optionally indicates the search should be within the client container.

see:

containerSearchNext

InterpolateRotation(RotationF a, RotationF b, float factor)

Interpolates between two rotations.

Parameters:

a

Rotation one.

b

Rotation two.

factor

The amount to interpolate between the two.

return:

v, interpolated result.

isAddressTypeAvailable(int addressType)

Determines if a specified address type can be reached.

isalnum(string str, int index)

Test whether the character at the given position is an alpha-numeric character.

Alpha-numeric characters are characters that are either alphabetic (a-z, A-Z) or numbers (0-9). Parameters:

str

The string to test.

index

The index of a character in str.

return:

True if the character at the given index in str is an alpha-numeric character; false otherwise.

see:

isspace

isClass(string identifier)

Returns true if the passed identifier is the name of a declared class.

isDatablockCacheSaved()

UNDOCUMENTED!

isDebugBuild()

Test whether the engine has been compiled with TORQUE_DEBUG, i.e. if it includes debugging functionality.

return:

True if this is a debug build; false otherwise.

isDefined(string varName, string varValue)

Determines if a variable exists and contains a value.

Parameters:

varName

Name of the variable to search for

return:

True if the variable was defined in script, false if not

isDefined( "$myVar" );


IsDirectory(string directory)

Determines if a specified directory exists or not.

Parameters:

directory

String containing path in the form of "foo/bar"

return:

Returns true if the directory was found.

note:

Do not include a trailing slash '/'.

isEventPending(int scheduleId)

isEventPending(scheduleId);

isFile(string fileName)

Determines if the specified file exists or not.

Parameters:

fileName

The path to the file.

return:

Returns true if the file was found.

isFloat(string str, bool sciOk)

Returns true if the string is a float.

Parameters:

str

The string to test.

sciOk

Test for correct scientific notation and accept it (ex. 1.2e+14)

return:

true if str is a float and false if not

isFloat( "13.5" ) // Returns true.


isFunction(string funcName)

Determines if a function exists or not.

Parameters:

funcName

String containing name of the function

return:

True if the function exists, false if not

isInt(string str)

Returns true if the string is an integer.

Parameters:

str

The string to test.

return:

true if str is an integer and false if not

isInt( "13" ) // Returns true.


isMemberOfClass(string className, string superClassName)

Returns true if the class is derived from the super class.

If either class doesn't exist this returns false. Parameters:

className

The class name.

superClassName

The super class to look for.

isMethod(string nameSpace, string method)

Determines if a class/namespace method exists.

Parameters:

namespace

Class or namespace, such as Player

method

Name of the function to search for

return:

True if the method exists, false if not

isObject(string objectName)

isObject(object)

isPackage(String identifier)

Returns true if the identifier is the name of a declared package.

isQueueRegistered(string queueName)

Determines if a dispatcher queue exists.

Parameters:

queueName

String containing the name of queue

isShippingBuild()

Test whether the engine has been compiled with TORQUE_SHIPPING, i.e. in a form meant for final release.

return:

True if this is a shipping build; false otherwise.

isspace(string str, int index)

Test whether the character at the given position is a whitespace character.

Characters such as tab, space, or newline are considered whitespace. Parameters:

str

The string to test.

index

The index of a character in str.

return:

True if the character at the given index in str is a whitespace character; false otherwise.

see:

isalnum

isStockColor(string stockColorName)

Gets whether the specified name is a stock color or not.

Parameters:

stockColorName

- The stock color name to test for.

return:

Whether the specified name is a stock color or not.

isSupportedFormat(string extension)

UNDOCUMENTED!

isToolBuild()

Test whether the engine has been compiled with TORQUE_TOOLS, i.e. if it includes tool-related functionality.

return:

True if this is a tool build; false otherwise.

isValidIP(string str)

Returns true if the string is a valid ip address, excepts localhost.

Parameters:

str

The string to test.

return:

true if str is a valid ip address and false if not

isValidIP( "localhost" ) // Returns true.


isValidObjectName(string name)

Return true if the given name makes for a valid object name.

Parameters:

name

Name of object

return:

True if name is allowed, false if denied (usually because it starts with a number, _, or invalid character

isValidPort(string str)

Returns true if the string is a valid port number.

Parameters:

str

The string to test.

return:

true if str is a port and false if not

isValidPort( "8080" ) // Returns true.


isWriteableFileName(string fileName)

Determines if a file name can be written to using File I/O.

Parameters:

fileName

Name and path of file to check

return:

Returns true if the file can be written to.

lightScene(string completeCallbackFn, string mode)

Will generate static lighting for the scene if supported by the active light manager.

If mode is "forceAlways", the lightmaps will be regenerated regardless of whether lighting cache files can be written to. If mode is "forceWritable", then the lightmaps will be regenerated only if the lighting cache files can be written. Parameters:

completeCallbackFn

The name of the function to execute when the lighting is complete.

mode

One of "forceAlways", "forceWritable" or "loadOnly".

return:

Returns true if the scene lighting process was started.

listGFXResources(bool unflaggedOnly)

Returns a list of the unflagged GFX resources. See flagCurrentGFXResources for usage details.

see:

flagCurrentGFXResources, clearGFXResourceFlags, describeGFXResources

loadObject(string filename)

Loads a serialized object from a file.

Parameters:

Name

and path to text file containing the object

lockMouse(bool isLocked)

Lock or unlock the mouse to the window.

When true, prevents the mouse from leaving the bounds of the game window.

log(string message)

Logs a message to the console.

Parameters:

message

The message text.

note:

By default, messages will appear white in the console.

logError(string message)

Logs an error message to the console.

Parameters:

message

The message text.

note:

By default, errors will appear red in the console.

logWarning(string message)

Logs a warning message to the console.

Parameters:

message

The message text.

note:

By default, warnings will appear turquoise in the console.

ltrim(string str)

Remove leading whitespace from the string.

Parameters:

str

A string.

return:

A string that is the same as str but with any leading (i.e. leftmost) whitespace removed.

ltrim( "   string  " ); // Returns "string  ".
see:

rtrim

see:

trim

m2Pi()

Return the value of 2*PI (full-circle in radians).

return:

The value of 2*PI.

mAbs(float v)

Calculate absolute value of specified value.

Parameters:

v

Input Value.

return:

Absolute value of specified value.

mAcos(float v)

Calculate the arc-cosine of v.

Parameters:

v

Input Value (in radians).

return:

The arc-cosine of the input value.

makeFullPath(string path, string cwd)

Converts a relative file path to a full path.

For example, "./console.log" becomes "C:/Torque/t3d/examples/FPS Example/game/console.log" Parameters:

path

Name of file or path to check

cwd

Optional current working directory from which to build the full path.

return:

String containing non-relative directory of path

makeRelativePath(string path, string to)

Turns a full or local path to a relative one.

For example, "./game/art" becomes "game/art" Parameters:

path

Full path (may include a file) to convert

to

Optional base path used for the conversion. If not supplied the current working directory is used.

return:

String containing relative path

markDataBlocks()

Called before a series of datablocks are reloaded to help distinguish reloaded datablocks from already loaded ones.

mAsin(float v)

Calculate the arc-sine of v.

Parameters:

v

Input Value (in radians).

return:

The arc-sine of the input value.

mAtan(float rise, float run)

Calculate the arc-tangent (slope) of a line defined by rise and run.

Parameters:

rise

of line.

run

of line.

return:

The arc-tangent (slope) of a line defined by rise and run.

materialRayCast(Point3F start, Point3F end, uint mask, SceneObject pExempt, bool useClientContainer)

Cast a ray from start to end, checking for collision against items matching mask.

If pExempt is specified, then it is temporarily excluded from collision checks (For instance, you might want to exclude the player if said player was firing a weapon.) Parameters:

start

An XYZ vector containing the tail position of the ray.

end

An XYZ vector containing the head position of the ray

mask

A bitmask corresponding to the type of objects to check for

pExempt

An optional ID for a single object that ignored for this raycast

useClientContainer

Optionally indicates the search should be within the client container.

return:

A string containing either null, if nothing was struck, or these fields:

  • The ID of the object that was struck.

  • The x, y, z position that it was struck.

  • The x, y, z of the normal of the face that was struck.

  • The distance between the start point and the position we hit.

mathInit(... )

Install the math library with specified extensions.

Possible parameters are:

- 'DETECT' Autodetect math lib settings.

- 'C' Enable the C math routines. C routines are always enabled.

- 'SSE' Enable SSE math routines.


MatrixCreate(VectorF position, AngAxisF orientation)

Create a transform from the given translation and orientation.

Parameters:

position

The translation vector for the transform.

orientation

The axis and rotation that orients the transform.

return:

A transform based on the given position and orientation.

MatrixCreateFromEuler(Point3F angles)

@Create a matrix from the given rotations.

Parameters:

Vector3F

X, Y, and Z rotation in radians.

return:

A transform based on the given orientation.

MatrixInverseMulVector(MatrixF xfrm, Point3F vector)

Multiply the vector by the affine inverse of the transform.

MatrixMulPoint(TransformF transform, Point3F point)

Multiply the given point by the given transform assuming that w=1.

This function will multiply the given vector such that translation with take effect. Parameters:

transform

A transform.

point

A vector.

return:

The transformed vector.

MatrixMultiply(TransformF left, TransformF right)

Multiply the two matrices.

Parameters:

left

First transform.

right

Right transform.

return:

Concatenation of the two transforms.

MatrixMulVector(TransformF transform, VectorF vector)

Multiply the vector by the transform assuming that w=0.

This function will multiply the given vector by the given transform such that translation will not affect the vector.

Parameters:

transform

A transform.

vector

A vector.

return:

The transformed vector.

mCeil(float v)

Round v up to the nearest integer.

Parameters:

v

Number to convert to integer.

return:

Number converted to integer.

mClamp(float v, float min, float max)

Clamp the specified value between two bounds.

Parameters:

v

Input value.

min

Minimum Bound.

max

Maximum Bound.

return:

The specified value clamped to the specified bounds.

mCos(float v)

Calculate the cosine of v.

Parameters:

v

Input Value (in radians).

return:

The cosine of the input value.

mDegToRad(float degrees)

Convert specified degrees into radians.

Parameters:

degrees

Input Value (in degrees).

return:

The specified degrees value converted to radians.

messageBox(string title, string message, MBButtons buttons, MBIcons icons)

Display a modal message box using the platform's native message box implementation.

Parameters:

title

The title to display on the message box window.

message

The text message to display in the box.

buttons

Which buttons to put on the message box.

icons

Which icon to show next to the message.

return:

One of $MROK, $MRCancel, $MRRetry, and $MRDontSave identifying the button that the user pressed.

messageBox( "Error", "" );


mFloatLength(float v, uint precision)

Formats the specified number to the given number of decimal places.

Parameters:

v

Number to format.

precision

Number of decimal places to format to (1-9).

return:

Number formatted to the specified number of decimal places.

mFloor(float v)

Round v down to the nearest integer.

Parameters:

v

Number to convert to integer.

return:

Number converted to integer.

mFMod(float v, float d)

Calculate the remainder of v/d.

Parameters:

v

Input Value.

d

Divisor Value.

return:

The remainder of v/d.

mGetAngleBetweenVectors(VectorF vecA, VectorF vecB)

Returns angle between two vectors.

Parameters:

vecA

First input vector.

vecB

Second input vector.

return:

Angle between both vectors in radians.

mGetSignedAngleBetweenVectors(VectorF vecA, VectorF vecB, VectorF norm)

Returns signed angle between two vectors, using a normal for orientation.

Parameters:

vecA

First input vector.

vecB

Second input vector.

norm

Normal/Cross Product vector.

return:

Angle between both vectors in radians.

mIsPow2(int v)

Returns whether the value is an exact power of two.

Parameters:

v

Input value.

return:

Whether the specified value is an exact power of two.

mLerp(float v1, float v2, float time)

Calculate linearly interpolated value between two specified numbers using specified normalized time.

Parameters:

v1

Interpolate From Input value.

v2

Interpolate To Input value.

time

Normalized time used to interpolate values (0-1).

return:

The interpolated value between the two specified values at normalized time t.

mLog(float v)

Calculate the natural logarithm of v.

Parameters:

v

Input Value.

return:

The natural logarithm of the input value.

monthNumToStr(int num, bool abbreviate)

returns month as a word given a number or "" if number is bad

return:

month as a word given a number or "" if number is bad

moveTransformAbs(MatrixF xfrm, Point3F pos)

Move the transform to the new absolute position.

moveTransformRel(MatrixF xfrm, Point3F pos)

Move the transform to the new relative position.

mPi()

Return the value of PI (half-circle in radians).

return:

The value of PI.

mPow(float v, float p)

Calculate b raised to the p-th power.

Parameters:

v

Input Value.

p

Power to raise value by.

return:

v raised to the p-th power.

mRadToDeg(float radians)

Convert specified radians into degrees.

Parameters:

radians

Input Value (in radians).

return:

The specified radians value converted to degrees.

mRandomDir(Point3F axis, float angleMin, float angleMax)

Returns a randomized direction based on a starting axis and the min/max angles.

Parameters:

axis

Main axis to deviate the direction from.

angleMin

minimum amount of deviation from the axis.

angleMax

maximum amount of deviation from the axis.

return:

Randomized direction vector.

mRandomPointInSphere(float radius)

Returns a randomized point inside a sphere of a given radius.

Parameters:

radius

The radius of the sphere to find a point in.

return:

Randomized point inside a sphere.

mRound(float v)

Round v to the nth decimal place or the nearest whole number by default.

Parameters:

v

Value to roundn

return:

The rounded value as a S32.

mRoundColour(float v, int n)

Round v to the nth decimal place or the nearest whole number by default.

Parameters:

v

Value to roundn

n

Number of decimal places to round to, 0 by defaultn

return:

The rounded value as a S32.

mRoundDelta(float v, int d)

Round v to the nearest number based on the delta.

Parameters:

v

Value to round

d

Delta use when rounding

return:

The rounded value as a S32.

mSaturate(float v)

Clamp the specified value between 0 and 1 (inclusive).

Parameters:

v

Input value.

return:

The specified value clamped between 0 and 1 (inclusive).

mSin(float v)

Calculate the sine of v.

Parameters:

v

Input Value (in radians).

return:

The sine of the input value.

mSolveCubic(float a, float b, float c, float d)

Solve a cubic equation (3rd degree polynomial) of form a*x^3 + b*x^2 + c*x + d = 0.

Parameters:

a

First Coefficient.

b

Second Coefficient.

c

Third Coefficient.

d

Fourth Coefficient.

return:

A 4-tuple, containing: (sol x0 x1 x2). (sol) is the number of solutions(being 0, 1, 2 or 3), and (x0), (x1) and (x2) are the solutions, if any.

mSolveQuadratic(float a, float b, float c)

Solve a quadratic equation (2nd degree polynomial) of form a*x^2 + b*x + c = 0.

Parameters:

a

First Coefficient.

b

Second Coefficient.

c

Third Coefficient.

return:

A triple, containing: (sol x0 x1). (sol) is the number of solutions(being 0, 1, or 2), and (x0) and (x1) are the solutions, if any.

mSolveQuartic(float a, float b, float c, float d, float e)

Solve a quartic equation (4th degree polynomial) of form a*x^4 + b*x^3 + c*x^2 + d*x + e = 0.

Parameters:

a

First Coefficient.

b

Second Coefficient.

c

Third Coefficient.

d

Fourth Coefficient.

e

Fifth Coefficient.

return:

A 5-tuple, containing: (sol x0 x1 x2 c3). (sol) is the number of solutions(being 0, 1, 2, 3 or 4), and (x0), (x1), (x2) and (x3) are the solutions, if any.

mSqrt(float v)

Calculate the square-root of v.

Parameters:

v

Input Value.

return:

The square-root of the input value.

mTan(float v)

Calculate the tangent of v.

Parameters:

v

Input Value (in radians).

return:

The tangent of the input value.

mWrap(int v, int min, int max)

Wrap the specified value between two bounds.

Parameters:

v

Input value.

min

Minimum Bound.

max

Maximum Bound.

return:

The specified value wrapped to the specified bounds.

mWrapF(float v, float min, float max)

Wrap the specified value between two bounds.

Parameters:

v

Input value.

min

Minimum Bound.

max

Maximum Bound.

return:

The specified value wrapped to the specified bounds.

nameToID(string objectName)

nameToID(object)

NavMeshIgnore(int objid, bool _ignore)

Flag this object as not generating a navmesh result.

NavMeshUpdateAll(int objid, bool remove)

Update all NavMesh tiles that intersect the given object's world box.

NavMeshUpdateAroundObject(int objid, bool remove)

Update all NavMesh tiles that intersect the given object's world box.

NavMeshUpdateOne(int meshid, int objid, bool remove)

Update all tiles in a given NavMesh that intersect the given object's world box.

nextToken(string str1, string token, string delim)

Tokenize a string using a set of delimiting characters.

This function first skips all leading charaters in str that are contained in delimiters. From that position, it then scans for the next character in str that is contained in delimiters and stores all characters from the starting position up to the first delimiter in a variable in the current scope called token. Finally, it skips all characters in delimiters after the token and then returns the remaining string contents in str.

To scan out all tokens in a string, call this function repeatedly by passing the result it returns each time as the new str until the function returns "".

Parameters:

str

A string.

token

The name of the variable in which to store the current token. This variable is set in the scope in which nextToken is called.

delimiters

A string of characters. Each character is considered a delimiter.

return:

The remainder of str after the token has been parsed out or "" if no more tokens were found in str.

// Prints:
// a
// b
// c
%str = "a   b c";
while ( %str !$= "" )
{
   // First time, stores "a" in the variable %token and sets %str to "b c".
   %str = nextToken( %str, "token", " " );
   echo( %token );
}


openFile(string file)

Open the given file through the system. This will usually open the file in its associated application.

Parameters:

file

Path of the file to open.

note:

Only present in a Tools build of Torque.

openFolder(string path)

Open the given folder in the system's file manager.

Parameters:

path

full path to a directory.

note:

Only present in a Tools build of Torque.

pathConcat(string path, string file)

Combines two separate strings containing a file path and file name together into a single string.

Parameters:

path

String containing file path

file

String containing file name

return:

String containing concatenated file name and path

pathCopy(string fromFile, string toFile, bool noOverwrite)

Copy a file to a new location.

Parameters:

fromFile

Path of the file to copy.

toFile

Path where to copy fromFile to.

noOverwrite

If true, then fromFile will not overwrite a file that may already exist at toFile.

return:

True if the file was successfully copied, false otherwise.

note:

Only present in a Tools build of Torque.

pathOnMissionLoadDone()

Load all Path information from the mission.

This function is usually called from the loadMissionStage2() server-side function after the mission file has loaded. Internally it places all Paths into the server's PathManager. From this point the Paths are ready for transmission to the clients.

// Inform the engine to load all Path information from the mission.
pathOnMissionLoadDone();
see:

NetConnection::transmitPaths()

see:

NetConnection::clearPaths()

see:

Path

physicsDebugDraw(bool enable)

physicsDebugDraw( bool enable )

physicsDestroy()

physicsDestroy()

physicsDestroyWorld(string worldName)

physicsDestroyWorld( String worldName )

physicsGetTimeScale()

physicsGetTimeScale()

physicsInit(string library)

physicsInit( [string library] )

physicsInitWorld(string worldName)

physicsInitWorld( String worldName )

physicsPluginPresent()

Returns true if a physics plugin exists and is initialized.

physicsPluginPresent()

physicsRestoreState()

physicsRestoreState()

physicsSetTimeScale(float scale)

physicsSetTimeScale( F32 scale )

physicsSimulationEnabled()

physicsStopSimulation( String worldName )

physicsStartSimulation(string worldName)

physicsStartSimulation( String worldName )

physicsStopSimulation(string worldName)

physicsStopSimulation( String worldName )

physicsStoreState()

physicsStoreState()

playJournal(string filename)

Begin playback of a journal from a specified field.

Parameters:

filename

Name and path of file journal file

playJournalToVideo(string journalFile, string videoFile, string encoder, float framerate, Point2I resolution)

Load a journal file and capture it video.

populateAllFontCacheRange(uint rangeStart, uint rangeEnd)

Populate the font cache for all fonts with Unicode code points in the specified range.

Parameters:

rangeStart

The start Unicode point.

rangeEnd

The end Unicode point.

note:

We only support BMP-0, so code points range from 0 to 65535.

populateAllFontCacheString(string string)

Populate the font cache for all fonts with characters from the specified string.

populateFontCacheRange(string faceName, int fontSize, uint rangeStart, uint rangeEnd)

Populate the font cache for the specified font with Unicode code points in the specified range.

Parameters:

faceName

The name of the font face.

fontSize

The size of the font in pixels.

rangeStart

The start Unicode point.

rangeEnd

The end Unicode point.

note:

We only support BMP-0, so code points range from 0 to 65535.

populateFontCacheString(string faceName, int fontSize, string string)

Populate the font cache for the specified font with characters from the specified string.

Parameters:

faceName

The name of the font face.

fontSize

The size of the font in pixels.

string

The string to populate.

preloadClientDataBlocks()

Preload all datablocks in client mode.

(Server parameter is set to false). This will take some time to complete.

profilerDump()

Dumps current profiling stats to the console window.

note:

Markers disabled with profilerMarkerEnable() will be skipped over. If the profiler is currently running, it will be disabled.

profilerDumpToFile(string fileName)

Dumps current profiling stats to a file.

note:

If the profiler is currently running, it will be disabled.

Parameters:
fileName

Name and path of file to save profiling stats to. Must use forward slashes (/). Will attempt to create the file if it does not already exist.

profilerDumpToFile( "C:/Torque/log1.txt" );


profilerEnable(bool enable)

Enables or disables the profiler.

Data is only gathered while the profiler is enabled.

note:

Profiler is not available in shipping builds. T3D has predefined profiling areas surrounded by markers, but you may need to define additional markers (in C++) around areas you wish to profile, by using the PROFILE_START( markerName ); and PROFILE_END(); macros.

profilerMarkerEnable(string markerName, bool enable)

Enable or disable a specific profile.

Parameters:

enable

Optional paramater to enable or disable the profile.

markerName

Name of a specific marker to enable or disable.

note:

Calling this function will first call profilerReset(), clearing all data from profiler. All profile markers are enabled by default.

profilerReset()

Resets the profiler, clearing it of all its data.

If the profiler is currently running, it will first be disabled. All markers will retain their current enabled/disabled status.

queryAllServers(uint lanPort, uint flags, string gameType, string missionType, uint minPlayers, uint maxPlayers, uint maxBots, uint regionMask, uint maxPing, uint minCPU, uint filterFlags)

queryAllServers(...);

queryLanServers(uint lanPort, uint flags, string gameType, string missionType, uint minPlayers, uint maxPlayers, uint maxBots, uint regionMask, uint maxPing, uint minCPU, uint filterFlags)

queryLanServers(...);

queryMasterServer(uint flags, string gameType, string missionType, uint minPlayers, uint maxPlayers, uint maxBots, uint regionMask, uint maxPing, uint minCPU, uint filterFlags)

queryMasterServer(...);

querySingleServer(string addrText, U8 flags)

querySingleServer(address, flags);

quit()

Shut down the engine and exit its process.

This function cleanly uninitializes the engine and then exits back to the system with a process exit status indicating a clean exit.

see:

quitWithErrorMessage

quitWithErrorMessage(string message, int status)

Display an error message box showing the given message and then shut down the engine and exit its process.

This function cleanly uninitialized the engine and then exits back to the system with a process exit status indicating an error.

Parameters:

message

The message to log to the console and show in an error message box.

status

The status code to return to the OS.

see:

quit

quitWithStatus(int status)

Shut down the engine and exit its process.

This function cleanly uninitializes the engine and then exits back to the system with a given return status code.

Parameters:

status

The status code to return to the OS.

see:

quitWithErrorMessage

realQuit()

UNDOCUMENTED!

registerMessageListener(string queueName, string listenerName)

Registers an event message.

Parameters:

queueName

String containing the name of queue to attach listener to

listener

Name of event messenger

registerMessageQueue(string queueName)

Registeres a dispatcher queue.

Parameters:

queueName

String containing the name of queue

reInitMaterials()

Flushes all procedural shaders and re-initializes all active material instances.

reloadTextures()

Reload all the textures from disk.

removeField(string text, int index)

Remove the field in text at the given index.

Fields in text must be separated by newlines and/or tabs. Parameters:

text

A list of fields separated by newlines and/or tabs.

index

The zero-based index of the field in text.

return:

A new string with the field at the given index removed or the original string if index is out of range.

removeField( "a b" TAB "c d" TAB "e f", 1 ) // Returns "a b" TAB "e f"

see:

removeWord

see:

removeRecord

removeGlobalShaderMacro(string name)

Removes an existing global macro by name.

see:

addGlobalShaderMacro

removeRecord(string text, int index)

Remove the record in text at the given index.

Records in text must be separated by newlines. Parameters:

text

A list of records separated by newlines.

index

The zero-based index of the record in text.

return:

A new string with the record at the given index removed or the original string if index is out of range.

removeRecord( "a b" NL "c d" NL "e f", 1 ) // Returns "a b" NL "e f"

see:

removeWord

see:

removeField

removeTaggedString(int tag)

Remove a tagged string from the Net String Table.

Parameters:

tag

The tag associated with the string

see:

syntaxDataTypes under Tagged Strings

see:

addTaggedString()

see:

getTaggedString()

removeToken(string text, string delimiters, int index)

Remove the substring in text separated by delimiters at the given index.

Parameters:

text

A delimiters list of substrings.

delimiters

Character or characters that separate the list of substrings in text.

index

The zero-based index of the word in text.

return:

A new string with the substring at the given index removed or the original string if index is out of range.

removeToken( "a b c d", " ", 2 ) // Returns "a b d"

see:

removeWord

see:

removeField

see:

removeRecord

removeWord(string text, int index)

Remove the word in text at the given index.

Words in text must be separated by newlines, spaces, and/or tabs. Parameters:

text

A whitespace-separated list of words.

index

The zero-based index of the word in text.

return:

A new string with the word at the given index removed or the original string if index is out of range.

removeWord( "a b c d", 2 ) // Returns "a b d"

see:

removeToken

see:

removeField

see:

removeRecord

resetDatablockCache()

UNDOCUMENTED!

resetFPSTracker()

Reset FPS stats (fps::)

ResetGFX()

forces the gbuffer to be reinitialized in cases of improper/lack of buffer clears.

resetLightManager()

Deactivates and then activates the currently active light manager.This causes most shaders to be regenerated and is often used when global rendering changes have occured.

restWords(string text)

Return all but the first word in text.

Parameters:

text

A list of words separated by newlines, spaces, and/or tabs.

return:

text with the first word removed.

note:

This is equal to @tsexample_nopar getWords( text, 1 )

see:

getWords

rolloverRayCast(Point3F start, Point3F end, uint mask)

Performs a raycast from points start to end and returns the ID of nearest intersecting object with a type found in the specified mask. Returns -1 if no object is found.

RotationLookAt(Point3F origin, Point3F target, Point3F up)

Provides a rotation orientation to look at a target from a given position.

Parameters:

origin

Position of the object doing the looking.

target

Position to be looked at.

up

The up angle to orient the rotation.

return:

v orientation result.

rtrim(string str)

Remove trailing whitespace from the string.

Parameters:

str

A string.

return:

A string that is the same as str but with any trailing (i.e. rightmost) whitespace removed.

rtrim( "   string  " ); // Returns "   string".
see:

ltrim

see:

trim

saveCompositeTexture(string pathR, string pathG, string pathB, string pathA, string inputKeyString, string saveAs)

File1,file2,file3,file4,[chanels for r g b and a locations],saveAs.

saveJournal(string filename)

Save the journal to the specified file.

saveObject(SimObject object, string filename)

Serialize the object to a file.

Parameters:

object

The object to serialize.

filename

The file name and path.

sbmDumpStats()

UNDOCUMENTED!

sbmDumpStrings()

UNDOCUMENTED!

sceneDumpZoneStates(bool updateFirst)

Dump the current zoning states of all zone spaces in the scene to the console.

Parameters:

updateFirst

If true, zoning states are brought up to date first; if false, the zoning states are dumped as is.

note:

Only valid on the client.

sceneGetZoneOwner(uint zoneId)

Return the SceneObject that contains the given zone.

Parameters:

zoneId

ID of zone.

return:

A SceneObject or NULL if the given zoneId is invalid.

note:

Only valid on the client.

screenShot(string file, string format, uint tileCount, float tileOverlap)

Takes a screenshot with optional tiling to produce huge screenshots.

Parameters:

file

The output image file path.

format

Either JPEG or PNG.

tileCount

If greater than 1 will tile the current screen size to take a large format screenshot.

tileOverlap

The amount of horizontal and vertical overlap between the tiles used to remove tile edge artifacts from post effects.

setCoreLangTable(string lgTable)

Sets the primary LangTable used by the game.

Parameters:

ID of the core LangTable

setCurrentDirectory(string path)

Set the current working directory.

Parameters:

path

The absolute or relative (to the current working directory) path of the directory which should be made the new working directory.

return:

True if the working directory was successfully changed to path, false otherwise.

note:

Only present in a Tools build of Torque.

setDatablockCacheCRC(uint crc)

UNDOCUMENTED!

setDefaultFov(float defaultFOV)

Set the default FOV for a camera.

Parameters:

defaultFOV

The default field of view in degrees

setField(string text, int index, string replacement)

Replace the field in text at the given index with replacement.

Fields in text must be separated by newlines and/or tabs. Parameters:

text

A list of fields separated by newlines and/or tabs.

index

The zero-based index of the field to replace.

replacement

The string with which to replace the field.

return:

A new string with the field at the given index replaced by replacement or the original string if index is out of range.

setField( "a b" TAB "c d" TAB "e f", 1, "g h" ) // Returns "a b" TAB "g h" TAB "e f"

see:

getField

see:

setWord

see:

setRecord

SetFogVolumeQuality(uint new_quality)

Resizes the rendertargets of the Volumetric Fog object. @params new_quality new quality for the rendertargets 1 = full size, 2 = halfsize, 3 = 1/3, 4 = 1/4 ...

setFov(float FOV)

Set the FOV of the camera.

Parameters:

FOV

The camera's new FOV in degrees

setLightManager(string name)

Finds and activates the named light manager.

return:

Returns true if the light manager is found and activated.

setLogMode(int mode)

Determines how log files are written.

Sets the operational mode of the console logging system.

Parameters:

mode

Parameter specifying the logging mode. This can be:

  • 1: Open and close the console log file for each seperate string of output. This will ensure that all parts get written out to disk and that no parts remain in intermediate buffers even if the process crashes.

  • 2: Keep the log file open and write to it continuously. This will make the system operate faster but if the process crashes, parts of the output may not have been written to disk yet and will be missing from the log.

Additionally, when changing the log mode and thus opening a new log file, either of the two mode values may be combined by binary OR with 0x4 to cause the logging system to flush all console log messages that had already been issued to the console system into the newly created log file.

note:

Xbox 360 does not support logging to a file. Use Platform::OutputDebugStr in C++ instead.

setMainDotCsDir(string path)

setMainDotCsDir()

setNetPort(int port, bool bind)

Set the network port for the game to use.

Parameters:

port

The port to use.

bind

True if bind() should be called on the port.

return:

True if the port was successfully opened. This will trigger a windows firewall prompt. If you don't have firewall tunneling tech you can set this to false to avoid the prompt.

setPixelShaderVersion(float version)

Sets the pixel shader version for the active device. This can be used to force a lower pixel shader version than is supported by the device for testing or performance optimization.

Parameters:

version

The floating point shader version number.

note:

This will only affect shaders/materials created after the call and should be used before the game begins.

see:

$pref::Video::forcedPixVersion

setRandomSeed(int seed)

Set the current seed for the random number generator.

Based on this seed, a repeatable sequence of numbers will be produced by getRandom(). Parameters:

seed

The seed with which to initialize the randon number generator with. The same seed will always leed tothe same sequence of pseudo-random numbers. If -1, the current timestamp will be used as the seed which is a good basis for randomization.

setRecord(string text, int index, string replacement)

Replace the record in text at the given index with replacement.

Records in text must be separated by newlines. Parameters:

text

A list of records separated by newlines.

index

The zero-based index of the record to replace.

replacement

The string with which to replace the record.

return:

A new string with the record at the given index replaced by replacement or the original string if index is out of range.

setRecord( "a b" NL "c d" NL "e f", 1, "g h" ) // Returns "a b" NL "g h" NL "e f"

see:

getRecord

see:

setWord

see:

setField

setReflectFormat(GFXFormat format)

Set the reflection texture format.

setRotationRightVector(RotationF rot, VectorF rightVec)

Sets the right vector of the rotation.

Parameters:

Starting

rotation.

New

up vector.

return:

New rotation with the set right vector.

setRotationUpVector(RotationF rot, VectorF upVec)

Sets the up vector of the rotation.

Parameters:

Starting

rotation.

New

up vector.

return:

New rotation with the set up vector.

setServerInfo(uint index)

setServerInfo(index);

setShadowManager(string sShadowSystemName)

string sShadowSystemName

setShadowVizLight(string name)

UNDOCUMENTED!

setToken(string text, string delimiters, int index, string replacement)

Replace the substring in text separated by delimiters at the given index with replacement.

Parameters:

text

A delimiters list of substrings.

delimiters

Character or characters that separate the list of substrings in text.

index

The zero-based index of the substring to replace.

replacement

The string with which to replace the substring.

return:

A new string with the substring at the given index replaced by replacement or the original string if index is out of range.

setToken( "a b c d", " ", 2, "f" ) // Returns "a b f d"

see:

getToken

see:

setWord

see:

setField

see:

setRecord

setVariable(string varName, string value)

Sets the value of the named variable.

Parameters:

varName

Name of the variable to locate

value

New value of the variable

return:

True if variable was successfully found and set

setWord(string text, int index, string replacement)

Replace the word in text at the given index with replacement.

Words in text must be separated by newlines, spaces, and/or tabs. Parameters:

text

A whitespace-separated list of words.

index

The zero-based index of the word to replace.

replacement

The string with which to replace the word.

return:

A new string with the word at the given index replaced by replacement or the original string if index is out of range.

setWord( "a b c d", 2, "f" ) // Returns "a b f d"

see:

getWord

see:

setToken

see:

setField

see:

setRecord

setZoomSpeed(int speed)

Set the zoom speed of the camera. This affects how quickly the camera changes from one field of view to another.

Parameters:

speed

The camera's zoom speed in ms per 90deg FOV change

sfxCreateDevice(string provider, string device, bool useHardware, int maxBuffers)

Try to create a new sound device using the given properties.

If a sound device is currently initialized, it will be uninitialized first. However, be aware that in this case, if this function fails, it will not restore the previously active device but rather leave the sound system in an uninitialized state.

Sounds that are already playing while the new device is created will be temporarily transitioned to virtualized playback and then resume normal playback once the device has been created.

In the core scripts, sound is automatically set up during startup in the sfxStartup() function.

Parameters:

provider

The name of the device provider as returned by sfxGetAvailableDevices().

device

The name of the device as returned by sfxGetAvailableDevices().

useHardware

Whether to enabled hardware mixing on the device or not. Only relevant if supported by the given device.

maxBuffers

The maximum number of concurrent voices for this device to use or -1 for the device to pick its own reasonable default.

return:

True if the initialization was successful, false if not.

note:

This function must be called before any of the sound playback functions can be used.

see:

sfxGetAvailableDevices

see:

sfxGetDeviceInfo

see:

sfxDeleteDevice

SFX_devices

sfxCreateSource(SFXDescription description, string filename)

Create a temporary SFXProfile from the given description and filename and then create and return a new source that plays the profile.

The source will be returned in stopped state. Call SFXSource::play() to start playback.

In contrast to play-once sources, the source object will not be automatically deleted once playback stops. Call delete() to release the source object.

Parameters:

description

The description to use for setting up the temporary SFXProfile.

filename

Path to the sound file to play.

return:

A new SFXSource for playback of the given track or 0 if no source or no temporary profile could be created.

// Create a source for a music track:
%source = sfxCreateSource( AudioMusicLoop2D, "art/sound/backgroundMusic" );
%source.play();

see:

SFXProfile

sfxCreateSource(SFXDescription description, string filename, float x, float y, float z)

Create a temporary SFXProfile from the given description and filename and then create and return a new source that plays the profile. Position the sound source at the given coordinates (if it is a 3D sound).

The source will be returned in stopped state. Call SFXSource::play() to start playback.

In contrast to play-once sources, the source object will not be automatically deleted once playback stops. Call delete() to release the source object.

Parameters:

description

The description to use for setting up the temporary SFXProfile.

filename

Path to the sound file to play.

x

The X coordinate of the 3D sound position.

y

The Y coordinate of the 3D sound position.

z

The Z coordinate of the 3D sound position.

return:

A new SFXSource for playback of the given track or 0 if no source or no temporary profile could be created.

// Create a source for a music track and position it at (100, 200, 300):
%source = sfxCreateSource( AudioMusicLoop3D, "art/sound/backgroundMusic", 100, 200, 300 );
%source.play();

see:

SFXProfile

sfxCreateSource(SFXTrack track)

Create a new source that plays the given track.

The source will be returned in stopped state. Call SFXSource::play() to start playback.

In contrast to play-once sources, the source object will not be automatically deleted once playback stops. Call delete() to release the source object.

This function will automatically create the right SFXSource type for the given SFXTrack.

Parameters:

track

The track the source should play.

return:

A new SFXSource for playback of the given track or 0 if no source could be created from the given track.

note:

Trying to create a source for a device-specific track type will fail if the currently selected device does not support the type. Example: trying to create a source for an FMOD Designer event when not running FMOD.

// Create and play a source from a pre-existing profile:
%source = sfxCreateSource( SoundFileProfile );
%source.play();


sfxCreateSource(SFXTrack track, float x, float y, float z)

Create a new source that plays the given track and position its 3D sounds source at the given coordinates (if it is a 3D sound).

The source will be returned in stopped state. Call SFXSource::play() to start playback.

In contrast to play-once sources, the source object will not be automatically deleted once playback stops. Call delete() to release the source object.

This function will automatically create the right SFXSource type for the given SFXTrack.

Parameters:

track

The track the source should play.

x

The X coordinate of the 3D sound position.

y

The Y coordinate of the 3D sound position.

z

The Z coordinate of the 3D sound position.

return:

A new SFXSource for playback of the given track or 0 if no source could be created from the given track.

note:

Trying to create a source for a device-specific track type will fail if the currently selected device does not support the type. Example: trying to create a source for an FMOD Designer event when not running FMOD.

// Create and play a source from a pre-existing profile and position it at (100, 200, 300):
%source = sfxCreateSource( SoundFileProfile, 100, 200, 300 );
%source.play();


sfxDeleteDevice()

Delete the currently active sound device and release all its resources.

SFXSources that are still playing will be transitioned to virtualized playback mode. When creating a new device, they will automatically transition back to normal playback.

In the core scripts, this is done automatically for you during shutdown in the sfxShutdown() function.

see:

sfxCreateDevice

SFX_devices

sfxDeleteWhenStopped(SFXSource source)

Mark the given source for deletion as soon as it moves into stopped state.

This function will retroactively turn the given source into a play-once source (see Play-Once Sources).

Parameters:

source

A sound source.

sfxDumpSources(bool includeGroups)

Dump information about all current SFXSource instances to the console.

The dump includes information about the playback status for each source, volume levels, virtualization, etc. Parameters:

includeGroups

If true, direct instances of SFXSources (which represent logical sound groups) will be included. Otherwise only instances of subclasses of SFXSources are included in the dump.

see:

SFXSource

see:

sfxDumpSourcesToString

sfxDumpSourcesToString(bool includeGroups)

Dump information about all current SFXSource instances to a string.

The dump includes information about the playback status for each source, volume levels, virtualization, etc. Parameters:

includeGroups

If true, direct instances of SFXSources (which represent logical sound groups) will be included. Otherwise only instances of subclasses of SFXSources are included in the dump.

return:

A string containing a dump of information about all currently instantiated SFXSources.

see:

SFXSource

see:

sfxDumpSources

sfxGetActiveStates()

Return a newline-separated list of all active states.

return:

A list of the form

stateName1 NL stateName2 NL stateName3 ...
where each element is the name of an active state object.

// Disable all active states.
foreach$( %state in sfxGetActiveStates() )
   %state.disable();


sfxGetAvailableDevices()

Get a list of all available sound devices.

The return value will be a newline-separated list of entries where each line describes one available sound device. Each such line will have the following format:

provider TAB device TAB hasHardware TAB numMaxBuffers

  • provider: The name of the device provider (e.g. "FMOD").

  • device: The name of the device as returned by the device layer.

  • hasHardware: Whether the device supports hardware mixing or not.

  • numMaxBuffers: The maximum number of concurrent voices supported by the device's mixer. If this limit limit is exceeded, i.e. if there are more active sounds playing at any one time, then voice virtualization will start culling voices and put them into virtualized playback mode. Voice virtualization may or may not be provided by the device itself; if not provided by the device, it will be provided by Torque's sound system.

return:

A newline-separated list of information about all available sound devices.

see:

sfxCreateDevice

see:

sfxGetDeviceInfo

see:

$SFX::DEVICE_INFO_PROVIDER

see:

$SFX::DEVICE_INFO_NAME

see:

$SFX::DEVICE_INFO_USEHARDWARE

see:

$SFX::DEVICE_INFO_MAXBUFFERS

SFX_devices

sfxGetDeviceInfo()

Return information about the currently active sound device.

The return value is a tab-delimited string of the following format:

provider TAB device TAB hasHardware TAB numMaxBuffers TAB caps

  • provider: The name of the device provider (e.g. "FMOD").

  • device: The name of the device as returned by the device layer.

  • hasHardware: Whether the device supports hardware mixing or not.

  • numMaxBuffers: The maximum number of concurrent voices supported by the device's mixer. If this limit limit is exceeded, i.e. if there are more active sounds playing at any one time, then voice virtualization will start culling voices and put them into virtualized playback mode. Voice virtualization may or may not be provided by the device itself; if not provided by the device, it will be provided by Torque's sound system.

  • caps: A bitfield of capability flags.

return:

A tab-separated list of properties of the currently active sound device or the empty string if no sound device has been initialized.

see:

sfxCreateDevice

see:

sfxGetAvailableDevices

see:

$SFX::DEVICE_INFO_PROVIDER

see:

$SFX::DEVICE_INFO_NAME

see:

$SFX::DEVICE_INFO_USEHARDWARE

see:

$SFX::DEVICE_INFO_MAXBUFFERS

see:

$SFX::DEVICE_INFO_CAPS

see:

$SFX::DEVICE_CAPS_REVERB

see:

$SFX::DEVICE_CAPS_VOICEMANAGEMENT

see:

$SFX::DEVICE_CAPS_OCCLUSION

see:

$SFX::DEVICE_CAPS_DSPEFFECTS

see:

$SFX::DEVICE_CAPS_MULTILISTENER

see:

$SFX::DEVICE_CAPS_FMODDESIGNER

SFX_devices

sfxGetDistanceModel()

Get the falloff curve type currently being applied to 3D sounds.

return:

The current distance model type.

Volume Attenuation

SFX_3d

sfxGetDopplerFactor()

Get the current global doppler effect setting.

return:

The current global doppler effect scale factor (>=0).

see:

sfxSetDopplerFactor

Doppler Effect

sfxGetRolloffFactor()

Get the current global scale factor applied to volume attenuation of 3D sounds in the logarithmic model.

return:

The current scale factor for logarithmic 3D sound falloff curves.

see:

sfxGetDistanceModel

see:

SFXDistanceModel

Volume Attenuation SFX_3d

sfxPlay(SFXSource source)

Start playback of the given source.

This is the same as calling SFXSource::play() directly.

Parameters:

source

The source to start playing.

return:

source.

// Create and play a source from a pre-existing profile:
%source = sfxCreateSource( SoundFileProfile );
%source.play();


sfxPlay(SFXTrack track)

Create a new play-once source for the given track and start playback of the source.

This is equivalent to calling sfxCreateSource() on @track and SFXSource::play() on the resulting source.

Parameters:

track

The sound datablock to play.

return:

The newly created play-once source or 0 if the creation failed.

Play-Once Sources

sfxPlay(SFXTrack track, float x, float y, float z)

Create a new play-once source for the given track, position its 3D sound at the given coordinates (if the track's description is set up for 3D sound) and start playback of the source.

This is equivalent to calling sfxCreateSource() on @track and SFXSource::play() on the resulting source.

Parameters:

track

The sound datablock to play.

x

The X coordinate of the 3D sound position.

y

The Y coordinate of the 3D sound position.

z

The Z coordinate of the 3D sound position.

return:

The newly created play-once source or 0 if the creation failed.

Play-Once Sources

sfxPlayOnce(SFXDescription description, string filename)

Create a new temporary SFXProfile from the given description and filename, then create a play-once source for it and start playback.

Once playback has finished, the source will be automatically deleted in the next sound system update. If not referenced otherwise by then, the temporary SFXProfile will also be deleted. Parameters:

description

The description to use for playback.

filename

Path to the sound file to play.

return:

A newly created temporary source in "Playing" state or 0 if the operation failed.

// Play a sound effect file once.
sfxPlayOnce( AudioEffects, "art/sound/weapons/Weapon_pickup" );

Play-Once Sources

sfxPlayOnce(SFXDescription description, string filename, float x, float y, float z, float fadeInTime)

Create a new temporary SFXProfile from the given description and filename, then create a play-once source for it and start playback. Position the source's 3D sound at the given coordinates (only if the description is set up for 3D sound).

Once playback has finished, the source will be automatically deleted in the next sound system update. If not referenced otherwise by then, the temporary SFXProfile will also be deleted. Parameters:

description

The description to use for playback.

filename

Path to the sound file to play.

x

The X coordinate of the 3D sound position.

y

The Y coordinate of the 3D sound position.

z

The Z coordinate of the 3D sound position.

fadeInTime

If >=0, this overrides the SFXDescription::fadeInTime value on the track's description.

return:

A newly created temporary source in "Playing" state or 0 if the operation failed.

// Play a sound effect file once using a 3D sound with a default falloff placed at the origin.
sfxPlayOnce( AudioDefault3D, "art/sound/weapons/Weapon_pickup", 0, 0, 0 );

Play-Once Sources

sfxPlayOnce(SFXTrack track)

Create a play-once source for the given track.

Once playback has finished, the source will be automatically deleted in the next sound system update. Parameters:

track

The sound datablock.

return:

A newly created temporary source in "Playing" state or 0 if the operation failed.

Play-Once Sources

sfxPlayOnce(SFXTrack track, float x, float y, float z, float fadeInTime)

Create a play-once source for the given given track and position the source's 3D sound at the given coordinates only if the track's description is set up for 3D sound).

Once playback has finished, the source will be automatically deleted in the next sound system update. Parameters:

track

The sound datablock.

x

The X coordinate of the 3D sound position.

y

The Y coordinate of the 3D sound position.

z

The Z coordinate of the 3D sound position.

fadeInTime

If >=0, this overrides the SFXDescription::fadeInTime value on the track's description.

return:

A newly created temporary source in "Playing" state or 0 if the operation failed.

// Immediately start playing the given track.  Fade it in to full volume over 5 seconds.
sfxPlayOnce( MusicTrack, 0, 0, 0, 5.f );

Play-Once Sources

sfxSetDistanceModel(SFXDistanceModel model)

Set the falloff curve type to use for distance-based volume attenuation of 3D sounds.

Parameters:

model

The distance model to use for 3D sound.

note:

This setting takes effect globally and is applied to all 3D sounds.

sfxSetDopplerFactor(float value)

Set the global doppler effect scale factor.

Parameters:

value

The new doppler shift scale factor.

pre:

value must be >= 0.

see:

sfxGetDopplerFactor

Doppler Effect

sfxSetRolloffFactor(float value)

Set the global scale factor to apply to volume attenuation of 3D sounds in the logarithmic model.

Parameters:

value

The new scale factor for logarithmic 3D sound falloff curves.

pre:

value must be > 0.

note:

This function has no effect if the currently distance model is set to SFXDistanceModel::Linear.

see:

sfxGetDistanceModel

see:

SFXDistanceModel

Volume Attenuation SFX_3d

sfxStop(SFXSource source)

Stop playback of the given source.

This is equivalent to calling SFXSource::stop().

Parameters:

source

The source to put into stopped state.

sfxStopAndDelete(SFXSource source)

Stop playback of the given source (if it is not already stopped) and delete the source.

The advantage of this function over directly calling delete() is that it will correctly handle volume fades that may be configured on the source. Whereas calling delete() would immediately stop playback and delete the source, this functionality will wait for the fade-out to play and only then stop the source and delete it.

Parameters:

source

A sound source.

Volume Fades

ShakeCamera(float duration, float falloff, VectorF amplitude, VectorF frequency)

UNDOCUMENTED!

sizeof(string objectOrClass)

Determines the memory consumption of a class or object.

Parameters:

objectOrClass

The object or class being measured.

return:

Returns the total size of an object in bytes.

snapToggle()

Prevents mouse movement from being processed.

In the source, whenever a mouse move event occurs GameTSCtrl::onMouseMove() is called. Whenever snapToggle() is called, it will flag a variable that can prevent this from happening: gSnapLine. This variable is not exposed to script, so you need to call this function to trigger it.

// Snapping is off by default, so we will toggle
// it on first:
PlayGui.snapToggle();

// Mouse movement should be disabled
// Let's turn it back on
PlayGui.snapToggle();


spawnObject(class )

Global function used for spawning any type of object.

Note: This is separate from SpawnSphere::spawnObject(). This function is not called off any other class and uses different parameters than the SpawnSphere's function. In the source, SpawnSphere::spawnObject() actually calls this function and passes its properties (spawnClass, spawnDatablock, etc).

Parameters:

class

Mandatory field specifying the object class, such as Player or TSStatic.

datablock

Field specifying the object's datablock, optional for objects such as TSStatic, mandatory for game objects like Player.

name

Optional field specifying a name for this instance of the object.

properties

Optional set of parameters applied to the spawn object during creation.

script

Optional command(s) to execute when spawning an object.

// Set the parameters for the spawn function
%objectClass = "Player";
%objectDatablock = "DefaultPlayerData";
%objectName = "PlayerName";
%additionalProperties = "health = \"0\";"; // Note the escape sequence \ in front of quotes
%spawnScript = "echo(\"Player Spawned\");" // Note the escape sequence \ in front of quotes
// Spawn with the engine's Sim::spawnObject() function
%player = spawnObject(%objectClass, %objectDatablock, %objectName, %additionalProperties, %spawnScript);


StartClientReplication()

Activates the shape replicator.

// Call the function
StartClientReplication()


startEffectron(afxEffectronData datablock, string constraintSource, string constraintName, SimObject extra)

Instantiates the effectron defined by datablock.

startFileChangeNotifications()

Start watching resources for file changes.

Typically this is called during initializeCore().

see:

stopFileChangeNotifications()

StartFoliageReplication()

Activates the foliage replicator.

// Call the function
StartFoliageReplication();


startHeartbeat()

startHeartbeat();

startPrecisionTimer()

startPrecisionTimer() - Create and start a high resolution platform timer. Returns the timer id.

startSelectron(SceneObject selectedObj, unsigned int subcode, SimObject extra)

Instantiates a selectron.

startsWith(string str, string prefix, bool caseSensitive)

Test whether the given string begins with the given prefix.

Parameters:

str

The string to test.

prefix

The potential prefix of str.

caseSensitive

If true, the comparison will be case-sensitive; if false, differences in casing will not be taken into account.

return:

True if the first characters in str match the complete contents of prefix; false otherwise.

startsWith( "TEST123", "test" ) // Returns true.
see:

endsWith

startVideoCapture(GuiCanvas canvas, string filename, string encoder, float framerate, Point2I resolution)

Begins a video capture session.

see:

stopVideoCapture

stopFileChangeNotifications()

Stop watching resources for file changes.

Typically this is called during shutdownCore().

see:

startFileChangeNotifications()

stopHeartbeat()

stopHeartbeat();

stopPrecisionTimer(int id)

stopPrecisionTimer( S32 id ) - Stop and destroy timer with the passed id. Returns the elapsed milliseconds.

stopSampling()

Stops the rendering sampler.

stopServerQuery()

stopServerQuery();

stopVideoCapture()

Stops the video capture session.

see:

startVideoCapture

strasc(string chr)

Return the integer character code value corresponding to the first character in the given string.

Parameters:

chr

a (one-character) string.

return:

the UTF32 code value for the first character in the given string.

strchr(string str, string chr)

Find the first occurrence of the given character in str.

Parameters:

str

The string to search.

chr

The character to search for. Only the first character from the string is taken.

return:

The remainder of the input string starting with the given character or the empty string if the character could not be found.

see:

strrchr

strchrpos(string str, string chr, int start)

Find the first occurrence of the given character in the given string.

Parameters:

str

The string to search.

chr

The character to look for. Only the first character of this string will be searched for.

start

The index into str at which to start searching for the given character.

return:

The index of the first occurrence of chr in str or -1 if str does not contain the given character.

strchrpos( "test", "s" ) // Returns 2.


strcmp(string str1, string str2)

Compares two strings using case-sensitive comparison.

Parameters:

str1

The first string.

str2

The second string.

return:

0 if both strings are equal, a value <0 if the first character different in str1 has a smaller character code value than the character at the same position in str2, and a value >1 otherwise.

if( strcmp( %var, "foobar" ) == 0 )
   echo( "%var is equal to 'foobar'" );
see:

stricmp

see:

strnatcmp

strformat(string format, string value)

Format the given value as a string using printf-style formatting.

Parameters:

format

A printf-style format string.

value

The value argument matching the given format string.

// Convert the given integer value to a string in a hex notation.
%hex = strformat( "%x", %value );

see:

http://en.wikipedia.org/wiki/Printf

stricmp(string str1, string str2)

Compares two strings using case-insensitive comparison.

Parameters:

str1

The first string.

str2

The second string.

return:

0 if both strings are equal, a value <0 if the first character different in str1 has a smaller character code value than the character at the same position in str2, and a value >0 otherwise.

if( stricmp( "FOObar", "foobar" ) == 0 )
   echo( "this is always true" );
see:

strcmp

see:

strinatcmp

strinatcmp(string str1, string str2)

Compares two strings using "natural order" case-insensitive comparison.

Natural order means that rather than solely comparing single character code values, strings are ordered in a natural way. For example, the string "hello10" is considered greater than the string "hello2" even though the first numeric character in "hello10" actually has a smaller character value than the corresponding character in "hello2". However, since 10 is greater than 2, strnatcmp will put "hello10" after "hello2". Parameters:

str1

The first string.

str2

The second string.

return:

0 if the strings are equal, a value >0 if str1 comes after str2 in a natural order, and a value <0 if str1 comes before str2 in a natural order.

// Bubble sort 10 elements of %array using natural order
do
{
   %swapped = false;
   for( %i = 0; %i < 10 - 1; %i ++ )
      if( strnatcmp( %array[ %i ], %array[ %i + 1 ] ) > 0 )
      {
         %temp = %array[ %i ];
         %array[ %i ] = %array[ %i + 1 ];
         %array[ %i + 1 ] = %temp;
         %swapped = true;
      }
}
while( %swapped );
see:

stricmp

see:

strnatcmp

stripChars(string str, string chars)

Remove all occurrences of characters contained in chars from str.

Parameters:

str

The string to filter characters out from.

chars

A string of characters to filter out from str.

return:

A version of str with all occurrences of characters contained in chars filtered out.

stripChars( "teststring", "se" ); // Returns "tttring".


StripMLControlChars(string inString)

Strip TorqueML control characters from the specified string, returning a 'clean' version.

Parameters:

inString

String to strip TorqueML control characters from.

// Define the string to strip TorqueML control characters from
%string = "<font:Arial:24>How Now <color:c43c12>Brown <color:000000>Cow";

// Request the stripped version of the string
%strippedString = StripMLControlChars(%string);

return:

Version of the inputted string with all TorqueML characters removed.

see:

References

stripTrailingNumber(string str)

Strip a numeric suffix from the given string.

Parameters:

str

The string from which to strip its numeric suffix.

return:

The string str without its number suffix or the original string str if it has no such suffix.

stripTrailingNumber( "test123" ) // Returns "test".

see:

getTrailingNumber

strIsMatchExpr(string pattern, string str, bool caseSensitive)

Match a pattern against a string.

Parameters:

pattern

The wildcard pattern to match against. The pattern can include characters, '*' to match any number of characters and '?' to match a single character.

str

The string which should be matched against pattern.

caseSensitive

If true, characters in the pattern are matched in case-sensitive fashion against this string. If false, differences in casing are ignored.

return:

True if str matches the given pattern.

strIsMatchExpr( "f?o*R", "foobar" ) // Returns true.
see:

strIsMatchMultipleExpr

strIsMatchMultipleExpr(string patterns, string str, bool caseSensitive)

Match a multiple patterns against a single string.

Parameters:

patterns

A tab-separated list of patterns. Each pattern can include charaters, '*' to match any number of characters and '?' to match a single character. Each of the patterns is tried in turn.

str

The string which should be matched against patterns.

caseSensitive

If true, characters in the pattern are matched in case-sensitive fashion against this string. If false, differences in casing are ignored.

return:

True if str matches any of the given patterns.

strIsMatchMultipleExpr( "*.cs *.gui *.mis", "mymission.mis" ) // Returns true.
see:

strIsMatchExpr

strlen(string str)

Get the length of the given string in bytes.

note:

This does not return a true character count for strings with multi-byte characters!

Parameters:
str

A string.

return:

The length of the given string in bytes.

strlenskip(string str, string first, string last)

Calculate the length of a string in characters, skipping everything between and including first and last.

Parameters:

str

A string.

first

First character to look for to skip block of text.

last

Second character to look for to skip block of text.

return:

The length of the given string skipping blocks of text between characters.

strlwr(string str)

Return an all lower-case version of the given string.

Parameters:

str

A string.

return:

A version of str with all characters converted to lower-case.

strlwr( "TesT1" ) // Returns "test1"
see:

strupr

strnatcmp(string str1, string str2)

Compares two strings using "natural order" case-sensitive comparison.

Natural order means that rather than solely comparing single character code values, strings are ordered in a natural way. For example, the string "hello10" is considered greater than the string "hello2" even though the first numeric character in "hello10" actually has a smaller character value than the corresponding character in "hello2". However, since 10 is greater than 2, strnatcmp will put "hello10" after "hello2". Parameters:

str1

The first string.

str2

The second string.

return:

0 if the strings are equal, a value >0 if str1 comes after str2 in a natural order, and a value <0 if str1 comes before str2 in a natural order.

// Bubble sort 10 elements of %array using natural order
do
{
   %swapped = false;
   for( %i = 0; %i < 10 - 1; %i ++ )
      if( strnatcmp( %array[ %i ], %array[ %i + 1 ] ) > 0 )
      {
         %temp = %array[ %i ];
         %array[ %i ] = %array[ %i + 1 ];
         %array[ %i + 1 ] = %temp;
         %swapped = true;
      }
}
while( %swapped );
see:

strcmp

see:

strinatcmp

strpos(string haystack, string needle, int offset)

Find the start of needle in haystack searching from left to right beginning at the given offset.

Parameters:

haystack

The string to search.

needle

The string to search for.

return:

The index at which the first occurrence of needle was found in haystack or -1 if no match was found.

strpos( "b ab", "b", 1 ) // Returns 3.


strposr(string haystack, string needle, int offset)

Find the start of needle in haystack searching from right to left beginning at the given offset.

Parameters:

haystack

The string to search.

needle

The string to search for.

return:

The index at which the first occurrence of needle was found in heystack or -1 if no match was found.

strposr( "b ab", "b", 1 ) // Returns 2.


strrchr(string str, string chr)

Find the last occurrence of the given character in str.

Parameters:

str

The string to search.

chr

The character to search for. Only the first character from the string is taken.

return:

The remainder of the input string starting with the given character or the empty string if the character could not be found.

see:

strchr

strrchrpos(string str, string chr, int start)

Find the last occurrence of the given character in the given string.

Parameters:

str

The string to search.

chr

The character to look for. Only the first character of this string will be searched for.

start

The index into str at which to start searching for the given character.

return:

The index of the last occurrence of chr in str or -1 if str does not contain the given character.

strrchrpos( "test", "t" ) // Returns 3.


strrepeat(string str, int numTimes, string delimiter)

Return a string that repeats str numTimes number of times delimiting each occurrence with delimiter.

Parameters:

str

The string to repeat multiple times.

numTimes

The number of times to repeat str in the result string.

delimiter

The string to put between each repetition of str.

return:

A string containing str repeated numTimes times.

strrepeat( "a", 5, "b" ) // Returns "ababababa".


strreplace(string source, string from, string to)

Replace all occurrences of from in source with to.

Parameters:

source

The string in which to replace the occurrences of from.

from

The string to replace in source.

to

The string with which to replace occurrences of @from.

return:

A string with all occurrences of from in source replaced by to.

strreplace( "aabbccbb", "bb", "ee" ) // Returns "aaeeccee".


strstr(string string, string substring)

Find the start of substring in the given string searching from left to right.

Parameters:

string

The string to search.

substring

The string to search for.

return:

The index into string at which the first occurrence of substring was found or -1 if substring could not be found.

strstr( "abcd", "c" ) // Returns 2.


strToggleCaseToWords(string str)

Parse a Toggle Case word into separate words.

Parameters:

str

The string to parse.

return:

new string space separated.

strToggleCaseToWords( "HelloWorld" ) // Returns "Hello World".


strToPlayerName(string ptr)

strToPlayerName(string);

strupr(string str)

Return an all upper-case version of the given string.

Parameters:

str

A string.

return:

A version of str with all characters converted to upper-case.

strupr( "TesT1" ) // Returns "TEST1"
see:

strlwr

SubtractRotation(RotationF a, RotationF b)

Subtracts two rotations.

Parameters:

a

Rotation one.

b

Rotation two.

return:

v difference of both rotations.

TamlRead(string filename, string format)

Read an object from a file using Taml.

Parameters:

filename

The filename to read from.

format

The file format to use. Optional: Defaults to 'xml'. Can be set to 'binary'.

return:

(Object) The object read from the file or an empty string if read failed.

TamlWrite(SimObject simObject, string filename, string format, bool compressed)

Writes an object to a file using Taml.

Parameters:

object

The object to write.

filename

The filename to write to.

format

The file format to use. Optional: Defaults to 'xml'. Can be set to 'binary'.

compressed

Whether ZIP compression is used on binary formatting or not. Optional: Defaults to 'true'.

return:

Whether the write was successful or not.

telnetSetParameters(int port, string consolePass, string listenPass, bool remoteEcho)

Initializes and open the telnet console.

Parameters:

port

Port to listen on for console connections (0 will shut down listening).

consolePass

Password for read/write access to console.

listenPass

Password for read access to console.

remoteEcho

[optional] Enable echoing back to the client, off by default.

touchDataBlocks()

Called after a series of datablocks are reloaded to trigger some important actions on the reloaded datablocks.

trace(bool enable)

Enable or disable tracing in the script code VM.

When enabled, the script code runtime will trace the invocation and returns from all functions that are called and log them to the console. This is helpful in observing the flow of the script program.

Parameters:

enable

New setting for script trace execution, on by default.

trim(string str)

Remove leading and trailing whitespace from the string.

Parameters:

str

A string.

return:

A string that is the same as str but with any leading (i.e. leftmost) and trailing (i.e. rightmost) whitespace removed.

trim( "   string  " ); // Returns "string".


tsUpdateImposterImages(bool forceUpdate)

tsUpdateImposterImages( bool forceupdate )

unregisterMessageListener(string queueName, string listenerName)

Unregisters an event message.

Parameters:

queueName

String containing the name of queue

listener

Name of event messenger

unregisterMessageQueue(string queueName)

Unregisters a dispatcher queue.

Parameters:

queueName

String containing the name of queue

validateMemory()

Used to validate memory space for the game.

VectorAdd(VectorF a, VectorF b)

Add two vectors.

Parameters:

a

The first vector.

b

The second vector.

return:

The vector a + b.

//-----------------------------------------------------------------------------
//
// VectorAdd( %a, %b );
//
// The sum of vector a, (ax, ay, az), and vector b, (bx, by, bz) is:
//
//     a + b = ( ax + bx, ay + by, az + bz )
//
//-----------------------------------------------------------------------------
%a = "1 0 0";
%b = "0 1 0";

// %r = "( 1 + 0, 0 + 1, 0 + 0 )";
// %r = "1 1 0";
%r = VectorAdd( %a, %b );


VectorCross(VectorF a, VectorF b)

Calculcate the cross product of two vectors.

Parameters:

a

The first vector.

b

The second vector.

return:

The cross product x b.

//-----------------------------------------------------------------------------
//
// VectorCross( %a, %b );
//
// The cross product of vector a, (ax, ay, az), and vector b, (bx, by, bz), is
//
//     a x b = ( ( ay * bz ) - ( az * by ), ( az * bx ) - ( ax * bz ), ( ax * by ) - ( ay * bx ) )
//
//-----------------------------------------------------------------------------

%a = "1 1 0";
%b = "2 0 1";

// %r = "( ( 1 * 1 ) - ( 0 * 0 ), ( 0 * 2 ) - ( 1 * 1 ), ( 1 * 0 ) - ( 1 * 2 ) )";
// %r = "1 -1 -2";
%r = VectorCross( %a, %b );


VectorDist(VectorF a, VectorF b)

Compute the distance between two vectors.

Parameters:

a

The first vector.

b

The second vector.

return:

The length( b - a ).

//-----------------------------------------------------------------------------
//
// VectorDist( %a, %b );
//
// The distance between vector a, (ax, ay, az), and vector b, (bx, by, bz), is
//
//     a -> b = ||( b - a )||
//            = ||( bx - ax, by - ay, bz - az )||
//            = mSqrt( ( bx - ax ) * ( bx - ax ) + ( by - ay ) * ( by - ay ) + ( bz - az ) * ( bz - az ) )
//
//-----------------------------------------------------------------------------

%a = "1 1 0";
%b = "2 0 1";

// %r = mSqrt( ( 2 - 1 ) * ( 2 - 1) + ( 0 - 1 ) * ( 0 - 1 ) + ( 1 - 0 ) * ( 1 - 0 ) );
// %r = mSqrt( 3 );
%r = VectorDist( %a, %b );


VectorDiv(VectorF a, VectorF b)

Divide two vectors.

Parameters:

a

The first vector.

b

The second vector.

return:

The vector a / b.

//-----------------------------------------------------------------------------
//
// VectorDiv( %a, %b );
//
// The division of vector a, (ax, ay, az), and vector b, (bx, by, bz) is:
//
//     a * b = ( ax / bx, ay / by, az / bz )
//
//-----------------------------------------------------------------------------

%a = "1 1 1";
%b = "2 2 2";

// %r = "( 1 / 2, 1 / 2, 1 / 2 )";
// %r = "0.5 0.5 0.5";
%r = VectorDiv( %a, %b );


VectorDot(VectorF a, VectorF b)

Compute the dot product of two vectors.

Parameters:

a

The first vector.

b

The second vector.

return:

The dot product a * b.

//-----------------------------------------------------------------------------
//
// VectorDot( %a, %b );
//
// The dot product between vector a, (ax, ay, az), and vector b, (bx, by, bz), is:
//
//     a . b = ( ax * bx + ay * by + az * bz )
//
//-----------------------------------------------------------------------------

%a = "1 1 0";
%b = "2 0 1";

// %r = "( 1 * 2 + 1 * 0 + 0 * 1 )";
// %r = 2;
%r = VectorDot( %a, %b );


VectorLen(VectorF v)

Calculate the magnitude of the given vector.

Parameters:

v

A vector.

return:

The length of vector v.

//-----------------------------------------------------------------------------
//
// VectorLen( %a );
//
// The length or magnitude of  vector a, (ax, ay, az), is:
//
//     ||a|| = Sqrt( ax * ax + ay * ay + az * az )
//
//-----------------------------------------------------------------------------

%a = "1 1 0";

// %r = mSqrt( 1 * 1 + 1 * 1 + 0 * 0 );
// %r = mSqrt( 2 );
// %r = 1.414;
%r = VectorLen( %a );


VectorLerp(VectorF a, VectorF b, float t)

Linearly interpolate between two vectors by t.

Parameters:

a

Vector to start interpolation from.

b

Vector to interpolate to.

t

Interpolation factor (0-1). At zero, a is returned and at one, b is returned. In between, an interpolated vector between a and b is returned.

return:

An interpolated vector between a and b.

//-----------------------------------------------------------------------------
//
// VectorLerp( %a, %b );
//
// The point between vector a, (ax, ay, az), and vector b, (bx, by, bz), which is
// weighted by the interpolation factor, t, is
//
//     r = a + t * ( b - a )
//       = ( ax + t * ( bx - ax ), ay + t * ( by - ay ), az + t * ( bz - az ) )
//
//-----------------------------------------------------------------------------

%a = "1 1 0";
%b = "2 0 1";
%v = "0.25";

// %r = "( 1 + 0.25 * ( 2 - 1 ), 1 + 0.25 * ( 0 - 1 ), 0 + 0.25 * ( 1 - 0 ) )";
// %r = "1.25 0.75 0.25";
%r = VectorLerp( %a, %b );


VectorMidPoint(VectorF a, VectorF b)

Gets the midpoint between the two vectors.

Parameters:

a

The first vector.

b

The second vector.

return:

The vector (a + b) / 2.

//-----------------------------------------------------------------------------
//
// VectorMidPoint( %a, %b );
//
// The midpoint of vector a, (ax, ay, az), and vector b, (bx, by, bz) is:
//
//     (a + b)/2 = ( (ax + bx) /2, ay + by) /2, (az + bz) /2 )
//
//-----------------------------------------------------------------------------


VectorMul(VectorF a, VectorF b)

Multiplies two vectors.

Parameters:

a

The first vector.

b

The second vector.

return:

The vector a * b.

//-----------------------------------------------------------------------------
//
// VectorMul( %a, %b );
//
// The multiplication of vector a, (ax, ay, az), and vector b, (bx, by, bz) is:
//
//     a * b = ( ax * bx, ay * by, az * bz )
//
//-----------------------------------------------------------------------------

%a = "1 0 0";
%b = "0 1 0";

// %r = "( 1 * 0, 0 * 1, 0 * 0 )";
// %r = "0 0 0";
%r = VectorMul( %a, %b );


VectorNormalize(VectorF v)

Brings a vector into its unit form, i.e. such that it has the magnitute 1.

Parameters:

v

The vector to normalize.

return:

The vector v scaled to length 1.

//-----------------------------------------------------------------------------
//
// VectorNormalize( %a );
//
// The normalized vector a, (ax, ay, az), is:
//
//     a^ = a / ||a||
//        = ( ax / ||a||, ay / ||a||, az / ||a|| )
//
//-----------------------------------------------------------------------------

%a = "1 1 0";
%l = 1.414;

// %r = "( 1 / 1.141, 1 / 1.141, 0 / 1.141 )";
// %r = "0.707 0.707 0";
%r = VectorNormalize( %a );


VectorOrthoBasis(AngAxisF aa)

Create an orthogonal basis from the given vector.

Parameters:

aaf

The vector to create the orthogonal basis from.

return:

A matrix representing the orthogonal basis.

VectorReflect(VectorF vec, VectorF normal)

Compute the reflection of a vector based on a normal.

Parameters:

a

The vector.

b

The normal.

return:

The reflected vector.

VectorRot(Point3F v, float angle)

rotate a vector in 2d

VectorScale(VectorF a, float scalar)

Scales a vector by a scalar.

Parameters:

a

The vector to scale.

scalar

The scale factor.

return:

The vector a * scalar.

//-----------------------------------------------------------------------------
//
// VectorScale( %a, %v );
//
// Scaling vector a, (ax, ay, az), but the scalar, v, is:
//
//     a * v = ( ax * v, ay * v, az * v )
//
//-----------------------------------------------------------------------------

%a = "1 1 0";
%v = "2";

// %r = "( 1 * 2, 1 * 2, 0 * 2 )";
// %r = "2 2 0";
%r = VectorScale( %a, %v );


VectorSub(VectorF a, VectorF b)

Subtract two vectors.

Parameters:

a

The first vector.

b

The second vector.

return:

The vector a - b.

//-----------------------------------------------------------------------------
//
// VectorSub( %a, %b );
//
// The difference of vector a, (ax, ay, az), and vector b, (bx, by, bz) is:
//
//     a - b = ( ax - bx, ay - by, az - bz )
//
//-----------------------------------------------------------------------------

%a = "1 0 0";
%b = "0 1 0";

// %r = "( 1 - 0, 0 - 1, 0 - 0 )";
// %r = "1 -1 0";
%r = VectorSub( %a, %b );


warn(string message...)

Logs a warning message to the console.

Concatenates all given arguments to a single string and prints the string to the console as a warning message (in the in-game console, these will show up using a turquoise font by default). A newline is added automatically after the text.

Parameters:

message

Any number of string arguments.

warnThru(string passthru, string text...)

Like warn(), but first argument is returned.

wasSyntaxError()

Returns true if script compiler had a syntax error. Useful for detecting syntax errors after reloading a script.

weekdayNumToStr(int num, bool abbreviate)

returns weekday as a word given a number or "" if number is bad

return:

weekday as a word given a number or "" if number is bad

writeFontCache()

Force all cached fonts to serialize themselves to the cache.

    1
    2/*!
    3@class EditorIconRegistry
    4@brief This class is used to find the correct icon file path for different SimObject class types.
    5
    6It is typically used by the editors, not intended for actual game development
    7
    8@internal*/
    9
   10/*!
   11@defgroup Decals
   12@brief Decals are non-SimObject derived objects that are stored and loaded separately from the normal mission file.
   13
   14The DecalManager handles all aspects of decal management including loading, creation, saving, and automatically deleting decals that have exceeded their lifeSpan.
   15
   16The static decals associated with a mission are normally loaded immediately after the mission itself has loaded as shown below.
   17@tsexample
   18// Load the static mission decals.
   19decalManagerLoad( %missionName @ ".decals" );
   20@endtsexample
   21@ingroup FX
   22*/
   23
   24/*!
   25@class PfxVis
   26@brief Singleton class that exposes ConsoleStaticFunctions for debug visualizing PostEffects.
   27
   28@tsexample
   29// Script interface...
   30PfxVis::open( PostEffect ) // Multiple PostEffects can be visualized at the same time
   31PfxVis::clear()      // Clear all visualizer windows
   32PfxVis::hide()       // Hide all windows (are not destroyed)
   33PfxVis::show()
   34@endtsexample
   35
   36@ingroup GFX
   37*/
   38
   39/*!
   40@brief Takes a world point and find the "highest" terrain underneath it
   41
   42@param x The X coordinate in world space
   43@param y The Y coordinate in world space
   44
   45@return Returns the closest terrain height below the given point as an F32 value.
   46
   47@ingroup Terrain*/
   48
   49bool getTerrainHeightBelowPosition( F32 x, F32 y);
   50/*!
   51@brief Takes a world point and find the "highest" terrain underneath it
   52
   53@param position The world space point, minus the z (height) value. Formatted as ("x y")
   54
   55@return Returns the closest terrain height below the given point as an F32 value.
   56
   57@ingroup Terrain*/
   58
   59bool getTerrainHeightBelowPosition( Point2I position );
   60/*!
   61@brief Gets the terrain height at the specified position
   62
   63@param x The X coordinate in world space
   64@param y The Y coordinate in world space
   65
   66@return Returns the terrain height at the given point as an F32 value.
   67
   68@ingroup Terrain*/
   69
   70bool getTerrainHeight( F32 x, F32 y);
   71/*!
   72@brief Gets the terrain height at the specified position
   73
   74@param position The world space point, minus the z (height) value. Formatted as ("x y")
   75
   76@return Returns the terrain height at the given point as an F32 value.
   77
   78@ingroup Terrain*/
   79
   80bool getTerrainHeight( Point2I position );
   81/*!
   82@brief Takes a world point and find the "highest" terrain underneath it
   83
   84@param x The X coordinate in world space
   85@param y The Y coordinate in world space
   86
   87@param z The Z coordinate in world space
   88
   89@return Returns the ID of the requested terrain block (0 if not found).
   90
   91@ingroup Terrain*/
   92
   93bool getTerrainUnderWorldPoint( F32 x, F32 y, F32 z);
   94/*!
   95@brief Gets the terrain block that is located under the given world point
   96
   97@param position The world space coordinate you wish to query at. Formatted as ("x y z")
   98
   99@return Returns the ID of the requested terrain block (0 if not found).
  100
  101@ingroup Terrain*/
  102
  103bool getTerrainUnderWorldPoint( Point3F position );
  104/*!
  105@class GFXInit
  106@ingroup GFX
  107@brief Functions for tracking GFX adapters and initializing them into devices.
  108*/
  109
  110/*!
  111@class GFXCardProfilerAPI
  112@brief This class is the interface between TorqueScript and GFXCardProfiler.
  113
  114You will not actually declare GFXCardProfilerAPI in TorqueScript. It exists solely to give access to the GFXCardProfiler's querying functions, such as GFXCardProfiler::getRenderer.
  115
  116@tsexample
  117// Example of accessing GFXCardProfiler function from script
  118// Notice you are not using the API version
  119%videoMem = GFXCardProfiler::getVideoMemoryMB();
  120@endtsexample
  121
  122@see GFXCardProfiler for more information
  123
  124@ingroup GFX
  125*/
  126
  127/*!
  128@class ScriptMsgListener
  129@brief Script accessible version of Dispatcher::IMessageListener. Often used in conjunction with EventManager
  130
  131The main use of ScriptMsgListener is to allow script to listen formessages. You can subclass ScriptMsgListener in script to receivethe Dispatcher::IMessageListener callbacks.
  132
  133Alternatively, you can derive from it in C++ instead of SimObject toget an object that implements Dispatcher::IMessageListener with scriptcallbacks. If you need to derive from something other then SimObject,then you will need to implement the Dispatcher::IMessageListenerinterface yourself.
  134
  135@tsexample
  136// Create the EventManager.
  137$MyEventManager = new EventManager() { queue = "MyEventManager"; };
  138
  139// Create an event.
  140$MyEventManager.registerEvent( "SomeCoolEvent" );
  141
  142// Create a listener and subscribe.
  143$MyListener = new ScriptMsgListener() { class = MyListener; };
  144$MyEventManager.subscribe( $MyListener, "SomeCoolEvent" );
  145
  146function MyListener::onSomeCoolEvent( %this, %data )
  147{
  148   echo( "onSomeCoolEvent Triggered" );
  149}
  150
  151// Trigger the event.
  152$MyEventManager.postEvent( "SomeCoolEvent", "Data" );
  153@endtsexample
  154
  155@ingroup Messaging
  156*/
  157
  158/*!
  159@brief Global function used for spawning any type of object.
  160
  161Note: This is separate from SpawnSphere::spawnObject(). This function is not called off any other class and uses different parameters than the SpawnSphere's function. In the source, SpawnSphere::spawnObject() actually calls this function and passes its properties (spawnClass, spawnDatablock, etc).
  162
  163@param class Mandatory field specifying the object class, such as Player or TSStatic.
  164
  165@param datablock Field specifying the object's datablock, optional for objects such as TSStatic, mandatory for game objects like Player.
  166
  167@param name Optional field specifying a name for this instance of the object.
  168
  169@param properties Optional set of parameters applied to the spawn object during creation.
  170
  171@param script Optional command(s) to execute when spawning an object.
  172
  173@tsexample
  174// Set the parameters for the spawn function
  175%objectClass = "Player";
  176%objectDatablock = "DefaultPlayerData";
  177%objectName = "PlayerName";
  178%additionalProperties = "health = \"0\";"; // Note the escape sequence \ in front of quotes
  179%spawnScript = "echo(\"Player Spawned\");" // Note the escape sequence \ in front of quotes
  180// Spawn with the engine's Sim::spawnObject() function
  181%player = spawnObject(%objectClass, %objectDatablock, %objectName, %additionalProperties, %spawnScript);
  182@endtsexample
  183
  184@ingroup Game*/
  185
  186bool spawnObject(class [, dataBlock, name, properties, script]);
  187/*!
  188@brief Create a new temporary SFXProfile from the given @a description and @a filename, then create a play-once source for it and start playback.  Position the source's 3D sound at the given coordinates (only if the description is set up for 3D sound).
  189
  190Once playback has finished, the source will be automatically deleted in the next sound system update.  If not referenced otherwise by then, the temporary SFXProfile will also be deleted.
  191@param description The description to use for playback.
  192@param filename Path to the sound file to play.
  193@param x The X coordinate of the 3D sound position.
  194@param y The Y coordinate of the 3D sound position.
  195@param z The Z coordinate of the 3D sound position.
  196@param fadeInTime If >=0, this overrides the SFXDescription::fadeInTime value on the track's description.
  197@return A newly created temporary source in "Playing" state or 0 if the operation failed.
  198
  199@tsexample
  200// Play a sound effect file once using a 3D sound with a default falloff placed at the origin.
  201sfxPlayOnce( AudioDefault3D, "art/sound/weapons/Weapon_pickup", 0, 0, 0 );
  202@endtsexample
  203
  204@ref SFXSource_playonce
  205
  206@ingroup SFX*/
  207
  208SFXSource sfxPlayOnce( SFXDescription description, string filename, float x, float y, float z, float fadeInTime=-1 );
  209/*!
  210@brief Create a new temporary SFXProfile from the given @a description and @a filename, then create a play-once source for it and start playback.
  211
  212Once playback has finished, the source will be automatically deleted in the next sound system update.  If not referenced otherwise by then, the temporary SFXProfile will also be deleted.
  213@param description The description to use for playback.
  214@param filename Path to the sound file to play.
  215@return A newly created temporary source in "Playing" state or 0 if the operation failed.
  216
  217@tsexample
  218// Play a sound effect file once.
  219sfxPlayOnce( AudioEffects, "art/sound/weapons/Weapon_pickup" );
  220@endtsexample
  221
  222@ref SFXSource_playonce
  223
  224@ingroup SFX*/
  225
  226SFXSource sfxPlayOnce( SFXDescription description, string filename );
  227/*!
  228@brief Create a play-once source for the given given @a track and position the source's 3D sound at the given coordinates only if the track's description is set up for 3D sound).
  229
  230Once playback has finished, the source will be automatically deleted in the next sound system update.
  231@param track The sound datablock.
  232@param x The X coordinate of the 3D sound position.
  233@param y The Y coordinate of the 3D sound position.
  234@param z The Z coordinate of the 3D sound position.
  235@param fadeInTime If >=0, this overrides the SFXDescription::fadeInTime value on the track's description.
  236@return A newly created temporary source in "Playing" state or 0 if the operation failed.
  237
  238@tsexample
  239// Immediately start playing the given track.  Fade it in to full volume over 5 seconds.
  240sfxPlayOnce( MusicTrack, 0, 0, 0, 5.f );
  241@endtsexample
  242
  243@ref SFXSource_playonce
  244
  245@ingroup SFX*/
  246
  247SFXSource sfxPlayOnce( SFXTrack track, float x, float y, float z, float fadeInTime=-1 );
  248/*!
  249@brief Create a play-once source for the given @a track.
  250
  251Once playback has finished, the source will be automatically deleted in the next sound system update.
  252@param track The sound datablock.
  253@return A newly created temporary source in "Playing" state or 0 if the operation failed.
  254
  255@ref SFXSource_playonce
  256
  257@ingroup SFX*/
  258
  259SFXSource sfxPlayOnce( SFXTrack track );
  260/*!
  261@brief Create a new play-once source for the given @a track, position its 3D sound at the given coordinates (if the track's description is set up for 3D sound) and start playback of the source.
  262
  263This is equivalent to calling sfxCreateSource() on @track and SFXSource::play() on the resulting source.
  264
  265@param track The sound datablock to play.
  266
  267@param x The X coordinate of the 3D sound position.
  268@param y The Y coordinate of the 3D sound position.
  269@param z The Z coordinate of the 3D sound position.
  270@return The newly created play-once source or 0 if the creation failed.
  271
  272@ref SFXSource_playonce
  273
  274@ingroup SFX*/
  275
  276void sfxPlay( SFXTrack track, float x, float y, float z );
  277/*!
  278@brief Create a new play-once source for the given @a track and start playback of the source.
  279
  280This is equivalent to calling sfxCreateSource() on @track and SFXSource::play() on the resulting source.
  281
  282@param track The sound datablock to play.
  283
  284@return The newly created play-once source or 0 if the creation failed.
  285
  286@ref SFXSource_playonce
  287
  288@ingroup SFX*/
  289
  290void sfxPlay( SFXTrack track );
  291/*!
  292@brief Start playback of the given source.
  293
  294This is the same as calling SFXSource::play() directly.
  295
  296@param source The source to start playing.
  297
  298@return @a source.
  299
  300@tsexample
  301// Create and play a source from a pre-existing profile:
  302%source = sfxCreateSource( SoundFileProfile );
  303%source.play();
  304@endtsexample
  305
  306@ingroup SFX*/
  307
  308SFXSource sfxPlay( SFXSource source );
  309/*!
  310@brief Create a temporary SFXProfile from the given @a description and @a filename and then create and return a new source that plays the profile. Position the sound source at the given coordinates (if it is a 3D sound).
  311
  312The source will be returned in stopped state.  Call SFXSource::play() to start playback.
  313
  314In contrast to play-once sources, the source object will not be automatically deleted once playback stops. Call delete() to release the source object.
  315
  316@param description The description to use for setting up the temporary SFXProfile.
  317@param filename Path to the sound file to play.
  318@param x The X coordinate of the 3D sound position.
  319@param y The Y coordinate of the 3D sound position.
  320@param z The Z coordinate of the 3D sound position.
  321@return A new SFXSource for playback of the given track or 0 if no source or no temporary profile could be created.
  322
  323@tsexample
  324// Create a source for a music track and position it at (100, 200, 300):
  325%source = sfxCreateSource( AudioMusicLoop3D, "art/sound/backgroundMusic", 100, 200, 300 );
  326%source.play();
  327@endtsexample
  328
  329@see SFXProfile
  330
  331@ingroup SFX*/
  332
  333SFXSound sfxCreateSource( SFXDescription description, string filename, float x, float y, float z );
  334/*!
  335@brief Create a temporary SFXProfile from the given @a description and @a filename and then create and return a new source that plays the profile.
  336
  337The source will be returned in stopped state.  Call SFXSource::play() to start playback.
  338
  339In contrast to play-once sources, the source object will not be automatically deleted once playback stops. Call delete() to release the source object.
  340
  341@param description The description to use for setting up the temporary SFXProfile.
  342@param filename Path to the sound file to play.
  343@return A new SFXSource for playback of the given track or 0 if no source or no temporary profile could be created.
  344
  345@tsexample
  346// Create a source for a music track:
  347%source = sfxCreateSource( AudioMusicLoop2D, "art/sound/backgroundMusic" );
  348%source.play();
  349@endtsexample
  350
  351@see SFXProfile
  352
  353@ingroup SFX*/
  354
  355SFXSound sfxCreateSource( SFXDescription description, string filename );
  356/*!
  357@brief Create a new source that plays the given track and position its 3D sounds source at the given coordinates (if it is a 3D sound).
  358
  359The source will be returned in stopped state.  Call SFXSource::play() to start playback.
  360
  361In contrast to play-once sources, the source object will not be automatically deleted once playback stops. Call delete() to release the source object.
  362
  363This function will automatically create the right SFXSource type for the given SFXTrack.
  364
  365@param track The track the source should play.
  366@param x The X coordinate of the 3D sound position.
  367@param y The Y coordinate of the 3D sound position.
  368@param z The Z coordinate of the 3D sound position.
  369@return A new SFXSource for playback of the given track or 0 if no source could be created from the given track.
  370
  371@note Trying to create a source for a device-specific track type will fail if the currently selected device does not support the type.  Example: trying to create a source for an FMOD Designer event when not running FMOD.
  372
  373@tsexample
  374// Create and play a source from a pre-existing profile and position it at (100, 200, 300):
  375%source = sfxCreateSource( SoundFileProfile, 100, 200, 300 );
  376%source.play();
  377@endtsexample
  378
  379@ingroup SFX*/
  380
  381SFXSource sfxCreateSource( SFXTrack track, float x, float y, float z );
  382/*!
  383@brief Create a new source that plays the given track.
  384
  385The source will be returned in stopped state.  Call SFXSource::play() to start playback.
  386
  387In contrast to play-once sources, the source object will not be automatically deleted once playback stops. Call delete() to release the source object.
  388
  389This function will automatically create the right SFXSource type for the given SFXTrack.
  390
  391@param track The track the source should play.
  392@return A new SFXSource for playback of the given track or 0 if no source could be created from the given track.
  393
  394@note Trying to create a source for a device-specific track type will fail if the currently selected device does not support the type.  Example: trying to create a source for an FMOD Designer event when not running FMOD.
  395
  396@tsexample
  397// Create and play a source from a pre-existing profile:
  398%source = sfxCreateSource( SoundFileProfile );
  399%source.play();
  400@endtsexample
  401
  402@ingroup SFX*/
  403
  404SFXSource sfxCreateSource( SFXTrack track );
  405/*!
  406@class BanList
  407@ingroup Miscellaneous
  408@brief Used for kicking and banning players from a server.
  409There is only a single instance of BanList. It is very important to note that you do not ever create this object in script like you would other game play objects. You simply reference it via namespace.
  410
  411For this to be used effectively, make sure you are hooking up other functions to BanList. For example, functions like GameConnection::onConnectRequestRejected( %this, %msg ) and function GameConnection::onConnectRequest are excellent places to make use of the BanList. Other systems can be used in conjunction for strict control over a server
  412
  413@see addBadWord
  414@see containsBadWords
  415*/
  416
  417/*!
  418
  419@ingroup UNDOCUMENTED
  420*/
  421enum VPathObjectOrientationType {
  422/*!
  423*/
  424FREE,
  425/*!
  426*/
  427INTERPOLATE,
  428/*!
  429*/
  430TOPATH,
  431/*!
  432*/
  433TOOBJECT,
  434/*!
  435*/
  436TOPOINT,
  437};
  438/*!
  439
  440@ingroup UNDOCUMENTED
  441*/
  442enum VPathNodeOrientationType {
  443/*!
  444*/
  445FREE,
  446/*!
  447*/
  448TOPOINT,
  449};
  450/*!
  451
  452@ingroup UNDOCUMENTED
  453*/
  454enum VPathEditorMode {
  455/*!
  456*/
  457GIZMO,
  458/*!
  459*/
  460ADDNODE,
  461/*!
  462*/
  463DELETENODE,
  464};
  465/*!
  466
  467@ingroup UNDOCUMENTED
  468*/
  469enum VPathType {
  470/*!
  471*/
  472BEZIER,
  473/*!
  474*/
  475LINEAR,
  476};
  477/*!
  478
  479@ingroup UNDOCUMENTED
  480*/
  481enum VScriptEventCommandType {
  482/*!
  483*/
  484EXPRESSION,
  485/*!
  486*/
  487METHOD,
  488};
  489/*!
  490
  491@ingroup UNDOCUMENTED
  492*/
  493enum VDataTableDataType {
  494/*!
  495*/
  496EXPRESSION,
  497/*!
  498*/
  499STATIC,
  500/*!
  501*/
  502VARIABLE,
  503};
  504/*!
  505
  506@ingroup UNDOCUMENTED
  507*/
  508enum VActionToggle {
  509/*!
  510*/
  511ON,
  512/*!
  513*/
  514OFF,
  515};
  516/*!
  517@brief The method used to include water surfaces in the NavMesh.
  518
  519
  520@ingroup UNDOCUMENTED
  521*/
  522enum NavMeshWaterMethod {
  523/*!
  524@brief Ignore all water surfaces.
  525
  526*/
  527Ignore,
  528/*!
  529@brief Treat water surfaces as solid and walkable.
  530
  531*/
  532Solid,
  533/*!
  534@brief Treat water as an impassable obstacle.
  535
  536*/
  537Impassable,
  538};
  539/*!
  540@brief The size of a cover point.
  541
  542
  543@ingroup UNDOCUMENTED
  544*/
  545enum CoverPointSize {
  546/*!
  547@brief Only provides cover when prone.
  548
  549*/
  550Prone,
  551/*!
  552@brief Only provides cover when crouching.
  553
  554*/
  555Crouch,
  556/*!
  557@brief Provides cover when standing.
  558
  559*/
  560Stand,
  561};
  562/*!
  563@brief Possible wave operation types.
  564
  565@ingroup afxXM_WaveBase
  566
  567*/
  568enum afxXM_WaveOpType {
  569/*!
  570@brief ...
  571
  572*/
  573add,
  574/*!
  575@brief ...
  576
  577*/
  578multiply,
  579/*!
  580@brief ...
  581
  582*/
  583replace,
  584/*!
  585@brief ...
  586
  587*/
  588mult,
  589};
  590/*!
  591@brief Possible wave parameter types.
  592
  593@ingroup afxXM_WaveBase
  594
  595*/
  596enum afxXM_WaveParamType {
  597/*!
  598@brief ...
  599
  600*/
  601none,
  602/*!
  603@brief ...
  604
  605*/
  606pos,
  607/*!
  608@brief ...
  609
  610*/
  611pos.x,
  612/*!
  613@brief ...
  614
  615*/
  616pos.y,
  617/*!
  618@brief ...
  619
  620*/
  621pos.z,
  622/*!
  623@brief ...
  624
  625*/
  626ori,
  627/*!
  628@brief ...
  629
  630*/
  631pos2,
  632/*!
  633@brief ...
  634
  635*/
  636pos2.x,
  637/*!
  638@brief ...
  639
  640*/
  641pos2.y,
  642/*!
  643@brief ...
  644
  645*/
  646pos2.z,
  647/*!
  648@brief ...
  649
  650*/
  651scale,
  652/*!
  653@brief ...
  654
  655*/
  656scale.x,
  657/*!
  658@brief ...
  659
  660*/
  661scale.y,
  662/*!
  663@brief ...
  664
  665*/
  666scale.z,
  667/*!
  668@brief ...
  669
  670*/
  671color,
  672/*!
  673@brief ...
  674
  675*/
  676color.red,
  677/*!
  678@brief ...
  679
  680*/
  681color.green,
  682/*!
  683@brief ...
  684
  685*/
  686color.blue,
  687/*!
  688@brief ...
  689
  690*/
  691color.alpha,
  692/*!
  693@brief ...
  694
  695*/
  696vis,
  697/*!
  698@brief ...
  699
  700*/
  701position,
  702/*!
  703@brief ...
  704
  705*/
  706position.x,
  707/*!
  708@brief ...
  709
  710*/
  711position.y,
  712/*!
  713@brief ...
  714
  715*/
  716position.z,
  717/*!
  718@brief ...
  719
  720*/
  721orientation,
  722/*!
  723@brief ...
  724
  725*/
  726position2,
  727/*!
  728@brief ...
  729
  730*/
  731position2.x,
  732/*!
  733@brief ...
  734
  735*/
  736position2.y,
  737/*!
  738@brief ...
  739
  740*/
  741position2.z,
  742/*!
  743@brief ...
  744
  745*/
  746color.r,
  747/*!
  748@brief ...
  749
  750*/
  751color.g,
  752/*!
  753@brief ...
  754
  755*/
  756color.b,
  757/*!
  758@brief ...
  759
  760*/
  761color.a,
  762/*!
  763@brief ...
  764
  765*/
  766visibility,
  767};
  768/*!
  769@brief Possible waveform types.
  770
  771@ingroup afxXM_WaveBase
  772
  773*/
  774enum afxXM_WaveFormType {
  775/*!
  776@brief ...
  777
  778*/
  779none,
  780/*!
  781@brief ...
  782
  783*/
  784sine,
  785/*!
  786@brief ...
  787
  788*/
  789square,
  790/*!
  791@brief ...
  792
  793*/
  794triangle,
  795/*!
  796@brief ...
  797
  798*/
  799sawtooth,
  800/*!
  801@brief ...
  802
  803*/
  804noise,
  805/*!
  806@brief ...
  807
  808*/
  809one,
  810};
  811/*!
  812@brief Possible box conform alignment types.
  813
  814@ingroup afxXM_BoxConform
  815
  816*/
  817enum afxXM_BoxConformType {
  818/*!
  819@brief ...
  820
  821*/
  822+x,
  823/*!
  824@brief ...
  825
  826*/
  827-x,
  828/*!
  829@brief ...
  830
  831*/
  832+y,
  833/*!
  834@brief ...
  835
  836*/
  837-y,
  838/*!
  839@brief ...
  840
  841*/
  842+z,
  843/*!
  844@brief ...
  845
  846*/
  847-z,
  848/*!
  849@brief ...
  850
  851*/
  852x,
  853/*!
  854@brief ...
  855
  856*/
  857y,
  858/*!
  859@brief ...
  860
  861*/
  862z,
  863};
  864/*!
  865@brief Possible loop types for an afxPath.
  866
  867@ingroup afxPath
  868
  869*/
  870enum afxPath3DLoopType {
  871/*!
  872@brief ...
  873
  874*/
  875constant,
  876/*!
  877@brief ...
  878
  879*/
  880cycle,
  881/*!
  882@brief ...
  883
  884*/
  885oscillate,
  886};
  887/*!
  888@brief Possible particle pool types.
  889
  890@ingroup afxParticlePool
  891
  892*/
  893enum afxParticlePool_PoolType {
  894/*!
  895@brief ...
  896
  897*/
  898normal,
  899/*!
  900@brief ...
  901
  902*/
  903two-pass,
  904/*!
  905@brief ...
  906
  907*/
  908twopass,
  909};
  910/*!
  911@brief Possible RPG spell target types.
  912
  913@ingroup afxRPGMagicSpell
  914
  915*/
  916enum afxRPGMagicSpell_TargetType {
  917/*!
  918@brief ...
  919
  920*/
  921nothing,
  922/*!
  923@brief ...
  924
  925*/
  926self,
  927/*!
  928@brief ...
  929
  930*/
  931friend,
  932/*!
  933@brief ...
  934
  935*/
  936enemy,
  937/*!
  938@brief ...
  939
  940*/
  941corpse,
  942/*!
  943@brief ...
  944
  945*/
  946free,
  947};
  948/*!
  949@brief Possible zodiac plane facing types.
  950
  951@ingroup afxZodiacPlane
  952
  953*/
  954enum afxZodiacPlane_FacingType {
  955/*!
  956@brief ...
  957
  958*/
  959up,
  960/*!
  961@brief ...
  962
  963*/
  964down,
  965/*!
  966@brief ...
  967
  968*/
  969forward,
  970/*!
  971@brief ...
  972
  973*/
  974backward,
  975/*!
  976@brief ...
  977
  978*/
  979right,
  980/*!
  981@brief ...
  982
  983*/
  984left,
  985/*!
  986@brief ...
  987
  988*/
  989front,
  990/*!
  991@brief ...
  992
  993*/
  994back,
  995};
  996/*!
  997@brief Possible zodiac blend types.
  998
  999@ingroup afxZodiacPlane
 1000
 1001*/
 1002enum afxZodiacPlane_BlendType {
 1003/*!
 1004@brief ...
 1005
 1006*/
 1007normal,
 1008/*!
 1009@brief ...
 1010
 1011*/
 1012additive,
 1013/*!
 1014@brief ...
 1015
 1016*/
 1017subtractive,
 1018};
 1019/*!
 1020@brief Possible zodiac blend types.
 1021
 1022@ingroup afxZodiac
 1023
 1024*/
 1025enum afxZodiac_BlendType {
 1026/*!
 1027@brief ...
 1028
 1029*/
 1030normal,
 1031/*!
 1032@brief ...
 1033
 1034*/
 1035additive,
 1036/*!
 1037@brief ...
 1038
 1039*/
 1040subtractive,
 1041};
 1042/*!
 1043@brief Possible projectile launch direction types.
 1044
 1045@ingroup afxProjectile
 1046
 1047*/
 1048enum afxProjectile_LaunchDirType {
 1049/*!
 1050@brief ...
 1051
 1052*/
 1053towardPos2Constraint,
 1054/*!
 1055@brief ...
 1056
 1057*/
 1058orientConstraint,
 1059/*!
 1060@brief ...
 1061
 1062*/
 1063launchDirField,
 1064};
 1065/*!
 1066@brief Possible player movement operation types.
 1067
 1068@ingroup afxPlayerMovemen
 1069
 1070*/
 1071enum afxPlayerMovement_OpType {
 1072/*!
 1073@brief ...
 1074
 1075*/
 1076add,
 1077/*!
 1078@brief ...
 1079
 1080*/
 1081multiply,
 1082/*!
 1083@brief ...
 1084
 1085*/
 1086replace,
 1087/*!
 1088@brief ...
 1089
 1090*/
 1091mult,
 1092};
 1093/*!
 1094@brief Possible phrase effect types.
 1095
 1096@ingroup afxPhraseEffect
 1097
 1098*/
 1099enum afxPhraseEffect_PhraseType {
 1100/*!
 1101@brief ...
 1102
 1103*/
 1104triggered,
 1105/*!
 1106@brief ...
 1107
 1108*/
 1109continuous,
 1110};
 1111/*!
 1112@brief Possible phrase effect state types.
 1113
 1114@ingroup afxPhraseEffect
 1115
 1116*/
 1117enum afxPhraseEffect_StateType {
 1118/*!
 1119@brief ...
 1120
 1121*/
 1122on,
 1123/*!
 1124@brief ...
 1125
 1126*/
 1127off,
 1128/*!
 1129@brief ...
 1130
 1131*/
 1132both,
 1133};
 1134/*!
 1135@brief Possible phrase effect match types.
 1136
 1137@ingroup afxPhraseEffect
 1138
 1139*/
 1140enum afxPhraseEffect_MatchType {
 1141/*!
 1142@brief ...
 1143
 1144*/
 1145any,
 1146/*!
 1147@brief ...
 1148
 1149*/
 1150all,
 1151};
 1152/*!
 1153@brief Possible particle emitter path origin types.
 1154
 1155@ingroup afxParticleEmitterPath
 1156
 1157*/
 1158enum afxParticleEmitterPath_OriginType {
 1159/*!
 1160@brief ...
 1161
 1162*/
 1163origin,
 1164/*!
 1165@brief ...
 1166
 1167*/
 1168point,
 1169/*!
 1170@brief ...
 1171
 1172*/
 1173vector,
 1174/*!
 1175@brief ...
 1176
 1177*/
 1178tangent,
 1179};
 1180/*!
 1181@brief Possible blending types.
 1182
 1183@ingroup afxBillboard
 1184
 1185*/
 1186enum afxBillboard_BlendStyle {
 1187/*!
 1188@brief ...
 1189
 1190*/
 1191NORMAL,
 1192/*!
 1193@brief ...
 1194
 1195*/
 1196ADDITIVE,
 1197/*!
 1198@brief ...
 1199
 1200*/
 1201SUBTRACTIVE,
 1202/*!
 1203@brief ...
 1204
 1205*/
 1206PREMULTALPHA,
 1207};
 1208/*!
 1209@brief An enumeration of battery levels of a joystick.
 1210
 1211
 1212@ingroup Input*/
 1213enum SDLPowerEnum {
 1214/*!
 1215*/
 1216Unknown,
 1217/*!
 1218*/
 1219Empty,
 1220/*!
 1221*/
 1222Low,
 1223/*!
 1224*/
 1225Medium,
 1226/*!
 1227*/
 1228Full,
 1229/*!
 1230*/
 1231Wired,
 1232/*!
 1233*/
 1234Max,
 1235};
 1236/*!
 1237@brief The type of device connected.
 1238
 1239
 1240@ingroup Input*/
 1241enum SDLJoystickType {
 1242/*!
 1243*/
 1244Unknown,
 1245/*!
 1246*/
 1247Game Controller,
 1248/*!
 1249*/
 1250Wheel,
 1251/*!
 1252*/
 1253Arcade Stick,
 1254/*!
 1255*/
 1256Flight Stick,
 1257/*!
 1258*/
 1259Dance Pad,
 1260/*!
 1261*/
 1262Guitar,
 1263/*!
 1264*/
 1265Drum Kit,
 1266/*!
 1267*/
 1268Arcade Pad,
 1269/*!
 1270*/
 1271Throttle,
 1272};
 1273/*!
 1274@brief GuiSeparatorCtrl orientations
 1275
 1276
 1277@ingroup GuiControls*/
 1278enum GuiSeparatorType {
 1279/*!
 1280*/
 1281Vertical,
 1282/*!
 1283*/
 1284Horizontal,
 1285};
 1286/*!
 1287@brief The charting style of a single plotting curve in a GuiGraphCtrl.
 1288
 1289
 1290@ingroup GuiValues*/
 1291enum GuiGraphType {
 1292/*!
 1293@brief Plot the curve as a bar chart.
 1294
 1295*/
 1296Bar,
 1297/*!
 1298@brief Plot a filled poly graph that connects the data points on the curve.
 1299
 1300*/
 1301Filled,
 1302/*!
 1303@brief Plot each data point on the curve as a single dot.
 1304
 1305*/
 1306Point,
 1307/*!
 1308@brief Plot straight lines through the data points of the curve.
 1309
 1310*/
 1311PolyLine,
 1312};
 1313/*!
 1314@brief Routine to use for converting Theora's Y'CbCr pixel format to RGB color space.
 1315
 1316
 1317@ingroup GuiImages*/
 1318enum GuiTheoraTranscoder {
 1319/*!
 1320@brief Automatically detect most appropriate setting.
 1321
 1322*/
 1323Auto,
 1324/*!
 1325@brief Slower but beneric transcoder that can convert all Y'CbCr input formats to RGB or RGBA output.
 1326
 1327*/
 1328Generic,
 1329/*!
 1330@brief Fast SSE2-based transcoder with fixed conversion from 4:2:0 Y'CbCr to RGBA.
 1331
 1332*/
 1333SSE2420RGBA,
 1334};
 1335/*!
 1336
 1337@ingroup AdvancedLighting*/
 1338enum ShadowType {
 1339/*!
 1340*/
 1341Spot,
 1342/*!
 1343*/
 1344PSSM,
 1345/*!
 1346*/
 1347DualParaboloidSinglePass,
 1348/*!
 1349*/
 1350DualParaboloid,
 1351/*!
 1352*/
 1353CubeMap,
 1354};
 1355/*!
 1356@brief The shadow filtering modes for Advanced Lighting shadows.
 1357
 1358@ingroup AdvancedLighting*/
 1359enum ShadowFilterMode {
 1360/*!
 1361@brief Simple point sampled filtering.
 1362This is the fastest and lowest quality mode.*/
 1363None,
 1364/*!
 1365@brief A variable tap rotated poisson disk soft shadow filter.
 1366It performs 4 taps to classify the point as in shadow, out of shadow, or along a shadow edge.  Samples on the edge get an additional 8 taps to soften them.*/
 1367SoftShadow,
 1368/*!
 1369@brief A 12 tap rotated poisson disk soft shadow filter.
 1370It performs all the taps for every point without any early rejection.*/
 1371SoftShadowHighQuality,
 1372};
 1373/*!
 1374
 1375@ingroup UNDOCUMENTED
 1376*/
 1377enum _TamlFormatMode {
 1378/*!
 1379*/
 1380xml,
 1381/*!
 1382*/
 1383binary,
 1384};
 1385/*!
 1386@brief Type of mesh data available in a shape.
 1387
 1388@ingroup gameObjects*/
 1389enum ImageAssetType {
 1390/*!
 1391*/
 1392Albedo,
 1393/*!
 1394*/
 1395Normal,
 1396/*!
 1397*/
 1398ORMConfig,
 1399/*!
 1400*/
 1401GUI,
 1402/*!
 1403*/
 1404Roughness,
 1405/*!
 1406*/
 1407AO,
 1408/*!
 1409*/
 1410Metalness,
 1411/*!
 1412*/
 1413Glow,
 1414/*!
 1415*/
 1416Particle,
 1417/*!
 1418*/
 1419Decal,
 1420/*!
 1421*/
 1422Cubemap,
 1423};
 1424/*!
 1425@brief Type of mesh data available in a shape.
 1426
 1427@ingroup gameObjects*/
 1428enum ReflectionModeEnum {
 1429/*!
 1430@brief This probe does not provide any local reflection data
 1431
 1432*/
 1433No Reflections,
 1434/*!
 1435@brief Uses a static CubemapData
 1436
 1437*/
 1438Static Cubemap,
 1439/*!
 1440@brief Uses a cubemap baked from the probe's current position
 1441
 1442*/
 1443Baked Cubemap,
 1444};
 1445/*!
 1446@brief Type of mesh data available in a shape.
 1447
 1448@ingroup gameObjects*/
 1449enum ReflectProbeType {
 1450/*!
 1451@brief Sphere shaped
 1452
 1453*/
 1454Sphere,
 1455/*!
 1456@brief Box shape
 1457
 1458*/
 1459Box,
 1460};
 1461/*!
 1462@brief How the weapons are linked to triggers for this TurretShape.
 1463
 1464@ingroup gameObjects
 1465
 1466*/
 1467enum TurretShapeFireLinkType {
 1468/*!
 1469@brief All weapons fire under trigger 0.
 1470
 1471*/
 1472FireTogether,
 1473/*!
 1474@brief Weapon mounts 0,2 fire under trigger 0, mounts 1,3 fire under trigger 1.
 1475
 1476*/
 1477GroupedFire,
 1478/*!
 1479@brief Each weapon mount fires under its own trigger 0-3.
 1480
 1481*/
 1482IndividualFire,
 1483};
 1484/*!
 1485@brief How to handle the physics simulation with the client's and server.
 1486
 1487@ingroup Physics
 1488
 1489*/
 1490enum PhysicsSimType {
 1491/*!
 1492@brief Only handle physics on the client.
 1493
 1494*/
 1495ClientOnly,
 1496/*!
 1497@brief Only handle physics on the server.
 1498
 1499*/
 1500ServerOnly,
 1501/*!
 1502@brief Handle physics on both the client and server.
 1503
 1504*/
 1505ClientServer,
 1506};
 1507/*!
 1508@brief The type of visual blending style to apply to the particles.
 1509
 1510@ingroup FX
 1511
 1512*/
 1513enum ParticleBlendStyle {
 1514/*!
 1515@brief No blending style.
 1516
 1517*/
 1518NORMAL,
 1519/*!
 1520@brief Adds the color of the pixel to the frame buffer with full alpha for each pixel.
 1521
 1522*/
 1523ADDITIVE,
 1524/*!
 1525@brief Subtractive Blending. Reverses the color model, causing dark colors to have a stronger visual effect.
 1526
 1527*/
 1528SUBTRACTIVE,
 1529/*!
 1530@brief Color blends with the colors of the imagemap rather than the alpha.
 1531
 1532*/
 1533PREMULTALPHA,
 1534};
 1535/*!
 1536@brief Type of mesh data available in a shape.
 1537
 1538@ingroup gameObjects*/
 1539enum TSMeshType {
 1540/*!
 1541@brief No mesh data.
 1542
 1543*/
 1544None,
 1545/*!
 1546@brief Bounding box of the shape.
 1547
 1548*/
 1549Bounds,
 1550/*!
 1551@brief Specifically desingated "collision" meshes.
 1552
 1553*/
 1554Collision Mesh,
 1555/*!
 1556@brief Rendered mesh polygons.
 1557
 1558*/
 1559Visible Mesh,
 1560};
 1561/*!
 1562@brief The type of light to attach to this ShapeBaseImage.
 1563
 1564@ingroup gameObjects
 1565
 1566*/
 1567enum ShapeBaseImageLightType {
 1568/*!
 1569@brief No light is attached.
 1570
 1571*/
 1572NoLight,
 1573/*!
 1574@brief A constant emitting light is attached.
 1575
 1576*/
 1577ConstantLight,
 1578/*!
 1579@brief A spotlight is attached.
 1580
 1581*/
 1582SpotLight,
 1583/*!
 1584@brief A pusling light is attached.
 1585
 1586*/
 1587PulsingLight,
 1588/*!
 1589@brief Light emits when the weapon is fired, then dissipates.
 1590
 1591*/
 1592WeaponFireLight,
 1593};
 1594/*!
 1595@brief What kind of recoil this ShapeBaseImage should emit when fired.
 1596
 1597@ingroup gameObjects
 1598
 1599*/
 1600enum ShapeBaseImageRecoilState {
 1601/*!
 1602@brief No recoil occurs.
 1603
 1604*/
 1605NoRecoil,
 1606/*!
 1607@brief A light recoil occurs.
 1608
 1609*/
 1610LightRecoil,
 1611/*!
 1612@brief A medium recoil occurs.
 1613
 1614*/
 1615MediumRecoil,
 1616/*!
 1617@brief A heavy recoil occurs.
 1618
 1619*/
 1620HeavyRecoil,
 1621};
 1622/*!
 1623@brief How the spin animation should be played.
 1624
 1625@ingroup gameObjects
 1626
 1627*/
 1628enum ShapeBaseImageSpinState {
 1629/*!
 1630@brief No changes to the spin sequence.
 1631
 1632*/
 1633Ignore,
 1634/*!
 1635@brief Stops the spin sequence at its current position
 1636
 1637*/
 1638Stop,
 1639/*!
 1640@brief Increase spin sequence timeScale from 0 (on state entry) to 1 (after stateTimeoutValue seconds).
 1641
 1642*/
 1643SpinUp,
 1644/*!
 1645@brief Decrease spin sequence timeScale from 1 (on state entry) to 0 (after stateTimeoutValue seconds).
 1646
 1647*/
 1648SpinDown,
 1649/*!
 1650@brief Resume the spin sequence playback at its current position with timeScale = 1.
 1651
 1652*/
 1653FullSpeed,
 1654};
 1655/*!
 1656@brief The loaded state of this ShapeBaseImage.
 1657
 1658@ingroup gameObjects
 1659
 1660*/
 1661enum ShapeBaseImageLoadedState {
 1662/*!
 1663@brief Ignore the loaded state.
 1664
 1665*/
 1666Ignore,
 1667/*!
 1668@brief ShapeBaseImage is loaded.
 1669
 1670*/
 1671Loaded,
 1672/*!
 1673@brief ShapeBaseImage is not loaded.
 1674
 1675*/
 1676Empty,
 1677};
 1678/*!
 1679@brief The pose of the Player.
 1680
 1681@ingroup gameObjects
 1682
 1683*/
 1684enum PlayerPose {
 1685/*!
 1686@brief Standard movement pose.
 1687
 1688*/
 1689Stand,
 1690/*!
 1691@brief Sprinting pose.
 1692
 1693*/
 1694Sprint,
 1695/*!
 1696@brief Crouch pose.
 1697
 1698*/
 1699Crouch,
 1700/*!
 1701@brief Prone pose.
 1702
 1703*/
 1704Prone,
 1705/*!
 1706@brief Swimming pose.
 1707
 1708*/
 1709Swim,
 1710};
 1711/*!
 1712@brief Possible physical zone force types.
 1713
 1714@ingroup PhysicalZone
 1715
 1716*/
 1717enum PhysicalZone_ForceType {
 1718/*!
 1719@brief ...
 1720
 1721*/
 1722vector,
 1723/*!
 1724@brief ...
 1725
 1726*/
 1727spherical,
 1728/*!
 1729@brief ...
 1730
 1731*/
 1732cylindrical,
 1733/*!
 1734@brief ...
 1735
 1736*/
 1737sphere,
 1738/*!
 1739@brief ...
 1740
 1741*/
 1742cylinder,
 1743};
 1744/*!
 1745@brief The type of light the Item has
 1746
 1747@ingroup gameObjects
 1748
 1749*/
 1750enum ItemLightType {
 1751/*!
 1752@brief The item has no light attached.
 1753
 1754*/
 1755NoLight,
 1756/*!
 1757@brief The item has a constantly emitting light attached.
 1758
 1759*/
 1760ConstantLight,
 1761/*!
 1762@brief The item has a pulsing light attached.
 1763
 1764*/
 1765PulsingLight,
 1766};
 1767/*!
 1768@brief Movement behavior type for Camera.
 1769
 1770
 1771@ingroup BaseCamera*/
 1772enum CameraMotionMode {
 1773/*!
 1774@brief Camera does not rotate or move.
 1775
 1776*/
 1777Stationary,
 1778/*!
 1779@brief Camera may rotate but does not move.
 1780
 1781*/
 1782FreeRotate,
 1783/*!
 1784@brief Camera may rotate and move freely.
 1785
 1786*/
 1787Fly,
 1788/*!
 1789@brief Camera orbits about a given object.  Damage flash and white out is determined by the object being orbited.  See Camera::setOrbitMode() to set the orbit object and other parameters.
 1790
 1791*/
 1792OrbitObject,
 1793/*!
 1794@brief Camera orbits about a given point.  See Camera::setOrbitMode() to set the orbit point and other parameters.
 1795
 1796*/
 1797OrbitPoint,
 1798/*!
 1799@brief Camera always faces a given object.  See Camera::setTrackObject() to set the object to track and a distance to remain from the object.
 1800
 1801*/
 1802TrackObject,
 1803/*!
 1804@brief Camera moves in the XY plane.
 1805
 1806*/
 1807Overhead,
 1808/*!
 1809@brief Used by the World Editor to orbit about a point.  When first activated, the camera is rotated to face the orbit point rather than move to it.
 1810
 1811*/
 1812EditOrbit,
 1813};
 1814/*!
 1815@brief Specifies how the viewport should be set up for a PostEffect's target.
 1816
 1817@note Applies to both the diffuse target and the depth target (if defined).
 1818@ingroup Rendering
 1819
 1820*/
 1821enum PFXTargetViewport {
 1822/*!
 1823@brief Set viewport to match target size (default).
 1824
 1825*/
 1826PFXTargetViewport_TargetSize,
 1827/*!
 1828@brief Use the current GFX viewport (scaled to match target size).
 1829
 1830*/
 1831PFXTargetViewport_GFXViewport,
 1832/*!
 1833@brief Use the input texture 0 if it is named (scaled to match target size), otherwise revert to PFXTargetViewport_TargetSize if there is none.
 1834
 1835*/
 1836PFXTargetViewport_NamedInTexture0,
 1837};
 1838/*!
 1839@brief Describes when the target texture should be cleared
 1840
 1841@ingroup Rendering
 1842
 1843*/
 1844enum PFXTargetClear {
 1845/*!
 1846@brief Never clear the PostEffect target.
 1847
 1848*/
 1849PFXTargetClear_None,
 1850/*!
 1851@brief Clear once on create.
 1852
 1853*/
 1854PFXTargetClear_OnCreate,
 1855/*!
 1856@brief Clear before every draw.
 1857
 1858*/
 1859PFXTargetClear_OnDraw,
 1860};
 1861/*!
 1862@brief When to process this effect during the frame.
 1863
 1864@ingroup Rendering
 1865
 1866*/
 1867enum PFXRenderTime {
 1868/*!
 1869@brief Before a RenderInstManager bin.
 1870
 1871*/
 1872PFXBeforeBin,
 1873/*!
 1874@brief After a RenderInstManager bin.
 1875
 1876*/
 1877PFXAfterBin,
 1878/*!
 1879@brief After the diffuse rendering pass.
 1880
 1881*/
 1882PFXAfterDiffuse,
 1883/*!
 1884@brief When the end of the frame is reached.
 1885
 1886*/
 1887PFXEndOfFrame,
 1888/*!
 1889@brief This PostEffect is not processed by the manager. It will generate its texture when it is requested.
 1890
 1891*/
 1892PFXTexGenOnDemand,
 1893};
 1894/*!
 1895@brief Style of rendering for a GuiTSCtrl.
 1896
 1897
 1898@ingroup Gui3D*/
 1899enum GuiTSRenderStyles {
 1900/*!
 1901*/
 1902standard,
 1903/*!
 1904*/
 1905stereo side by side,
 1906/*!
 1907*/
 1908stereo separate,
 1909};
 1910/*!
 1911
 1912@ingroup TSShapeConstructor*/
 1913enum TSShapeConstructorAnimType {
 1914/*!
 1915*/
 1916Frames,
 1917/*!
 1918*/
 1919Seconds,
 1920/*!
 1921*/
 1922Milliseconds,
 1923};
 1924/*!
 1925
 1926@ingroup TSShapeConstructor*/
 1927enum TSShapeConstructorLodType {
 1928/*!
 1929*/
 1930DetectDTS,
 1931/*!
 1932*/
 1933SingleSize,
 1934/*!
 1935*/
 1936TrailingNumber,
 1937};
 1938/*!
 1939@brief Axis to use for upwards direction when importing from Collada.
 1940
 1941
 1942@ingroup TSShapeConstructor*/
 1943enum TSShapeConstructorUpAxis {
 1944/*!
 1945*/
 1946X_AXIS,
 1947/*!
 1948*/
 1949Y_AXIS,
 1950/*!
 1951*/
 1952Z_AXIS,
 1953/*!
 1954*/
 1955DEFAULT,
 1956};
 1957/*!
 1958@brief Description
 1959
 1960@ingroup ?
 1961
 1962*/
 1963enum baseTexFormat {
 1964/*!
 1965@brief No cached terrain.
 1966
 1967*/
 1968NONE,
 1969/*!
 1970@brief Cache the terrain in a DDS format.
 1971
 1972*/
 1973DDS,
 1974/*!
 1975@brief Cache the terrain in a PNG format.
 1976
 1977*/
 1978PNG,
 1979};
 1980/*!
 1981@brief The type of knot that this marker will be.
 1982
 1983@ingroup enviroMisc
 1984
 1985*/
 1986enum MarkerKnotType {
 1987/*!
 1988@brief Knot will have a smooth camera translation/rotation effect.
 1989
 1990*/
 1991Normal,
 1992/*!
 1993@brief Will do the same for translations, leaving rotation un-touched.
 1994
 1995*/
 1996Position Only,
 1997/*!
 1998@brief The rotation will take effect immediately for an abrupt rotation change.
 1999
 2000*/
 2001Kink,
 2002};
 2003/*!
 2004@brief The type of smoothing this marker will have for pathed objects.
 2005
 2006@ingroup enviroMisc
 2007
 2008*/
 2009enum MarkerSmoothingType {
 2010/*!
 2011@brief Marker will cause the movements of the pathed object to be smooth.
 2012
 2013*/
 2014Spline,
 2015/*!
 2016@brief Marker will have no smoothing effect.
 2017
 2018*/
 2019Linear,
 2020};
 2021/*!
 2022@brief What size to render the target texture. Sizes are based on the Window the render is occuring in.
 2023
 2024@ingroup RenderBin
 2025
 2026*/
 2027enum RenderTexTargetSize {
 2028/*!
 2029@brief Render to the size of the window.
 2030
 2031*/
 2032windowsize,
 2033/*!
 2034@brief Render to the size of the window, scaled to the render target's size.
 2035
 2036*/
 2037windowsizescaled,
 2038/*!
 2039@brief Don't scale the target texture, and render to its default size.
 2040
 2041*/
 2042fixedsize,
 2043};
 2044/*!
 2045@brief When using the Wave material animation, one of these Wave Types will be used to determine the type of wave to display.
 2046
 2047@ingroup GFX
 2048*/
 2049enum MaterialWaveType {
 2050/*!
 2051@brief Warps the material along a curved Sin Wave.
 2052
 2053*/
 2054Sin,
 2055/*!
 2056@brief Warps the material along a sharp Triangle Wave.
 2057
 2058*/
 2059Triangle,
 2060/*!
 2061@brief Warps the material along a wave which transitions between two oppposite states. As a Square Wave, the transition is quick and sudden.
 2062
 2063*/
 2064Square,
 2065};
 2066/*!
 2067@brief The type of graphical blending operation to apply to this material
 2068
 2069@ingroup GFX
 2070
 2071*/
 2072enum MaterialBlendOp {
 2073/*!
 2074@brief Disable blending for this material.
 2075
 2076*/
 2077None,
 2078/*!
 2079@brief Multiplicative blending.
 2080
 2081*/
 2082Mul,
 2083/*!
 2084@brief Premultiplied alpha.
 2085
 2086*/
 2087PreMul,
 2088/*!
 2089@brief Adds the color of the material to the frame buffer with full alpha for each pixel.
 2090
 2091*/
 2092Add,
 2093/*!
 2094@brief The color is modulated by the alpha channel before being added to the frame buffer.
 2095
 2096*/
 2097AddAlpha,
 2098/*!
 2099@brief Subtractive Blending. Reverses the color model, causing dark colors to have a stronger visual effect.
 2100
 2101*/
 2102Sub,
 2103/*!
 2104@brief Linearly interpolates between Material color and frame buffer color based on alpha.
 2105
 2106*/
 2107LerpAlpha,
 2108};
 2109/*!
 2110@brief The type of animation effect to apply to this material.
 2111
 2112@ingroup GFX
 2113
 2114*/
 2115enum MaterialAnimType {
 2116/*!
 2117@brief Scroll the material along the X/Y axis.
 2118
 2119*/
 2120Scroll,
 2121/*!
 2122@brief Rotate the material around a point.
 2123
 2124*/
 2125Rotate,
 2126/*!
 2127@brief Warps the material with an animation using Sin, Triangle or Square mathematics.
 2128
 2129*/
 2130Wave,
 2131/*!
 2132@brief Scales the material larger and smaller with a pulsing effect.
 2133
 2134*/
 2135Scale,
 2136/*!
 2137@brief Enables the material to have multiple frames of animation in its imagemap.
 2138
 2139*/
 2140Sequence,
 2141};
 2142/*!
 2143
 2144@ingroup GuiCore*/
 2145enum GuiFontCharset {
 2146/*!
 2147*/
 2148ANSI,
 2149/*!
 2150*/
 2151SYMBOL,
 2152/*!
 2153*/
 2154SHIFTJIS,
 2155/*!
 2156*/
 2157HANGEUL,
 2158/*!
 2159*/
 2160HANGUL,
 2161/*!
 2162*/
 2163GB2312,
 2164/*!
 2165*/
 2166CHINESEBIG5,
 2167/*!
 2168*/
 2169OEM,
 2170/*!
 2171*/
 2172JOHAB,
 2173/*!
 2174*/
 2175HEBREW,
 2176/*!
 2177*/
 2178ARABIC,
 2179/*!
 2180*/
 2181GREEK,
 2182/*!
 2183*/
 2184TURKISH,
 2185/*!
 2186*/
 2187VIETNAMESE,
 2188/*!
 2189*/
 2190THAI,
 2191/*!
 2192*/
 2193EASTEUROPE,
 2194/*!
 2195*/
 2196RUSSIAN,
 2197/*!
 2198*/
 2199MAC,
 2200/*!
 2201*/
 2202BALTIC,
 2203};
 2204/*!
 2205
 2206@ingroup GuiCore*/
 2207enum GuiAlignmentType {
 2208/*!
 2209*/
 2210Left,
 2211/*!
 2212*/
 2213Center,
 2214/*!
 2215*/
 2216Right,
 2217/*!
 2218*/
 2219Top,
 2220/*!
 2221*/
 2222Bottom,
 2223};
 2224/*!
 2225@brief Vertical sizing behavior of a GuiControl.
 2226
 2227
 2228@ingroup GuiCore*/
 2229enum GuiVerticalSizing {
 2230/*!
 2231*/
 2232bottom,
 2233/*!
 2234*/
 2235height,
 2236/*!
 2237*/
 2238top,
 2239/*!
 2240*/
 2241center,
 2242/*!
 2243*/
 2244relative,
 2245/*!
 2246*/
 2247aspectTop,
 2248/*!
 2249*/
 2250aspectBottom,
 2251/*!
 2252*/
 2253aspectCenter,
 2254/*!
 2255*/
 2256windowRelative,
 2257};
 2258/*!
 2259@brief Horizontal sizing behavior of a GuiControl.
 2260
 2261
 2262@ingroup GuiCore*/
 2263enum GuiHorizontalSizing {
 2264/*!
 2265*/
 2266right,
 2267/*!
 2268*/
 2269width,
 2270/*!
 2271*/
 2272left,
 2273/*!
 2274*/
 2275center,
 2276/*!
 2277*/
 2278relative,
 2279/*!
 2280*/
 2281aspectLeft,
 2282/*!
 2283*/
 2284aspectRight,
 2285/*!
 2286*/
 2287aspectCenter,
 2288/*!
 2289*/
 2290windowRelative,
 2291};
 2292/*!
 2293@brief Where the control should put the tab headers for selecting individual pages.
 2294
 2295
 2296@ingroup GuiContainers*/
 2297enum GuiTabPosition {
 2298/*!
 2299@brief Tab headers on top edge.
 2300
 2301*/
 2302Top,
 2303/*!
 2304@brief Tab headers on bottom edge.
 2305
 2306*/
 2307Bottom,
 2308};
 2309/*!
 2310@brief Determines how child controls are stacked vertically.
 2311
 2312
 2313@ingroup GuiContainers*/
 2314enum GuiVerticalStackingType {
 2315/*!
 2316@brief Child controls are positioned in order from top to bottom (top-most control is first)
 2317
 2318*/
 2319Top to Bottom,
 2320/*!
 2321@brief Child controls are positioned in order from bottom to top (bottom-most control is first)
 2322
 2323*/
 2324Bottom to Top,
 2325};
 2326/*!
 2327@brief Determines how child controls are stacked horizontally.
 2328
 2329
 2330@ingroup GuiContainers*/
 2331enum GuiHorizontalStackingType {
 2332/*!
 2333@brief Child controls are positioned in order from left to right (left-most control is first)
 2334
 2335*/
 2336Left to Right,
 2337/*!
 2338@brief Child controls are positioned in order from right to left (right-most control is first)
 2339
 2340*/
 2341Right to Left,
 2342};
 2343/*!
 2344@brief Stacking method used to position child controls.
 2345
 2346
 2347@ingroup GuiContainers*/
 2348enum GuiStackingType {
 2349/*!
 2350@brief Stack children vertically by setting their Y position
 2351
 2352*/
 2353Vertical,
 2354/*!
 2355@brief Stack children horizontall by setting their X position
 2356
 2357*/
 2358Horizontal,
 2359/*!
 2360@brief Automatically switch between Vertical and Horizontal stacking. Vertical stacking is chosen when the stack control is taller than it is wide, horizontal stacking is chosen when the stack control is wider than it is tall.
 2361
 2362*/
 2363Dynamic,
 2364};
 2365/*!
 2366@brief Which side of the splitter to keep at a fixed size (if any).
 2367
 2368
 2369@ingroup GuiContainers*/
 2370enum GuiSplitFixedPanel {
 2371/*!
 2372@brief Allow both childs to resize (default).
 2373
 2374*/
 2375None,
 2376/*!
 2377@brief Keep 
 2378
 2379*/
 2380FirstPanel,
 2381/*!
 2382*/
 2383SecondPanel,
 2384};
 2385/*!
 2386@brief Axis along which to divide the container's space.
 2387
 2388
 2389@ingroup GuiContainers*/
 2390enum GuiSplitOrientation {
 2391/*!
 2392@brief Divide vertically placing one child left and one child right.
 2393
 2394*/
 2395Vertical,
 2396/*!
 2397@brief Divide horizontally placing one child on top and one child below.
 2398
 2399*/
 2400Horizontal,
 2401};
 2402/*!
 2403@brief Display behavior of a scroll bar.  Determines when a scrollbar will be visible.
 2404
 2405
 2406@ingroup GuiContainers*/
 2407enum GuiScrollBarBehavior {
 2408/*!
 2409@brief Always visible.
 2410
 2411*/
 2412alwaysOn,
 2413/*!
 2414@brief Never visible.
 2415
 2416*/
 2417alwaysOff,
 2418/*!
 2419@brief Only visible when actually needed, i.e. when the child control(s) exceed the visible space on the given axis.
 2420
 2421*/
 2422dynamic,
 2423};
 2424/*!
 2425
 2426@ingroup GuiContainers*/
 2427enum GuiFrameState {
 2428/*!
 2429*/
 2430alwaysOn,
 2431/*!
 2432*/
 2433alwaysOff,
 2434/*!
 2435*/
 2436dynamic,
 2437};
 2438/*!
 2439
 2440@ingroup GuiContainers*/
 2441enum GuiDockingType {
 2442/*!
 2443*/
 2444None,
 2445/*!
 2446*/
 2447Client,
 2448/*!
 2449*/
 2450Top,
 2451/*!
 2452*/
 2453Bottom,
 2454/*!
 2455*/
 2456Left,
 2457/*!
 2458*/
 2459Right,
 2460};
 2461/*!
 2462@brief Direction in which to scroll the child control.
 2463
 2464
 2465@ingroup GuiContainers*/
 2466enum GuiAutoScrollDirection {
 2467/*!
 2468@brief Scroll from bottom towards top.
 2469
 2470*/
 2471Up,
 2472/*!
 2473@brief Scroll from top towards bottom.
 2474
 2475*/
 2476Down,
 2477/*!
 2478@brief Scroll from right towards left.
 2479
 2480*/
 2481Left,
 2482/*!
 2483@brief Scroll from left towards right.
 2484
 2485*/
 2486Right,
 2487};
 2488/*!
 2489
 2490@ingroup GuiImages*/
 2491enum GuiIconButtonIconLocation {
 2492/*!
 2493*/
 2494None,
 2495/*!
 2496*/
 2497Left,
 2498/*!
 2499*/
 2500Right,
 2501/*!
 2502*/
 2503Center,
 2504};
 2505/*!
 2506
 2507@ingroup GuiImages*/
 2508enum GuiIconButtonTextLocation {
 2509/*!
 2510*/
 2511None,
 2512/*!
 2513*/
 2514Bottom,
 2515/*!
 2516*/
 2517Right,
 2518/*!
 2519*/
 2520Top,
 2521/*!
 2522*/
 2523Left,
 2524/*!
 2525*/
 2526Center,
 2527};
 2528/*!
 2529@brief Type of button control.
 2530
 2531
 2532@ingroup GuiButtons*/
 2533enum GuiButtonType {
 2534/*!
 2535@brief A button that triggers an action when clicked.
 2536
 2537*/
 2538PushButton,
 2539/*!
 2540@brief A button that is toggled between on and off state.
 2541
 2542*/
 2543ToggleButton,
 2544/*!
 2545@brief A button placed in groups for presenting choices.
 2546
 2547*/
 2548RadioButton,
 2549};
 2550/*!
 2551@brief Rendering behavior when placing bitmaps in controls.
 2552
 2553
 2554@ingroup GuiImages*/
 2555enum GuiBitmapMode {
 2556/*!
 2557@brief Stretch bitmap to fit control extents.
 2558
 2559*/
 2560Stretched,
 2561/*!
 2562@brief Center bitmap in control.
 2563
 2564*/
 2565Centered,
 2566};
 2567/*!
 2568@brief The blend operators.
 2569
 2570@ingroup GFX*/
 2571enum GFXBlendOp {
 2572/*!
 2573*/
 2574GFXBlendOpAdd,
 2575/*!
 2576*/
 2577GFXBlendOpSubtract,
 2578/*!
 2579*/
 2580GFXBlendOpRevSubtract,
 2581/*!
 2582*/
 2583GFXBlendOpMin,
 2584/*!
 2585*/
 2586GFXBlendOpMax,
 2587};
 2588/*!
 2589@brief The stencil operators.
 2590
 2591@ingroup GFX*/
 2592enum GFXStencilOp {
 2593/*!
 2594*/
 2595GFXStencilOpKeep,
 2596/*!
 2597*/
 2598GFXStencilOpZero,
 2599/*!
 2600*/
 2601GFXStencilOpReplace,
 2602/*!
 2603*/
 2604GFXStencilOpIncrSat,
 2605/*!
 2606*/
 2607GFXStencilOpDecrSat,
 2608/*!
 2609*/
 2610GFXStencilOpInvert,
 2611/*!
 2612*/
 2613GFXStencilOpIncr,
 2614/*!
 2615*/
 2616GFXStencilOpDecr,
 2617};
 2618/*!
 2619@brief The render cull modes.
 2620
 2621@ingroup GFX*/
 2622enum GFXCullMode {
 2623/*!
 2624*/
 2625GFXCullNone,
 2626/*!
 2627*/
 2628GFXCullCW,
 2629/*!
 2630*/
 2631GFXCullCCW,
 2632};
 2633/*!
 2634@brief The texture formats.
 2635
 2636@note Not all formats are supported on all platforms.
 2637@ingroup GFX*/
 2638enum GFXFormat {
 2639/*!
 2640*/
 2641GFXFormatR8G8B8,
 2642/*!
 2643*/
 2644GFXFormatR8G8B8A8,
 2645/*!
 2646*/
 2647GFXFormatR8G8B8A8_SRGB,
 2648/*!
 2649*/
 2650GFXFormatR8G8B8X8,
 2651/*!
 2652*/
 2653GFXFormatR32F,
 2654/*!
 2655*/
 2656GFXFormatR5G6B5,
 2657/*!
 2658*/
 2659GFXFormatR5G5B5A1,
 2660/*!
 2661*/
 2662GFXFormatR5G5B5X1,
 2663/*!
 2664*/
 2665GFXFormatA4L4,
 2666/*!
 2667*/
 2668GFXFormatA8L8,
 2669/*!
 2670*/
 2671GFXFormatA8,
 2672/*!
 2673*/
 2674GFXFormatL8,
 2675/*!
 2676*/
 2677GFXFormatBC1,
 2678/*!
 2679*/
 2680GFXFormatBC2,
 2681/*!
 2682*/
 2683GFXFormatBC3,
 2684/*!
 2685*/
 2686GFXFormatBC4,
 2687/*!
 2688*/
 2689GFXFormatBC5,
 2690/*!
 2691*/
 2692GFXFormatD32,
 2693/*!
 2694*/
 2695GFXFormatD24X8,
 2696/*!
 2697*/
 2698GFXFormatD24S8,
 2699/*!
 2700*/
 2701GFXFormatD24FS8,
 2702/*!
 2703*/
 2704GFXFormatD16,
 2705/*!
 2706*/
 2707GFXFormatR32G32B32A32F,
 2708/*!
 2709*/
 2710GFXFormatR16G16B16A16F,
 2711/*!
 2712*/
 2713GFXFormatL16,
 2714/*!
 2715*/
 2716GFXFormatR16G16B16A16,
 2717/*!
 2718*/
 2719GFXFormatR16G16,
 2720/*!
 2721*/
 2722GFXFormatR16F,
 2723/*!
 2724*/
 2725GFXFormatR16G16F,
 2726/*!
 2727*/
 2728GFXFormatR10G10B10A2,
 2729};
 2730/*!
 2731@brief The texture filter types.
 2732
 2733@ingroup GFX*/
 2734enum GFXTextureFilterType {
 2735/*!
 2736*/
 2737GFXTextureFilterNone,
 2738/*!
 2739*/
 2740GFXTextureFilterPoint,
 2741/*!
 2742*/
 2743GFXTextureFilterLinear,
 2744/*!
 2745*/
 2746GFXTextureFilterAnisotropic,
 2747};
 2748/*!
 2749@brief The texture address modes.
 2750
 2751@ingroup GFX*/
 2752enum GFXTextureAddressMode {
 2753/*!
 2754*/
 2755GFXAddressWrap,
 2756/*!
 2757*/
 2758GFXAddressMirror,
 2759/*!
 2760*/
 2761GFXAddressClamp,
 2762/*!
 2763*/
 2764GFXAddressBorder,
 2765/*!
 2766*/
 2767GFXAddressMirrorOnce,
 2768};
 2769/*!
 2770@brief The supported comparison functions.
 2771
 2772@ingroup GFX*/
 2773enum GFXCmpFunc {
 2774/*!
 2775*/
 2776GFXCmpNever,
 2777/*!
 2778*/
 2779GFXCmpLess,
 2780/*!
 2781*/
 2782GFXCmpEqual,
 2783/*!
 2784*/
 2785GFXCmpLessEqual,
 2786/*!
 2787*/
 2788GFXCmpGreater,
 2789/*!
 2790*/
 2791GFXCmpNotEqual,
 2792/*!
 2793*/
 2794GFXCmpGreaterEqual,
 2795/*!
 2796*/
 2797GFXCmpAlways,
 2798};
 2799/*!
 2800@brief The supported blend modes.
 2801
 2802@ingroup GFX*/
 2803enum GFXBlend {
 2804/*!
 2805@brief (0, 0, 0, 0)
 2806
 2807*/
 2808GFXBlendZero,
 2809/*!
 2810@brief (1, 1, 1, 1)
 2811
 2812*/
 2813GFXBlendOne,
 2814/*!
 2815@brief (Rs, Gs, Bs, As)
 2816
 2817*/
 2818GFXBlendSrcColor,
 2819/*!
 2820@brief (1 - Rs, 1 - Gs, 1 - Bs, 1 - As)
 2821
 2822*/
 2823GFXBlendInvSrcColor,
 2824/*!
 2825@brief (As, As, As, As)
 2826
 2827*/
 2828GFXBlendSrcAlpha,
 2829/*!
 2830@brief ( 1 - As, 1 - As, 1 - As, 1 - As)
 2831
 2832*/
 2833GFXBlendInvSrcAlpha,
 2834/*!
 2835@brief (Ad Ad Ad Ad)
 2836
 2837*/
 2838GFXBlendDestAlpha,
 2839/*!
 2840@brief (1 - Ad 1 - Ad 1 - Ad 1 - Ad)
 2841
 2842*/
 2843GFXBlendInvDestAlpha,
 2844/*!
 2845@brief (Rd, Gd, Bd, Ad)
 2846
 2847*/
 2848GFXBlendDestColor,
 2849/*!
 2850@brief (1 - Rd, 1 - Gd, 1 - Bd, 1 - Ad)
 2851
 2852*/
 2853GFXBlendInvDestColor,
 2854/*!
 2855@brief (f, f, f, 1) where f = min(As, 1 - Ad)
 2856
 2857*/
 2858GFXBlendSrcAlphaSat,
 2859};
 2860/*!
 2861@brief Back-end graphics API used by the GFX subsystem.
 2862
 2863
 2864@ingroup GFX*/
 2865enum GFXAdapterType {
 2866/*!
 2867@brief OpenGL.
 2868
 2869*/
 2870OpenGL,
 2871/*!
 2872@brief Direct3D 11.
 2873
 2874*/
 2875D3D11,
 2876/*!
 2877@brief Null device for dedicated servers.
 2878
 2879*/
 2880NullDevice,
 2881};
 2882/*!
 2883@brief Return value for messageBox() indicating which button was pressed by the user.
 2884
 2885
 2886@ingroup Platform*/
 2887enum MBReturnVal {
 2888/*!
 2889*/
 2890OK,
 2891/*!
 2892*/
 2893Cancelled,
 2894/*!
 2895*/
 2896Retry,
 2897/*!
 2898*/
 2899DontSave,
 2900};
 2901/*!
 2902@brief What icon to show on a message box.
 2903
 2904
 2905@ingroup Platform*/
 2906enum MBIcons {
 2907/*!
 2908*/
 2909Information,
 2910/*!
 2911*/
 2912Warning,
 2913/*!
 2914*/
 2915Stop,
 2916/*!
 2917*/
 2918Question,
 2919};
 2920/*!
 2921@brief Which buttons to display on a message box.
 2922
 2923
 2924@ingroup Platform*/
 2925enum MBButtons {
 2926/*!
 2927*/
 2928Ok,
 2929/*!
 2930*/
 2931OkCancel,
 2932/*!
 2933*/
 2934RetryCancel,
 2935/*!
 2936*/
 2937SaveDontSave,
 2938/*!
 2939*/
 2940SaveDontSaveCancel,
 2941};
 2942/*!
 2943@brief Priority levels for logging entries
 2944
 2945@ingroup Logging*/
 2946enum LogLevel {
 2947/*!
 2948@brief Lowest priority level, no highlighting.
 2949
 2950*/
 2951normal,
 2952/*!
 2953@brief Mid level priority, tags and highlights possible issues in blue.
 2954
 2955*/
 2956warning,
 2957/*!
 2958@brief Highest priority level, extreme emphasis on this entry. Highlighted in red.
 2959
 2960*/
 2961error,
 2962};
 2963/*!
 2964@brief Channels are individual properties of sound sources that may be animated over time.
 2965
 2966
 2967@see SFXParameter
 2968
 2969@ref SFX_interactive
 2970
 2971@ingroup SFX*/
 2972enum SFXChannel {
 2973/*!
 2974@brief Channel controls volume level of attached sound sources.
 2975
 2976@see SFXDescription::volume*/
 2977Volume,
 2978/*!
 2979@brief Channel controls pitch of attached sound sources.
 2980
 2981@see SFXDescription::pitch*/
 2982Pitch,
 2983/*!
 2984@brief Channel controls virtualizaton priority level of attached sound sources.
 2985
 2986@see SFXDescription::priority*/
 2987Priority,
 2988/*!
 2989@brief Channel controls X coordinate of 3D sound position of attached sources.
 2990
 2991*/
 2992PositionX,
 2993/*!
 2994@brief Channel controls Y coordinate of 3D sound position of attached sources.
 2995
 2996*/
 2997PositionY,
 2998/*!
 2999@brief Channel controls Z coordinate of 3D sound position of attached sources.
 3000
 3001*/
 3002PositionZ,
 3003/*!
 3004@brief Channel controls X rotation (in degrees) of 3D sound orientation of attached sources.
 3005
 3006*/
 3007RotationX,
 3008/*!
 3009@brief Channel controls Y rotation (in degrees) of 3D sound orientation of attached sources.
 3010
 3011*/
 3012RotationY,
 3013/*!
 3014@brief Channel controls Z rotation (in degrees) of 3D sound orientation of attached sources.
 3015
 3016*/
 3017RotationZ,
 3018/*!
 3019@brief Channel controls X coordinate of 3D sound velocity vector of attached sources.
 3020
 3021*/
 3022VelocityX,
 3023/*!
 3024@brief Channel controls Y coordinate of 3D sound velocity vector of attached sources.
 3025
 3026*/
 3027VelocityY,
 3028/*!
 3029@brief Channel controls Z coordinate of 3D sound velocity vector of attached sources.
 3030
 3031*/
 3032VelocityZ,
 3033/*!
 3034@brief Channel controls reference distance of 3D sound of attached sources.
 3035
 3036@see SFXDescription::referenceDistance*/
 3037ReferenceDistance,
 3038/*!
 3039@brief Channel controls max volume attenuation distance of 3D sound of attached sources.
 3040
 3041@see SFXDescription::maxDistance*/
 3042MaxDistance,
 3043/*!
 3044@brief Channel controls angle (in degrees) of 3D sound inner volume cone of attached sources.
 3045
 3046@see SFXDescription::coneInsideAngle*/
 3047ConeInsideAngle,
 3048/*!
 3049@brief Channel controls angle (in degrees) of 3D sound outer volume cone of attached sources.
 3050
 3051@see SFXDescription::coneOutsideAngle*/
 3052ConeOutsideAngle,
 3053/*!
 3054@brief Channel controls volume outside of 3D sound outer cone of attached sources.
 3055
 3056@see SFXDescription::coneOutsideVolume*/
 3057ConeOutsideVolume,
 3058/*!
 3059@brief Channel controls playback cursor of attached sound sources.
 3060
 3061
 3062@note Be aware that different types of sound sources interpret play cursor positions differently or do not actually have play cursors (these sources will ignore the channel).*/
 3063Cursor,
 3064/*!
 3065@brief Channel controls playback status of attached sound sources.
 3066
 3067
 3068The channel's value is rounded down to the nearest integer and interpreted in the following way:
 3069- 1: Play
 3070- 2: Stop
 3071- 3: Pause
 3072
 3073*/
 3074Status,
 3075/*!
 3076@brief Channel available for custom use.  By default ignored by sources.
 3077
 3078
 3079@note For FMOD Designer event sources (SFXFMODEventSource), this channel is used for event parameters defined in FMOD Designer and should not be used otherwise.
 3080
 3081@see SFXSource::onParameterValueChange*/
 3082User0,
 3083/*!
 3084@brief Channel available for custom use.  By default ignored by sources.
 3085
 3086
 3087@see SFXSource::onParameterValueChange*/
 3088User1,
 3089/*!
 3090@brief Channel available for custom use.  By default ignored by sources.
 3091
 3092
 3093@see SFXSource::onParameterValueChange*/
 3094User2,
 3095/*!
 3096@brief Channel available for custom use.  By default ignored by sources.
 3097
 3098
 3099@see SFXSource::onParameterValueChange*/
 3100User3,
 3101};
 3102/*!
 3103@brief Type of volume distance attenuation curve.
 3104
 3105The distance model determines the falloff curve applied to the volume of 3D sounds over distance.
 3106
 3107@ref SFXSource_volume
 3108
 3109@ref SFX_3d
 3110
 3111@ingroup SFX*/
 3112enum SFXDistanceModel {
 3113/*!
 3114@brief Volume attenuates linearly from the references distance onwards to max distance where it reaches zero.
 3115
 3116*/
 3117Linear,
 3118/*!
 3119@brief Volume attenuates logarithmically starting from the reference distance and halving every reference distance step from there on. Attenuation stops at max distance but volume won't reach zero.
 3120
 3121*/
 3122Logarithmic,
 3123/*!
 3124@brief Volume attenuates exponentially starting from the reference distance and attenuating every reference distance step by the rolloff factor. Attenuation stops at max distance but volume won't reach zero.
 3125
 3126*/
 3127Exponential,
 3128};
 3129/*!
 3130@brief Playback status of sound source.
 3131
 3132@ingroup SFX*/
 3133enum SFXStatus {
 3134/*!
 3135@brief The source is currently playing.
 3136
 3137*/
 3138Playing,
 3139/*!
 3140@brief Playback of the source is stopped.  When transitioning to Playing state, playback will start at the beginning of the source.
 3141
 3142*/
 3143Stopped,
 3144/*!
 3145@brief Playback of the source is paused.  Resuming playback will play from the current playback position.
 3146
 3147*/
 3148Paused,
 3149};
 3150/*!
 3151@brief Reaction behavior when a state is changed incompatibly on a slot that has already started playing.
 3152
 3153
 3154@see SFXPlayList::stateMode
 3155
 3156@ingroup SFX*/
 3157enum SFXPlayListStateMode {
 3158/*!
 3159@brief Stop the sources playing on the slot when a state changes to a setting that is incompatible with the slot's state setting.
 3160
 3161*/
 3162StopWhenDeactivated,
 3163/*!
 3164@brief Pause all sources playing on the slot when a state changes to a setting that is incompatible with the slot's state setting.
 3165
 3166
 3167When the slot's state is reactivated again, the sources will resume playback.*/
 3168PauseWhenDeactivated,
 3169/*!
 3170@brief Ignore when a state changes to a setting incompatible with the slot's state setting and just keep playing sources attached to the slot.
 3171
 3172*/
 3173IgnoreWhenDeactivated,
 3174};
 3175/*!
 3176@brief Behavior when hitting the play stage of a slot that is still playing from a previous cycle.
 3177
 3178
 3179@see SFXPlayList::replay
 3180
 3181@ingroup SFX*/
 3182enum SFXPlayListReplayMode {
 3183/*!
 3184@brief Ignore any sources that may already be playing on the slot and just create a new source.
 3185
 3186*/
 3187IgnorePlaying,
 3188/*!
 3189@brief Restart all sources that was last created for the slot.
 3190
 3191*/
 3192RestartPlaying,
 3193/*!
 3194@brief Keep playing the current source(s) as if the source started last on the slot was created in this cycle.  For this, the sources associated with the slot are brought to the top of the play stack.
 3195
 3196*/
 3197KeepPlaying,
 3198/*!
 3199@brief Stop all sources currently playing on the slot and then create a new source.
 3200
 3201*/
 3202StartNew,
 3203/*!
 3204@brief If there are sources already playing on the slot, skip the play stage.
 3205
 3206*/
 3207SkipIfPlaying,
 3208};
 3209/*!
 3210@brief Playlist behavior when transitioning in and out of invididual slots.
 3211
 3212
 3213Transition behaviors apply when the playback controller starts processing a playlist slot and when it ends processing a slot.  Using transition behaviors, playback can be synchronized.
 3214
 3215@see SFXPlayList::transitionIn
 3216
 3217@see SFXPlayList::transitionOut
 3218
 3219@ingroup SFX*/
 3220enum SFXPlayListTransitionMode {
 3221/*!
 3222@brief No transition.  Immediately move on to processing the slot or immediately move on to the next slot.
 3223
 3224*/
 3225None,
 3226/*!
 3227@brief Wait for the sound source spawned last by this playlist to finish playing.  Then proceed.
 3228
 3229*/
 3230Wait,
 3231/*!
 3232@brief Wait for all sound sources currently spawned by the playlist to finish playing.  Then proceed.
 3233
 3234*/
 3235WaitAll,
 3236/*!
 3237@brief Stop the sound source spawned last by this playlist.  Then proceed.
 3238
 3239*/
 3240Stop,
 3241/*!
 3242@brief Stop all sound sources spawned by the playlist.  Then proceed.
 3243
 3244*/
 3245StopAll,
 3246};
 3247/*!
 3248@brief Randomization pattern to apply to playlist slot playback order.
 3249
 3250
 3251@see SFXPlayList::random
 3252
 3253@ingroup SFX*/
 3254enum SFXPlayListRandomMode {
 3255/*!
 3256@brief Play slots in sequential order.  No randomization.
 3257
 3258*/
 3259NotRandom,
 3260/*!
 3261@brief Play a strictly random selection of slots.
 3262
 3263
 3264In this mode, a set of numSlotsToPlay random numbers between 0 and numSlotsToPlay-1 (inclusive), i.e. in the range of valid slot indices, is generated and playlist slots are played back in the order of this list.  This allows the same slot to occur multiple times in a list and, consequentially, allows for other slots to not appear at all in a given slot ordering.*/
 3265StrictRandom,
 3266/*!
 3267@brief Play all slots in the list in a random order.
 3268
 3269
 3270In this mode, the @c numSlotsToPlay slots from the list with valid tracks assigned are put into a random order and played.  This guarantees that each slots is played exactly once albeit at a random position in the total ordering.*/
 3271OrderedRandom,
 3272};
 3273/*!
 3274@brief Playlist behavior when description is set to loop.
 3275
 3276
 3277@see SFXDescription::isLooping
 3278
 3279@see SFXPlayList::loopMode
 3280
 3281@ingroup SFX*/
 3282enum SFXPlayListLoopMode {
 3283/*!
 3284@brief Loop over all slots, i.e. jump from last to first slot after all slots have played.
 3285
 3286*/
 3287All,
 3288/*!
 3289@brief Loop infinitely over the current slot.  Only useful in combination with either states or manual playlist control.
 3290
 3291*/
 3292Single,
 3293};
 3294/*!
 3295@var int $pref::maximumNumOfLights;
 3296@brief The maximum number of local lights that can be rendered at a time. If set to -1, then no limit.
 3297
 3298
 3299@ingroup UNDOCUMENTED
 3300*/
 3301namespace $pref { int maximumNumOfLights; } 
 3302/*!
 3303@var int $Ease::Cubic;
 3304@brief Cubic ease for curve movement.
 3305
 3306@ingroup Game*/
 3307namespace $Ease { int Cubic; } 
 3308/*!
 3309@var bool $pref::useLightFade;
 3310@brief Indicates if local lights should utilize the distance-based object fadeout logic.
 3311
 3312
 3313@ingroup UNDOCUMENTED
 3314*/
 3315namespace $pref { bool useLightFade; } 
 3316/*!
 3317@var int $Ease::Quartic;
 3318@brief Quartic ease for curve movement.
 3319
 3320@ingroup Game*/
 3321namespace $Ease { int Quartic; } 
 3322/*!
 3323@var float $pref::lightFadeStart;
 3324@brief Distance at which light fading begins if $pref::useLightFade is on.
 3325
 3326
 3327@ingroup UNDOCUMENTED
 3328*/
 3329namespace $pref { float lightFadeStart; } 
 3330/*!
 3331@var int $Ease::Quintic;
 3332@brief Quintic ease for curve movement.
 3333
 3334@ingroup Game*/
 3335namespace $Ease { int Quintic; } 
 3336/*!
 3337@var float $pref::lightFadeEnd;
 3338@brief Distance at which light fading should have fully faded if $pref::useLightFade is on.
 3339
 3340
 3341@ingroup UNDOCUMENTED
 3342*/
 3343namespace $pref { float lightFadeEnd; } 
 3344/*!
 3345@var int $Ease::Sinusoidal;
 3346@brief Sinusoidal ease for curve movement.
 3347
 3348@ingroup Game*/
 3349namespace $Ease { int Sinusoidal; } 
 3350/*!
 3351@var bool $pref::allowLocalLightShadows;
 3352@brief Indicates if local lights(point/spot) can cast shadows.
 3353
 3354
 3355@ingroup UNDOCUMENTED
 3356*/
 3357namespace $pref { bool allowLocalLightShadows; } 
 3358/*!
 3359@var int $Ease::Exponential;
 3360@brief Exponential ease for curve movement.
 3361
 3362@ingroup Game*/
 3363namespace $Ease { int Exponential; } 
 3364/*!
 3365@var bool $pref::afxZodiac::preferDestinationGradients;
 3366
 3367@ingroup UNDOCUMENTED
 3368*/
 3369namespace $pref { namespace afxZodiac { bool preferDestinationGradients; }  } 
 3370/*!
 3371@var int $Ease::Circular;
 3372@brief Circular ease for curve movement.
 3373
 3374@ingroup Game*/
 3375namespace $Ease { int Circular; } 
 3376/*!
 3377@var int $Ease::Elastic;
 3378@brief Elastic ease for curve movement.
 3379
 3380@ingroup Game*/
 3381namespace $Ease { int Elastic; } 
 3382/*!
 3383@var int $Ease::Back;
 3384@brief Backwards ease for curve movement.
 3385
 3386@ingroup Game*/
 3387namespace $Ease { int Back; } 
 3388/*!
 3389@var int $Ease::Bounce;
 3390@brief Bounce ease for curve movement.
 3391
 3392@ingroup Game*/
 3393namespace $Ease { int Bounce; } 
 3394/*!
 3395@var bool $pref::enablePostEffects;
 3396@brief If true, post effects will be eanbled.
 3397
 3398@ingroup Game*/
 3399namespace $pref { bool enablePostEffects; } 
 3400/*!
 3401@var float $pref::TS::detailAdjust;
 3402@brief User perference for scaling the TSShape level of detail.
 3403The smaller the value the closer the camera must get to see the highest LOD.  This setting can have a huge impact on performance in mesh heavy scenes.  The default value is 1.
 3404@ingroup Rendering
 3405*/
 3406namespace $pref { namespace TS { float detailAdjust; }  } 
 3407/*!
 3408@var int $pref::TS::skipLoadDLs;
 3409@brief User perference which causes TSShapes to skip loading higher lods.
 3410This potentialy reduces the GPU resources and materials generated as well as limits the LODs rendered.  The default value is 0.
 3411@see $pref::TS::skipRenderDLs
 3412@ingroup Rendering
 3413*/
 3414namespace $pref { namespace TS { int skipLoadDLs; }  } 
 3415/*!
 3416@var int $pref::TS::skipRenderDLs;
 3417@brief User perference which causes TSShapes to skip rendering higher lods.
 3418This will reduce the number of draw calls and triangles rendered and improve rendering performance when proper LODs have been created for your models. The default value is 0.
 3419@see $pref::TS::skipLoadDLs
 3420@ingroup Rendering
 3421*/
 3422namespace $pref { namespace TS { int skipRenderDLs; }  } 
 3423/*!
 3424@var float $pref::TS::smallestVisiblePixelSize;
 3425@brief User perference which sets the smallest pixel size at which TSShapes will skip rendering.
 3426This will force all shapes to stop rendering when they get smaller than this size. The default value is -1 which disables it.
 3427@ingroup Rendering
 3428*/
 3429namespace $pref { namespace TS { float smallestVisiblePixelSize; }  } 
 3430/*!
 3431@var int $pref::TS::maxInstancingVerts;
 3432@brief Enables mesh instancing on non-skin meshes that have less that this count of verts.
 3433The default value is 2000.  Higher values can degrade performance.
 3434@ingroup Rendering
 3435*/
 3436namespace $pref { namespace TS { int maxInstancingVerts; }  } 
 3437/*!
 3438@var bool $pref::imposter::canShadow;
 3439@brief User preference which toggles shadows from imposters.  Defaults to true.
 3440
 3441@ingroup Rendering
 3442*/
 3443namespace $pref { namespace imposter { bool canShadow; }  } 
 3444/*!
 3445@var float $pref::windEffectRadius;
 3446@brief Radius to affect the wind.
 3447
 3448@ingroup Rendering
 3449*/
 3450namespace $pref { float windEffectRadius; } 
 3451/*!
 3452@var bool $pref::useStaticObjectFade;
 3453@brief Indicates if all statics should utilize the distance-based object fadeout logic.
 3454
 3455
 3456@ingroup UNDOCUMENTED
 3457*/
 3458namespace $pref { bool useStaticObjectFade; } 
 3459/*!
 3460@var int $pref::Video::defaultAnisotropy;
 3461@brief Global variable defining the default anisotropy value.
 3462
 3463Controls the default anisotropic texture filtering level for all materials, including the terrain. This value can be changed at runtime to see its affect without reloading.
 3464
 3465 @ingroup Materials*/
 3466namespace $pref { namespace Video { int defaultAnisotropy; }  } 
 3467/*!
 3468@var float $pref::staticObjectFadeStart;
 3469@brief Distance at which static object fading begins if $pref::useStaticObjectFade is on.
 3470
 3471
 3472@ingroup UNDOCUMENTED
 3473*/
 3474namespace $pref { float staticObjectFadeStart; } 
 3475/*!
 3476@var float $pref::Reflect::refractTexScale;
 3477@brief RefractTex has dimensions equal to the active render target scaled in both x and y by this float.
 3478
 3479@ingroup Rendering*/
 3480namespace $pref { namespace Reflect { float refractTexScale; }  } 
 3481/*!
 3482@var float $pref::staticObjectFadeEnd;
 3483@brief Distance at which static object fading should have fully faded if $pref::useStaticObjectFade is on.
 3484
 3485
 3486@ingroup UNDOCUMENTED
 3487*/
 3488namespace $pref { float staticObjectFadeEnd; } 
 3489/*!
 3490@var int $pref::Reflect::frameLimitMS;
 3491@brief ReflectionManager tries not to spend more than this amount of time updating reflections per frame.
 3492
 3493@ingroup Rendering*/
 3494namespace $pref { namespace Reflect { int frameLimitMS; }  } 
 3495/*!
 3496@var float $pref::Shadows::textureScalar;
 3497@brief Used to scale the shadow texture sizes.
 3498This can reduce the shadow quality and texture memory overhead or increase them.
 3499@ingroup AdvancedLighting
 3500*/
 3501namespace $pref { namespace Shadows { float textureScalar; }  } 
 3502/*!
 3503@var float $pref::staticObjectUnfadeableSize;
 3504@brief Size of object where if the bounds is at or bigger than this, it will be ignored in the $pref::useStaticObjectFade logic. Useful for very large, distance-important objects.
 3505
 3506
 3507@ingroup UNDOCUMENTED
 3508*/
 3509namespace $pref { float staticObjectUnfadeableSize; } 
 3510/*!
 3511@var float $pref::PhysicsDebris::lifetimeScale;
 3512@brief Scales how long %PhysicsDebris will live before being removed.
 3513@note A value of 0 will disable PhysicsDebris entirely.
 3514@ingroup UNDOCUMENTED
 3515*/
 3516namespace $pref { namespace PhysicsDebris { float lifetimeScale; }  } 
 3517/*!
 3518@var bool $pref::Shadows::disable;
 3519@brief Used to disable all shadow rendering.
 3520
 3521@ingroup AdvancedLighting
 3522*/
 3523namespace $pref { namespace Shadows { bool disable; }  } 
 3524/*!
 3525@var bool $gfx::wireframe;
 3526@brief Used to toggle wireframe rendering at runtime.
 3527
 3528@ingroup GFX
 3529*/
 3530namespace $gfx { bool wireframe; } 
 3531/*!
 3532@var float $pref::Terrain::lodScale;
 3533@brief A global LOD scale used to tweak the default terrain screen error value.
 3534
 3535
 3536@ingroup Terrain*/
 3537namespace $pref { namespace Terrain { float lodScale; }  } 
 3538/*!
 3539@var bool $gfx::disassembleAllShaders;
 3540@brief On supported devices this will dump shader disassembly to the procedural shader folder.
 3541
 3542@ingroup GFX
 3543*/
 3544namespace $gfx { bool disassembleAllShaders; } 
 3545/*!
 3546@var bool $Shadows::disable;
 3547@brief Used by the editor to disable all shadow rendering.
 3548
 3549@ingroup AdvancedLighting
 3550*/
 3551namespace $Shadows { bool disable; } 
 3552/*!
 3553@var float $pref::Terrain::detailScale;
 3554@brief A global detail scale used to tweak the material detail distances.
 3555
 3556
 3557@ingroup Terrain*/
 3558namespace $pref { namespace Terrain { float detailScale; }  } 
 3559/*!
 3560@var float $pref::Shadows::teleportDist;
 3561@brief Minimum distance moved per frame to determine that we are teleporting.
 3562
 3563
 3564@ingroup UNDOCUMENTED
 3565*/
 3566namespace $pref { namespace Shadows { float teleportDist; }  } 
 3567/*!
 3568@var bool $gfx::disableOcclusionQuery;
 3569@brief Debug helper that disables all hardware occlusion queries causing them to return only the visibile state.
 3570
 3571@ingroup GFX
 3572*/
 3573namespace $gfx { bool disableOcclusionQuery; } 
 3574/*!
 3575@var float $SB::DFDec;
 3576@brief Speed to reduce the damage flash effect per tick.
 3577
 3578
 3579@see ShapeBase::setDamageFlash()
 3580@see ShapeBase::getDamageFlash()
 3581@note Relies on the flash postFx.
 3582@ingroup gameObjects
 3583*/
 3584namespace $SB { float DFDec; } 
 3585/*!
 3586@var float $SB::WODec;
 3587@brief Speed to reduce the whiteout effect per tick.
 3588
 3589
 3590@see ShapeBase::setWhiteOut()
 3591@see ShapeBase::getWhiteOut@note Relies on the flash postFx.
 3592@ingroup gameObjects
 3593*/
 3594namespace $SB { float WODec; } 
 3595/*!
 3596@var bool $pref::Video::disableVerticalSync;
 3597@brief Disables vertical sync on the active device.
 3598
 3599@note The video mode must be reset for the change to take affect.
 3600@ingroup GFX
 3601*/
 3602namespace $pref { namespace Video { bool disableVerticalSync; }  } 
 3603/*!
 3604@var float $pref::Shadows::turnRate;
 3605@brief Minimum angle moved per frame to determine that we are turning quickly.
 3606
 3607
 3608@ingroup UNDOCUMENTED
 3609*/
 3610namespace $pref { namespace Shadows { float turnRate; }  } 
 3611/*!
 3612@var int $pref::Net::LagThreshold;
 3613@brief How long between received packets before the client is considered as lagging (in ms).
 3614
 3615This is used by GameConnection to determine if the client is lagging.  If the client is indeed lagging, setLagIcon() is called to inform the user in some way.  i.e. display an icon on screen.
 3616
 3617@see GameConnection, GameConnection::setLagIcon()
 3618
 3619@ingroup Networking
 3620*/
 3621namespace $pref { namespace Net { int LagThreshold; }  } 
 3622/*!
 3623@var float $SB::FullCorrectionDistance;
 3624@brief Distance at which a weapon's muzzle vector is fully corrected to match where the player is looking.
 3625
 3626When a weapon image has correctMuzzleVector set and the Player is in 1st person, the muzzle vector from the weapon is modified to match where the player is looking.  Beyond the FullCorrectionDistance the muzzle vector is always corrected.  Between FullCorrectionDistance and the player, the weapon's muzzle vector is adjusted so that the closer the aim point is to the player, the closer the muzzle vector is to the true (non-corrected) one.
 3627@ingroup gameObjects
 3628*/
 3629namespace $SB { float FullCorrectionDistance; } 
 3630/*!
 3631@var float $pref::PSSM::detailAdjustScale;
 3632@brief Scales the model LOD when rendering into the PSSM shadow.
 3633Use this to reduce the draw calls when rendering the shadow by having meshes LOD out nearer to the camera than normal.
 3634@see $pref::TS::detailAdjust
 3635@ingroup AdvancedLighting*/
 3636namespace $pref { namespace PSSM { float detailAdjustScale; }  } 
 3637/*!
 3638@var string $Pref::Server::DatablockCacheFilename;
 3639
 3640@ingroup UNDOCUMENTED
 3641*/
 3642namespace $Pref { namespace Server { string DatablockCacheFilename; }  } 
 3643/*!
 3644@var float $pref::Video::forcedPixVersion;
 3645@brief Will force the shader model if the value is positive and less than the shader model supported by the active device.  Use 0 for fixed function.
 3646
 3647@note The graphics device must be reset for the change to take affect.
 3648@ingroup GFX
 3649*/
 3650namespace $pref { namespace Video { float forcedPixVersion; }  } 
 3651/*!
 3652@var int $rigidPhysics::workingQueryBoxStaleThreshold;
 3653@brief The maximum number of ticks that go by before the mWorkingQueryBox is considered stale and needs updating.
 3654
 3655Other factors can cause the collision working query box to become invalidated, such as the rigid body moving far enough outside of this cached box.  The smaller this number, the more times the working list of triangles that are considered for collision is refreshed.  This has the greatest impact with colliding with high triangle count meshes.
 3656
 3657@note Set to -1 to disable any time-based forced check.
 3658
 3659@ingroup GameObjects
 3660*/
 3661namespace $rigidPhysics { int workingQueryBoxStaleThreshold; } 
 3662/*!
 3663@var float $SB::CloakSpeed;
 3664@brief Time to cloak, in seconds.
 3665
 3666@ingroup gameObjects
 3667*/
 3668namespace $SB { float CloakSpeed; } 
 3669/*!
 3670@var float $pref::PSSM::smallestVisiblePixelSize;
 3671@brief The smallest pixel size an object can be and still be rendered into the PSSM shadow.
 3672Use this to force culling of small objects which contribute little to the final shadow.
 3673@see $pref::TS::smallestVisiblePixelSize
 3674@ingroup AdvancedLighting*/
 3675namespace $pref { namespace PSSM { float smallestVisiblePixelSize; }  } 
 3676/*!
 3677@var int $pref::Video::textureReductionLevel;
 3678@brief The number of mipmap levels to drop on loaded textures to reduce video memory usage.  It will skip any textures that have been defined as not allowing down scaling.
 3679
 3680@ingroup GFX
 3681*/
 3682namespace $pref { namespace Video { int textureReductionLevel; }  } 
 3683/*!
 3684@var string $pref::Client::DatablockCacheFilename;
 3685
 3686@ingroup UNDOCUMENTED
 3687*/
 3688namespace $pref { namespace Client { string DatablockCacheFilename; }  } 
 3689/*!
 3690@var float $rigidPhysics::workingQueryBoxSizeMultiplier;
 3691@brief How much larger the mWorkingQueryBox should be made when updating the working collision list.
 3692
 3693The larger this number the less often the working list will be updated due to motion, but any non-static shape that moves into the query box will not be noticed.
 3694
 3695@ingroup GameObjects
 3696*/
 3697namespace $rigidPhysics { float workingQueryBoxSizeMultiplier; } 
 3698/*!
 3699@var float $mvForwardAction;
 3700@brief Forwards movement speed for the active player.
 3701
 3702@ingroup Game*/
 3703float $mvForwardAction;
 3704/*!
 3705@var string $pref::Video::missingTexturePath;
 3706@brief The file path of the texture to display when the requested texture is missing.
 3707
 3708@ingroup GFX
 3709*/
 3710namespace $pref { namespace Video { string missingTexturePath; }  } 
 3711/*!
 3712@var bool $Pref::Server::EnableDatablockCache;
 3713
 3714@ingroup UNDOCUMENTED
 3715*/
 3716namespace $Pref { namespace Server { bool EnableDatablockCache; }  } 
 3717/*!
 3718@var float $mvBackwardAction;
 3719@brief Backwards movement speed for the active player.
 3720
 3721@ingroup Game*/
 3722float $mvBackwardAction;
 3723/*!
 3724@var int $pref::Net::PacketRateToServer;
 3725@brief Sets how often packets are sent from the client to the server.
 3726
 3727It is possible to control how often packets may be sent to the server.  This may be used to throttle the amount of bandwidth being used, but should be adjusted with caution.
 3728
 3729The actual formula used to calculate the delay between sending packets to the server is:
 3730@code
 3731Packet Update Delay To Server = 1024 / $pref::Net::PacketRateToServer@endcode
 3732with the result in ms.  A minimum rate of 8 is enforced in the source code.  The default value is 32.
 3733
 3734@note When using a local connection (@ref local_connections) be aware that this variable is always forced to 128.
 3735
 3736@ingroup Networking*/
 3737namespace $pref { namespace Net { int PacketRateToServer; }  } 
 3738/*!
 3739@var string $pref::Video::unavailableTexturePath;
 3740@brief The file path of the texture to display when the requested texture is unavailable.
 3741
 3742Often this texture is used by GUI controls to indicate that the request image is unavailable.
 3743@ingroup GFX
 3744*/
 3745namespace $pref { namespace Video { string unavailableTexturePath; }  } 
 3746/*!
 3747@var bool $pref::Client::EnableDatablockCache;
 3748
 3749@ingroup UNDOCUMENTED
 3750*/
 3751namespace $pref { namespace Client { bool EnableDatablockCache; }  } 
 3752/*!
 3753@var float $mvUpAction;
 3754@brief Upwards movement speed for the active player.
 3755
 3756@ingroup Game*/
 3757float $mvUpAction;
 3758/*!
 3759@var int $pref::Net::PacketRateToClient;
 3760@brief Sets how often packets are sent from the server to a client.
 3761
 3762It is possible to control how often packets may be sent to the clients.  This may be used to throttle the amount of bandwidth being used, but should be adjusted with caution.
 3763
 3764The actual formula used to calculate the delay between sending packets to a client is:
 3765@code
 3766Packet Update Delay To Client = 1024 / $pref::Net::PacketRateToClient@endcode
 3767with the result in ms.  A minimum rate of 1 is enforced in the source code.  The default value is 10.
 3768
 3769@note When using a local connection (@ref local_connections) be aware that this variable is always forced to 128.
 3770
 3771@ingroup Networking*/
 3772namespace $pref { namespace Net { int PacketRateToClient; }  } 
 3773/*!
 3774@var float $mvDownAction;
 3775@brief Downwards movement speed for the active player.
 3776
 3777@ingroup Game*/
 3778float $mvDownAction;
 3779/*!
 3780@var string $pref::Video::warningTexturePath;
 3781@brief The file path of the texture used to warn the developer.
 3782
 3783@ingroup GFX
 3784*/
 3785namespace $pref { namespace Video { string warningTexturePath; }  } 
 3786/*!
 3787@var int $TSControl::frameCount;
 3788@brief The number of frames that have been rendered since this control was created.
 3789
 3790@ingroup Rendering
 3791*/
 3792namespace $TSControl { int frameCount; } 
 3793/*!
 3794@var int $ProxMine::autoDeleteTicks;
 3795@brief Number of ticks until an exploded mine is deleted on the server.
 3796
 3797After a mine has exploded it remains in the server's scene graph for a time to allow its exploded state to be passed along to each client.  This variable controls how long a mine remains before it is deleted.  Any client that has not received the exploded state by then (perhaps due to lag) will not see any explosion produced by the mine.
 3798
 3799@ingroup GameObjects*/
 3800namespace $ProxMine { int autoDeleteTicks; } 
 3801/*!
 3802@var float $mvLeftAction;
 3803@brief Left movement speed for the active player.
 3804
 3805@ingroup Game*/
 3806float $mvLeftAction;
 3807/*!
 3808@var int $pref::Net::PacketSize;
 3809@brief Sets the maximum size in bytes an individual network packet may be.
 3810
 3811It is possible to control how large each individual network packet may be.  Increasing its size from the default allows for more data to be sent on each network send.  However, this value should be changed with caution as too large a value will cause packets to be split up by the networking platform or hardware, which is something Torque cannot handle.
 3812
 3813A minimum packet size of 100 bytes is enforced in the source code.  There is no enforced maximum.  The default value is 200 bytes.
 3814
 3815@note When using a local connection (@ref local_connections) be aware that this variable is always forced to 1024 bytes.
 3816
 3817@ingroup Networking*/
 3818namespace $pref { namespace Net { int PacketSize; }  } 
 3819/*!
 3820@var bool $TSControl::useLatestDisplayTransform;
 3821@brief Use the latest view transform when rendering stereo instead of the one calculated by the last move.
 3822
 3823@ingroup Rendering
 3824*/
 3825namespace $TSControl { bool useLatestDisplayTransform; } 
 3826/*!
 3827@var float $mvRightAction;
 3828@brief Right movement speed for the active player.
 3829
 3830@ingroup Game*/
 3831float $mvRightAction;
 3832/*!
 3833@var int $Stats::netBitsSent;
 3834@brief The number of bytes sent during the last packet send operation.
 3835
 3836@note Even though this variable has 'Bits' in it, the value is indeed reported in bytes.  This name is a legacy holdover and remains for compatibility reasons.
 3837@ingroup Networking*/
 3838namespace $Stats { int netBitsSent; } 
 3839/*!
 3840@var bool $mvFreeLook;
 3841@brief Boolean state for if freelook is active or not.
 3842
 3843@ingroup Game*/
 3844bool $mvFreeLook;
 3845/*!
 3846@var int $Stats::netBitsReceived;
 3847@brief The number of bytes received during the last packet process operation.
 3848
 3849@note Even though this variable has 'Bits' in it, the value is indeed reported in bytes.  This name is a legacy holdover and remains for compatibility reasons.
 3850@ingroup Networking*/
 3851namespace $Stats { int netBitsReceived; } 
 3852/*!
 3853@var GuiControl $ThisControl;
 3854@brief The control for which a command is currently being evaluated.  Only set during 'command' and altCommand callbacks to the control for which the command or altCommand is invoked.
 3855
 3856@ingroup GuiCore*/
 3857GuiControl $ThisControl;
 3858/*!
 3859@var bool $mvDeviceIsKeyboardMouse;
 3860@brief Boolean state for it the system is using a keyboard and mouse or not.
 3861
 3862@ingroup Game*/
 3863bool $mvDeviceIsKeyboardMouse;
 3864/*!
 3865@var int $Stats::netGhostUpdates;
 3866@brief The total number of ghosts added, removed, and/or updated on the client during the last packet process operation.
 3867
 3868@ingroup Networking*/
 3869namespace $Stats { int netGhostUpdates; } 
 3870/*!
 3871@var float $mvPitch;
 3872@brief Current pitch value, typically applied through input devices, such as a mouse.
 3873
 3874@ingroup Game*/
 3875float $mvPitch;
 3876/*!
 3877@var bool $pref::Audio::usePlayerCentricListener;
 3878
 3879@ingroup UNDOCUMENTED
 3880*/
 3881namespace $pref { namespace Audio { bool usePlayerCentricListener; }  } 
 3882/*!
 3883@var float $mvYaw;
 3884@brief Current yaw value, typically applied through input devices, such as a mouse.
 3885
 3886@ingroup Game*/
 3887float $mvYaw;
 3888/*!
 3889@var float $mvRoll;
 3890@brief Current roll value, typically applied through input devices, such as a mouse.
 3891
 3892@ingroup Game*/
 3893float $mvRoll;
 3894/*!
 3895@var float $mvPitchUpSpeed;
 3896@brief Upwards pitch speed.
 3897
 3898@ingroup Game*/
 3899float $mvPitchUpSpeed;
 3900/*!
 3901@var float $mvPitchDownSpeed;
 3902@brief Downwards pitch speed.
 3903
 3904@ingroup Game*/
 3905float $mvPitchDownSpeed;
 3906/*!
 3907@var float $mvYawLeftSpeed;
 3908@brief Left Yaw speed.
 3909
 3910@ingroup Game*/
 3911float $mvYawLeftSpeed;
 3912/*!
 3913@var float $mvYawRightSpeed;
 3914@brief Right Yaw speed.
 3915
 3916@ingroup Game*/
 3917float $mvYawRightSpeed;
 3918/*!
 3919@var float $mvRollLeftSpeed;
 3920@brief Left roll speed.
 3921
 3922@ingroup Game*/
 3923float $mvRollLeftSpeed;
 3924/*!
 3925@var float $mvRollRightSpeed;
 3926@brief Right roll speed.
 3927
 3928@ingroup Game*/
 3929float $mvRollRightSpeed;
 3930/*!
 3931@var bool $Con::logBufferEnabled;
 3932@brief If true, the log buffer will be enabled.
 3933
 3934@ingroup Console
 3935*/
 3936namespace $Con { bool logBufferEnabled; } 
 3937/*!
 3938@var float $mvXAxis_L;
 3939@brief Left thumbstick X axis position on a dual-analog gamepad.
 3940
 3941@ingroup Game*/
 3942float $mvXAxis_L;
 3943/*!
 3944@var float $mvYAxis_L;
 3945@brief Left thumbstick Y axis position on a dual-analog gamepad.
 3946
 3947@ingroup Game*/
 3948float $mvYAxis_L;
 3949/*!
 3950@var int $Con::printLevel;
 3951@brief This is deprecated.
 3952
 3953It is no longer in use and does nothing.
 3954@ingroup Console
 3955*/
 3956namespace $Con { int printLevel; } 
 3957/*!
 3958@var float $pref::WorldEditor::visibleDistanceScale;
 3959@brief Scale factor for the visible render distance.
 3960
 3961@ingroup */
 3962namespace $pref { namespace WorldEditor { float visibleDistanceScale; }  } 
 3963/*!
 3964@var float $mvXAxis_R;
 3965@brief Right thumbstick X axis position on a dual-analog gamepad.
 3966
 3967@ingroup Game*/
 3968float $mvXAxis_R;
 3969/*!
 3970@var bool $Con::warnUndefinedVariables;
 3971@brief If true, a warning will be displayed in the console whenever a undefined variable is used in script.
 3972
 3973@ingroup Console
 3974*/
 3975namespace $Con { bool warnUndefinedVariables; } 
 3976/*!
 3977@var float $mvYAxis_R;
 3978@brief Right thumbstick Y axis position on a dual-analog gamepad.
 3979
 3980@ingroup Game*/
 3981float $mvYAxis_R;
 3982/*!
 3983@var int $mvTriggerCount0;
 3984@brief Used to determine the trigger counts of buttons. Namely used for input actions such as jumping and weapons firing.
 3985
 3986@ingroup Game*/
 3987int $mvTriggerCount0;
 3988/*!
 3989@var string $instantGroup;
 3990@brief The group that objects will be added to when they are created.
 3991
 3992@ingroup Console
 3993*/
 3994string $instantGroup;
 3995/*!
 3996@var float $pref::WorldEditor::cameraFOV;
 3997@brief Field of view for editor's perspective camera, in degrees.
 3998
 3999@ingroup */
 4000namespace $pref { namespace WorldEditor { float cameraFOV; }  } 
 4001/*!
 4002@var int $Con::objectCopyFailures;
 4003@brief If greater than zero then it counts the number of object creation failures based on a missing copy object and does not report an error..
 4004
 4005@ingroup Console
 4006*/
 4007namespace $Con { int objectCopyFailures; } 
 4008/*!
 4009@var int $mvTriggerCount1;
 4010@brief Used to determine the trigger counts of buttons. Namely used for input actions such as jumping and weapons firing.
 4011
 4012@ingroup Game*/
 4013int $mvTriggerCount1;
 4014/*!
 4015@var int $mvTriggerCount2;
 4016@brief Used to determine the trigger counts of buttons. Namely used for input actions such as jumping and weapons firing.
 4017
 4018@ingroup Game*/
 4019int $mvTriggerCount2;
 4020/*!
 4021@var string $Con::File;
 4022@brief The currently executing script file.
 4023
 4024@ingroup FileSystem
 4025*/
 4026namespace $Con { string File; } 
 4027/*!
 4028@var filename $pref::afxSpellButton::unknownSpellBitmap;
 4029
 4030@ingroup UNDOCUMENTED
 4031*/
 4032namespace $pref { namespace afxSpellButton { filename unknownSpellBitmap; }  } 
 4033/*!
 4034@var string $Con::Root;
 4035@brief The mod folder for the currently executing script file.
 4036
 4037@ingroup FileSystem
 4038*/
 4039namespace $Con { string Root; } 
 4040/*!
 4041@var int $mvTriggerCount3;
 4042@brief Used to determine the trigger counts of buttons. Namely used for input actions such as jumping and weapons firing.
 4043
 4044@ingroup Game*/
 4045int $mvTriggerCount3;
 4046/*!
 4047@var float $pref::maxProbeDrawDistance;
 4048@brief Max distance for reflection probes to render.
 4049
 4050
 4051@ingroup UNDOCUMENTED
 4052*/
 4053namespace $pref { float maxProbeDrawDistance; } 
 4054/*!
 4055@var bool $Con::alwaysUseDebugOutput;
 4056@brief Determines whether to send output to the platform's "debug" system.
 4057
 4058@note This is disabled in shipping builds.
 4059@ingroup Console*/
 4060namespace $Con { bool alwaysUseDebugOutput; } 
 4061/*!
 4062@var int $mvTriggerCount4;
 4063@brief Used to determine the trigger counts of buttons. Namely used for input actions such as jumping and weapons firing.
 4064
 4065@ingroup Game*/
 4066int $mvTriggerCount4;
 4067/*!
 4068@var filename $pref::afxSpellButton::spellCooldownBitmaps;
 4069
 4070@ingroup UNDOCUMENTED
 4071*/
 4072namespace $pref { namespace afxSpellButton { filename spellCooldownBitmaps; }  } 
 4073/*!
 4074@var int $pref::MaxProbesPerFrame;
 4075@brief Max number of Environment Probes that can be rendered per-frame.
 4076
 4077
 4078@ingroup UNDOCUMENTED
 4079*/
 4080namespace $pref { int MaxProbesPerFrame; } 
 4081/*!
 4082@var bool $Con::useTimestamp;
 4083@brief If true a timestamp is prepended to every console message.
 4084
 4085@ingroup Console
 4086*/
 4087namespace $Con { bool useTimestamp; } 
 4088/*!
 4089@var int $mvTriggerCount5;
 4090@brief Used to determine the trigger counts of buttons. Namely used for input actions such as jumping and weapons firing.
 4091
 4092@ingroup Game*/
 4093int $mvTriggerCount5;
 4094/*!
 4095@var bool $Light::renderViz;
 4096@brief Toggles visualization of light object's radius or cone.
 4097
 4098@ingroup Lighting*/
 4099namespace $Light { bool renderViz; } 
 4100/*!
 4101@var bool $Con::useRealTimestamp;
 4102@brief If true a date and time will be prepended to every console message.
 4103
 4104@ingroup Console
 4105*/
 4106namespace $Con { bool useRealTimestamp; } 
 4107/*!
 4108@var bool $Light::renderLightFrustums;
 4109@brief Toggles rendering of light frustums when the light is selected in the editor.
 4110
 4111
 4112@note Only works for shadow mapped lights.
 4113
 4114@ingroup Lighting*/
 4115namespace $Light { bool renderLightFrustums; } 
 4116/*!
 4117@var int $BasicLightManagerStats::activePlugins;
 4118@brief The number of active Basic Lighting SceneObjectLightingPlugin objects this frame.
 4119
 4120@ingroup BasicLighting
 4121*/
 4122namespace $BasicLightManagerStats { int activePlugins; } 
 4123/*!
 4124@var int $platform::backgroundSleepTime;
 4125@brief Controls processor time usage when the game window is out of focus.
 4126
 4127@ingroup Platform
 4128*/
 4129namespace $platform { int backgroundSleepTime; } 
 4130/*!
 4131@var int $BasicLightManagerStats::shadowsUpdated;
 4132@brief The number of Basic Lighting shadows updated this frame.
 4133
 4134@ingroup BasicLighting
 4135*/
 4136namespace $BasicLightManagerStats { int shadowsUpdated; } 
 4137/*!
 4138@var int $platform::timeManagerProcessInterval;
 4139@brief Controls processor time usage when the game window is in focus.
 4140
 4141@ingroup Platform
 4142*/
 4143namespace $platform { int timeManagerProcessInterval; } 
 4144/*!
 4145@var int $BasicLightManagerStats::elapsedUpdateMs;
 4146@brief The number of milliseconds spent this frame updating Basic Lighting shadows.
 4147
 4148@ingroup BasicLighting
 4149*/
 4150namespace $BasicLightManagerStats { int elapsedUpdateMs; } 
 4151/*!
 4152@var float $BasicLightManager::shadowFilterDistance;
 4153@brief The maximum distance in meters that projected shadows will get soft filtering.
 4154
 4155@ingroup BasicLighting
 4156*/
 4157namespace $BasicLightManager { float shadowFilterDistance; } 
 4158/*!
 4159@var float $pref::ProjectedShadow::fadeStartPixelSize;
 4160@brief A size in pixels at which BL shadows begin to fade out. This should be a larger value than fadeEndPixelSize.
 4161
 4162@see DecalData
 4163@ingroup BasicLighting
 4164*/
 4165namespace $pref { namespace ProjectedShadow { float fadeStartPixelSize; }  } 
 4166/*!
 4167@var bool $Light::renderReflectionProbes;
 4168@brief Toggles rendering of light frustums when the light is selected in the editor.
 4169
 4170
 4171@note Only works for shadow mapped lights.
 4172
 4173@ingroup Lighting*/
 4174namespace $Light { bool renderReflectionProbes; } 
 4175/*!
 4176@var float $pref::ProjectedShadow::fadeEndPixelSize;
 4177@brief A size in pixels at which BL shadows are fully faded out. This should be a smaller value than fadeStartPixelSize.
 4178
 4179@see DecalData
 4180@ingroup BasicLighting
 4181*/
 4182namespace $pref { namespace ProjectedShadow { float fadeEndPixelSize; }  } 
 4183/*!
 4184@var bool $Light::renderPreviewProbes;
 4185@brief Toggles rendering of light frustums when the light is selected in the editor.
 4186
 4187
 4188@note Only works for shadow mapped lights.
 4189
 4190@ingroup Lighting*/
 4191namespace $Light { bool renderPreviewProbes; } 
 4192/*!
 4193@var bool $Physics::isSinglePlayer;
 4194@brief Informs the physics simulation if only a single player exists.
 4195
 4196If true, optimizations will be implemented to better cater to a single player environmnent.
 4197
 4198@ingroup Physics
 4199*/
 4200namespace $Physics { bool isSinglePlayer; } 
 4201/*!
 4202@var bool $Physics::gpuAccelerationAllowed;
 4203@brief Informs the physics plugin if it is allowed to use gpu acceleration.
 4204
 4205Not all physics implemenations or gpus can support gpu acceleration, this simply informs the plugin if it is allowed to try and use it or not.
 4206
 4207@ingroup Physics
 4208*/
 4209namespace $Physics { bool gpuAccelerationAllowed; } 
 4210/*!
 4211@var int $pref::Physics::threadCount;
 4212@brief Number of threads to use in a single pass of the physics engine.
 4213
 4214Defaults to 2 if not set.
 4215
 4216@ingroup Physics
 4217*/
 4218namespace $pref { namespace Physics { int threadCount; }  } 
 4219/*!
 4220@var bool $pref::Input::JoystickEnabled;
 4221@brief If true, Joystick devices will be automatically opened.
 4222
 4223
 4224@ingroup Input*/
 4225namespace $pref { namespace Input { bool JoystickEnabled; }  } 
 4226/*!
 4227@var float $pref::Camera::distanceScale;
 4228@brief A scale to apply to the normal visible distance, typically used for tuning performance.
 4229
 4230@ingroup Game*/
 4231namespace $pref { namespace Camera { float distanceScale; }  } 
 4232/*!
 4233@var bool $pref::Input::JoystickSplitAxesLR;
 4234@brief Split axis inputs on 4 axis joysticks. This has no effect on any other device.
 4235
 4236
 42374 Axis joysticks use IDs 0-3 which get mapped to xaxis, yaxis, zaxis and rxaxis. When true, this will increment IDs 2 and 3 so the inputs map to xaxis, yaxis, rxaxis and ryaxis.
 4238@ingroup Input*/
 4239namespace $pref { namespace Input { bool JoystickSplitAxesLR; }  } 
 4240/*!
 4241@var bool $pref::enableBadWordFilter;
 4242@brief If true, the bad word filter will be enabled.
 4243
 4244@ingroup Game*/
 4245namespace $pref { bool enableBadWordFilter; } 
 4246/*!
 4247@var float $cameraFov;
 4248@brief The camera's Field of View.
 4249
 4250
 4251@ingroup Game*/
 4252float $cameraFov;
 4253/*!
 4254@var string $pref::TSShapeConstructor::CapsuleShapePath;
 4255@brief The file path to the capsule shape used by tsMeshFit.
 4256
 4257
 4258@ingroup MeshFit
 4259*/
 4260namespace $pref { namespace TSShapeConstructor { string CapsuleShapePath; }  } 
 4261/*!
 4262@var bool $pref::Input::sdlControllerEnabled;
 4263@brief If true, any Joystick device that SDL recognizes as a Game Controller will be automatically opened as a game controller.
 4264
 4265
 4266@ingroup Input*/
 4267namespace $pref { namespace Input { bool sdlControllerEnabled; }  } 
 4268/*!
 4269@var float $timeScale;
 4270@brief Animation time scale.
 4271
 4272@ingroup platform*/
 4273float $timeScale;
 4274/*!
 4275@var string $Core::DefaultIrradianceCubemap;
 4276@brief The file path of the texture used as the default irradiance cubemap for PBR.
 4277
 4278@ingroup GFX
 4279*/
 4280namespace $Core { string DefaultIrradianceCubemap; } 
 4281/*!
 4282@var int $timeAdvance;
 4283@brief The speed at which system processing time advances.
 4284
 4285@ingroup platform*/
 4286int $timeAdvance;
 4287/*!
 4288@var bool $pref::Input::JoystickPOVButtons;
 4289@brief If true, the pov hat will be treated as 4 buttons and make/break events will be generated for upov, dpov, lpov and rpov.
 4290
 4291@ingroup Input*/
 4292namespace $pref { namespace Input { bool JoystickPOVButtons; }  } 
 4293/*!
 4294@var string $pref::TSShapeConstructor::CubeShapePath;
 4295@brief The file path to the cube shape used by tsMeshFit.
 4296
 4297
 4298@ingroup MeshFit
 4299*/
 4300namespace $pref { namespace TSShapeConstructor { string CubeShapePath; }  } 
 4301/*!
 4302@var int $frameSkip;
 4303@brief Sets the number of frames to skip while rendering the scene.
 4304
 4305@ingroup platform*/
 4306int $frameSkip;
 4307/*!
 4308@var string $Core::DefaultPrefilterCubemap;
 4309@brief The file path of the texture used as the default specular cubemap for PBR.
 4310
 4311@ingroup GFX
 4312*/
 4313namespace $Core { string DefaultPrefilterCubemap; } 
 4314/*!
 4315@var bool $pref::Input::JoystickPOVMask;
 4316@brief If true, the pov hat will be treated as a single input with a 4 bit mask value. The povmask event will be generated with the current mask every time the mask value changes.
 4317
 4318@ingroup Input*/
 4319namespace $pref { namespace Input { bool JoystickPOVMask; }  } 
 4320/*!
 4321@var string $pref::TSShapeConstructor::SphereShapePath;
 4322@brief The file path to the sphere shape used by tsMeshFit.
 4323
 4324
 4325@ingroup MeshFit
 4326*/
 4327namespace $pref { namespace TSShapeConstructor { string SphereShapePath; }  } 
 4328/*!
 4329@var string $Core::BRDFTexture;
 4330@brief The file path of the texture used as the default irradiance cubemap for PBR.
 4331
 4332@ingroup GFX
 4333*/
 4334namespace $Core { string BRDFTexture; } 
 4335/*!
 4336@var bool $pref::Water::disableTrueReflections;
 4337@brief Force all water objects to use static cubemap reflections.
 4338
 4339@ingroup Water*/
 4340namespace $pref { namespace Water { bool disableTrueReflections; }  } 
 4341/*!
 4342@var bool $_forceAllMainThread;
 4343@brief Force all work items to execute on main thread. turns this into a single-threaded system. Primarily useful to find whether malfunctions are caused by parallel execution or not.
 4344
 4345@ingroup platform*/
 4346bool $_forceAllMainThread;
 4347/*!
 4348@var int $pref::afxCamera::collisionMask;
 4349
 4350@ingroup UNDOCUMENTED
 4351*/
 4352namespace $pref { namespace afxCamera { int collisionMask; }  } 
 4353/*!
 4354@var int $Sampler::frequency;
 4355@brief Samples taken every nth frame.
 4356
 4357@ingroup Rendering*/
 4358namespace $Sampler { int frequency; } 
 4359/*!
 4360@var int $pref::AFX::targetSelectionMask;
 4361
 4362@ingroup UNDOCUMENTED
 4363*/
 4364namespace $pref { namespace AFX { int targetSelectionMask; }  } 
 4365/*!
 4366@var int $pref::AFX::freeTargetSelectionMask;
 4367
 4368@ingroup UNDOCUMENTED
 4369*/
 4370namespace $pref { namespace AFX { int freeTargetSelectionMask; }  } 
 4371/*!
 4372@var bool $pref::Decals::enabled;
 4373@brief Controls whether decals are rendered.
 4374
 4375@ingroup Decals*/
 4376namespace $pref { namespace Decals { bool enabled; }  } 
 4377/*!
 4378@var int $SFX::numSources;
 4379@brief Number of SFXSource type objects that are currently instantiated.
 4380
 4381@ingroup SFX*/
 4382namespace $SFX { int numSources; } 
 4383/*!
 4384@var float $pref::Decals::lifeTimeScale;
 4385@brief Lifetime that decals will last after being created in the world.
 4386Deprecated. Use DecalData::lifeSpan instead.
 4387@ingroup Decals*/
 4388namespace $pref { namespace Decals { float lifeTimeScale; }  } 
 4389/*!
 4390@var float $pref::AFX::targetSelectionRange;
 4391
 4392@ingroup UNDOCUMENTED
 4393*/
 4394namespace $pref { namespace AFX { float targetSelectionRange; }  } 
 4395/*!
 4396@var int $SFX::numSounds;
 4397@brief Number of SFXSound type objects (i.e. actual single-file sounds) that are currently instantiated.
 4398
 4399@ingroup SFX*/
 4400namespace $SFX { int numSounds; } 
 4401/*!
 4402@var bool $pref::Player::corpsesHiddenFromRayCast;
 4403
 4404@ingroup UNDOCUMENTED
 4405*/
 4406namespace $pref { namespace Player { bool corpsesHiddenFromRayCast; }  } 
 4407/*!
 4408@var bool $Decals::poolBuffers;
 4409@brief If true, will merge all PrimitiveBuffers and VertexBuffers into a pair of pools before clearing them at the end of a frame.
 4410
 4411If false, will just clear them at the end of a frame.
 4412@ingroup Decals*/
 4413namespace $Decals { bool poolBuffers; } 
 4414/*!
 4415@var int $SFX::numPlaying;
 4416@brief Number of SFXSources that are currently in playing state.
 4417
 4418@ingroup SFX*/
 4419namespace $SFX { int numPlaying; } 
 4420/*!
 4421@var int $pref::AFX::targetSelectionTimeoutMS;
 4422
 4423@ingroup UNDOCUMENTED
 4424*/
 4425namespace $pref { namespace AFX { int targetSelectionTimeoutMS; }  } 
 4426/*!
 4427@var bool $Decals::debugRender;
 4428@brief If true, the decal spheres will be visualized when in the editor.
 4429
 4430
 4431@ingroup Decals*/
 4432namespace $Decals { bool debugRender; } 
 4433/*!
 4434@var int $SFX::numCulled;
 4435@brief Number of SFXSounds that are currently in virtualized playback mode.
 4436
 4437@ref SFXSound_virtualization
 4438
 4439@ingroup SFX*/
 4440namespace $SFX { int numCulled; } 
 4441/*!
 4442@var int $pref::AFX::missileCollisionMask;
 4443
 4444@ingroup UNDOCUMENTED
 4445*/
 4446namespace $pref { namespace AFX { int missileCollisionMask; }  } 
 4447/*!
 4448@var int $SFX::numVoices;
 4449@brief Number of voices that are currently allocated on the sound device.
 4450
 4451@ingroup SFX*/
 4452namespace $SFX { int numVoices; } 
 4453/*!
 4454@var float $Decals::sphereDistanceTolerance;
 4455@brief The distance at which the decal system will start breaking up decal spheres when adding new decals.
 4456
 4457
 4458@ingroup Decals*/
 4459namespace $Decals { float sphereDistanceTolerance; } 
 4460/*!
 4461@var int $SFX::sourceUpdateTime;
 4462@brief Milliseconds spent on the last SFXSource update loop.
 4463
 4464@ref SFX_updating
 4465
 4466@ingroup SFX*/
 4467namespace $SFX { int sourceUpdateTime; } 
 4468/*!
 4469@var bool $pref::AFX::clickToTargetSelf;
 4470
 4471@ingroup UNDOCUMENTED
 4472*/
 4473namespace $pref { namespace AFX { bool clickToTargetSelf; }  } 
 4474/*!
 4475@var float $Decals::sphereRadiusTolerance;
 4476@brief The radius beyond which the decal system will start breaking up decal spheres when adding new decals.
 4477
 4478
 4479@ingroup Decals*/
 4480namespace $Decals { float sphereRadiusTolerance; } 
 4481/*!
 4482@var int $SFX::parameterUpdateTime;
 4483@brief Milliseconds spent on the last SFXParameter update loop.
 4484
 4485@ref SFX_updating
 4486
 4487@ref SFX_interactive
 4488
 4489@ingroup SFX*/
 4490namespace $SFX { int parameterUpdateTime; } 
 4491/*!
 4492@var string $Pref::Server::AFX::parameterFieldPrefix;
 4493
 4494@ingroup UNDOCUMENTED
 4495*/
 4496namespace $Pref { namespace Server { namespace AFX { string parameterFieldPrefix; }  }  } 
 4497/*!
 4498@var int $SFX::ambientUpdateTime;
 4499@brief Milliseconds spent on the last ambient audio update.
 4500
 4501@ref SFX_updating
 4502
 4503@ref SFX_ambient
 4504
 4505@ingroup SFX*/
 4506namespace $SFX { int ambientUpdateTime; } 
 4507/*!
 4508@var int $SFX::DEVICE_CAPS_REVERB;
 4509@brief Sound device capability flag indicating that the sound device supports reverb.
 4510
 4511
 4512@note Currently only FMOD implements this.
 4513
 4514@see sfxGetDeviceInfo
 4515
 4516@ref SFX_reverb
 4517
 4518@ingroup SFX*/
 4519namespace $SFX { const int DEVICE_CAPS_REVERB; } 
 4520/*!
 4521@var float $pref::AFX::terrainZodiacZBias;
 4522
 4523@ingroup UNDOCUMENTED
 4524*/
 4525namespace $pref { namespace AFX { float terrainZodiacZBias; }  } 
 4526/*!
 4527@var int $SFX::DEVICE_CAPS_VOICEMANAGEMENT;
 4528@brief Sound device capability flag indicating that the sound device implements its own voice virtualization.
 4529
 4530
 4531For these devices, the sound system will deactivate its own voice management and leave voice virtualization entirely to the device.
 4532
 4533@note Currently only FMOD implements this.
 4534
 4535@see sfxGetDeviceInfo
 4536
 4537@ref SFXSound_virtualization
 4538
 4539@ingroup SFX*/
 4540namespace $SFX { const int DEVICE_CAPS_VOICEMANAGEMENT; } 
 4541/*!
 4542@var float $pref::AFX::interiorZodiacZBias;
 4543
 4544@ingroup UNDOCUMENTED
 4545*/
 4546namespace $pref { namespace AFX { float interiorZodiacZBias; }  } 
 4547/*!
 4548@var int $SFX::DEVICE_CAPS_OCCLUSION;
 4549@brief Sound device capability flag indicating that the sound device implements sound occlusion.
 4550
 4551
 4552@note This is not yet used by the sound system.
 4553
 4554@see sfxGetDeviceInfo
 4555
 4556@ingroup SFX*/
 4557namespace $SFX { const int DEVICE_CAPS_OCCLUSION; } 
 4558/*!
 4559@var float $pref::AFX::polysoupZodiacZBias;
 4560
 4561@ingroup UNDOCUMENTED
 4562*/
 4563namespace $pref { namespace AFX { float polysoupZodiacZBias; }  } 
 4564/*!
 4565@var int $SFX::DEVICE_CAPS_DSPEFFECTS;
 4566@brief Sound device capability flag indicating that the sound device supports adding DSP effect chains to sounds.
 4567
 4568
 4569@see sfxGetDeviceInfo
 4570
 4571@note This is not yet used by the sound system.
 4572
 4573@see sfxGetDeviceInfo
 4574
 4575@ingroup SFX*/
 4576namespace $SFX { const int DEVICE_CAPS_DSPEFFECTS; } 
 4577/*!
 4578@var int $pref::VolumetricFog::Quality;
 4579@brief The scale of the rendertargets.
 4580
 4581@ingroup Rendering
 4582*/
 4583namespace $pref { namespace VolumetricFog { int Quality; }  } 
 4584/*!
 4585@var float $pref::GroundCover::densityScale;
 4586@brief A global LOD scalar which can reduce the overall density of placed GroundCover.
 4587
 4588@ingroup Foliage
 4589*/
 4590namespace $pref { namespace GroundCover { float densityScale; }  } 
 4591/*!
 4592@var int $SFX::DEVICE_CAPS_MULTILISTENER;
 4593@brief Sound device capability flag indicating that the sound device supports multiple concurrent listeners.
 4594
 4595
 4596@note Currently only FMOD implements this.
 4597
 4598@see sfxGetDeviceInfo
 4599
 4600@ingroup SFX*/
 4601namespace $SFX { const int DEVICE_CAPS_MULTILISTENER; } 
 4602/*!
 4603@var float $pref::GroundCover::fadeScale;
 4604@brief A global fade scalar which can reduce the overall rendered distance of placed GroundCover.
 4605
 4606@ingroup Foliage
 4607*/
 4608namespace $pref { namespace GroundCover { float fadeScale; }  } 
 4609/*!
 4610@var int $SFX::DEVICE_CAPS_FMODDESIGNER;
 4611@brief Sound device capability flag indicating that the sound device supports FMOD Designer audio projects.
 4612
 4613
 4614@note This is exclusive to FMOD.  If the FMOD Event DLLs are in place and could be successfully loaded, this flag will be set after initializating an FMOD audio device.
 4615
 4616@see sfxGetDeviceInfo
 4617
 4618@ref FMOD_designer
 4619
 4620@ingroup SFX*/
 4621namespace $SFX { const int DEVICE_CAPS_FMODDESIGNER; } 
 4622/*!
 4623@var int $SFX::DEVICE_INFO_PROVIDER;
 4624@brief Index of sound provider field in device info string.
 4625
 4626
 4627@see sfxGetDeviceInfo
 4628
 4629@see sfxGetAvailableDevices
 4630
 4631@ingroup SFX*/
 4632namespace $SFX { const int DEVICE_INFO_PROVIDER; } 
 4633/*!
 4634@var ShadowFilterMode $pref::shadows::filterMode;
 4635@brief The filter mode to use for shadows.
 4636
 4637@ingroup AdvancedLighting
 4638*/
 4639namespace $pref { namespace shadows { ShadowFilterMode filterMode; }  } 
 4640/*!
 4641@var int $SFX::DEVICE_INFO_NAME;
 4642@brief Index of device name field in device info string.
 4643
 4644
 4645@see sfxGetDeviceInfo
 4646
 4647@see sfxGetAvailableDevices
 4648
 4649@ingroup SFX*/
 4650namespace $SFX { const int DEVICE_INFO_NAME; } 
 4651/*!
 4652@var bool $AL::UseSSAOMask;
 4653@brief Used by the SSAO PostEffect to toggle the sampling of ssaomask texture by the light shaders.
 4654
 4655@ingroup AdvancedLighting
 4656*/
 4657namespace $AL { bool UseSSAOMask; } 
 4658/*!
 4659@var bool $AL::PSSMDebugRender;
 4660@brief Enables debug rendering of the PSSM shadows.
 4661
 4662@ingroup AdvancedLighting
 4663*/
 4664namespace $AL { bool PSSMDebugRender; } 
 4665/*!
 4666@var int $SFX::DEVICE_INFO_USEHARDWARE;
 4667@brief Index of use hardware flag in device info string.
 4668
 4669
 4670@see sfxGetDeviceInfo
 4671
 4672@see sfxGetAvailableDevices
 4673
 4674@ingroup SFX*/
 4675namespace $SFX { const int DEVICE_INFO_USEHARDWARE; } 
 4676/*!
 4677@var int $Ease::InOut;
 4678@brief InOut ease for curve movement.
 4679
 4680@ingroup Game*/
 4681namespace $Ease { int InOut; } 
 4682/*!
 4683@var bool $AL::DiffuseLightViz;
 4684@brief Enables debug rendering of the PSSM shadows.
 4685
 4686@ingroup AdvancedLighting
 4687*/
 4688namespace $AL { bool DiffuseLightViz; } 
 4689/*!
 4690@var int $SFX::DEVICE_INFO_MAXBUFFERS;
 4691@brief Index of buffer limit number in device info string.
 4692
 4693
 4694@see sfxGetDeviceInfo
 4695
 4696@see sfxGetAvailableDevices
 4697
 4698@ingroup SFX*/
 4699namespace $SFX { const int DEVICE_INFO_MAXBUFFERS; } 
 4700/*!
 4701@var int $Ease::In;
 4702@brief In ease for curve movement.
 4703
 4704@ingroup Game*/
 4705namespace $Ease { int In; } 
 4706/*!
 4707@var bool $AL::SpecularLightViz;
 4708@brief Enables debug rendering of the PSSM shadows.
 4709
 4710@ingroup AdvancedLighting
 4711*/
 4712namespace $AL { bool SpecularLightViz; } 
 4713/*!
 4714@var int $Ease::Out;
 4715@brief Out ease for curve movement.
 4716
 4717@ingroup Game*/
 4718namespace $Ease { int Out; } 
 4719/*!
 4720@var int $SFX::DEVICE_INFO_CAPS;
 4721@brief Index of device capability flags in device info string.
 4722
 4723
 4724@see sfxGetDeviceInfo
 4725
 4726@see sfxGetAvailableDevices
 4727
 4728@ingroup SFX*/
 4729namespace $SFX { const int DEVICE_INFO_CAPS; } 
 4730/*!
 4731@var int $Ease::Linear;
 4732@brief Linear ease for curve movement.
 4733
 4734@ingroup Game*/
 4735namespace $Ease { int Linear; } 
 4736/*!
 4737@var bool $AL::DetailLightingViz;
 4738@brief Enables debug rendering of the PSSM shadows.
 4739
 4740@ingroup AdvancedLighting
 4741*/
 4742namespace $AL { bool DetailLightingViz; } 
 4743/*!
 4744@var int $Ease::Quadratic;
 4745@brief Quadratic ease for curve movement.
 4746
 4747@ingroup Game*/
 4748namespace $Ease { int Quadratic; } 
 4749/*!
 4750@brief Add a string to the bad word filter
 4751
 4752The bad word filter is a table containing words which will not be displayed in chat windows. Instead, a designated replacement string will be displayed.  There are already a number of bad words automatically defined.
 4753
 4754@param badWord Exact text of the word to restrict.
 4755@return True if word was successfully added, false if the word or a subset of it already exists in the table
 4756@see filterString()
 4757
 4758@tsexample
 4759// In this game, "Foobar" is banned
 4760%badWord = "Foobar";
 4761
 4762// Returns true, word was successfully added
 4763addBadWord(%badWord);
 4764
 4765// Returns false, word has already been added
 4766addBadWord("Foobar");@endtsexample
 4767@ingroup Game*/
 4768bool addBadWord( string badWord );
 4769/*!
 4770@brief Replaces the characters in a string with designated text
 4771
 4772Uses the bad word filter to determine which characters within the string will be replaced.
 4773
 4774@param baseString  The original string to filter.
 4775@param replacementChars A string containing letters you wish to swap in the baseString.
 4776@return The new scrambled string 
 4777@see addBadWord()
 4778@see containsBadWords()
 4779@tsexample
 4780// Create the base string, can come from anywhere
 4781%baseString = "Foobar";
 4782
 4783// Create a string of random letters
 4784%replacementChars = "knqwrtlzs";
 4785
 4786// Filter the string
 4787%newString = filterString(%baseString, %replacementChars);
 4788
 4789// Print the new string to console
 4790echo(%newString);@endtsexample
 4791@ingroup Game*/
 4792string filterString( string baseString=nullAsType<const char*>(), string replacementChars=nullAsType<const char*>() );
 4793/*!
 4794@brief Checks to see if text is a bad word
 4795
 4796The text is considered to be a bad word if it has been added to the bad word filter.
 4797
 4798@param text Text to scan for bad words
 4799@return True if the text has bad word(s), false if it is clean
 4800@see addBadWord()
 4801@see filterString()
 4802@tsexample
 4803// In this game, "Foobar" is banned
 4804%badWord = "Foobar";
 4805
 4806// Add a banned word to the bad word filter
 4807addBadWord(%badWord);
 4808
 4809// Create the base string, can come from anywhere like user chat
 4810%userText = "Foobar";
 4811
 4812// Create a string of random letters
 4813%replacementChars = "knqwrtlzs";
 4814
 4815// If the text contains a bad word, filter it before printing
 4816// Otherwise print the original text
 4817if(containsBadWords(%userText))
 4818{
 4819  // Filter the string
 4820  %filteredText = filterString(%userText, %replacementChars);
 4821
 4822  // Print filtered text
 4823  echo(%filteredText);
 4824}
 4825else
 4826  echo(%userText);
 4827
 4828@endtsexample
 4829@ingroup Game*/
 4830bool containsBadWords( string text );
 4831/*!
 4832@brief Disables DirectInput.
 4833
 4834Also deactivates any connected joysticks.
 4835
 4836@ingroup Input*/
 4837void deactivateDirectInput();
 4838/*!
 4839@brief Activates DirectInput.
 4840
 4841Also activates any connected joysticks.@ingroup Input*/
 4842void activateDirectInput();
 4843/*!
 4844@brief strToPlayerName(string);
 4845
 4846
 4847@ingroup UNDOCUMENTED
 4848*/
 4849string strToPlayerName( string ptr );
 4850/*!
 4851@brief Lock or unlock the mouse to the window.
 4852
 4853When true, prevents the mouse from leaving the bounds of the game window.
 4854
 4855@ingroup Input*/
 4856void lockMouse( bool isLocked );
 4857/*!
 4858@brief Set the network port for the game to use.
 4859
 4860@param port The port to use.
 4861@param bind True if bind() should be called on the port.
 4862@returns True if the port was successfully opened.
 4863This will trigger a windows firewall prompt.  If you don't have firewall tunneling tech you can set this to false to avoid the prompt.
 4864
 4865@ingroup Networking*/
 4866bool setNetPort( int port, bool bind=true );
 4867/*!
 4868@brief Determines if a specified address type can be reached.
 4869
 4870@ingroup Networking*/
 4871bool isAddressTypeAvailable( int addressType );
 4872/*!
 4873@brief Closes the current network port
 4874
 4875@ingroup Networking*/
 4876void closeNetPort();
 4877/*!
 4878@brief Save the journal to the specified file.
 4879
 4880
 4881@ingroup Platform*/
 4882void saveJournal( string filename );
 4883/*!
 4884@brief Begin playback of a journal from a specified field.
 4885
 4886@param filename Name and path of file journal file
 4887@ingroup Platform*/
 4888void playJournal( string filename );
 4889/*!
 4890Return the current sim time in milliseconds.
 4891
 4892@brief Sim time is time since the game started.
 4893
 4894@ingroup Platform*/
 4895int getSimTime();
 4896/*!
 4897@brief Return the current real time in milliseconds.
 4898
 4899Real time is platform defined; typically time since the computer booted.
 4900
 4901@ingroup Platform*/
 4902int getRealTime();
 4903/*!
 4904@brief Return the current local time as: weekday month day year hour min sec.
 4905
 4906Local time is platform defined.@ingroup Platform*/
 4907string getLocalTime();
 4908/*!
 4909@brief Send a command to the server.
 4910
 4911@param func Name of the server command being called
 4912@param ... Various parameters being passed to server command
 4913
 4914@tsexample
 4915// Create a standard function.  Needs to be executed on the client, such 
 4916// as within scripts/client/default.bind.cs
 4917function toggleCamera(%val)
 4918{
 4919   // If key was down, call a server command named 'ToggleCamera'
 4920   if (%val)
 4921      commandToServer('ToggleCamera');
 4922}
 4923
 4924// Server command being called from above.  Needs to be executed on the 
 4925// server, such as within scripts/server/commands.cs
 4926function serverCmdToggleCamera(%client)
 4927{
 4928   if (%client.getControlObject() == %client.player)
 4929   {
 4930     %client.camera.setVelocity("0 0 0");
 4931     %control = %client.camera;
 4932   }
 4933   else
 4934   {
 4935     %client.player.setVelocity("0 0 0");
 4936     %control = %client.player;
 4937  }
 4938   %client.setControlObject(%control);
 4939   clientCmdSyncEditorGui();
 4940}
 4941@endtsexample
 4942
 4943@ingroup Networking*/
 4944void commandToServer(string func, ...);
 4945/*!
 4946@brief Send a command from the server to the client
 4947
 4948@param client The numeric ID of a client GameConnection
 4949@param func Name of the client function being called
 4950@param ... Various parameters being passed to client command
 4951
 4952@tsexample
 4953// Set up the client command.  Needs to be executed on the client, such as
 4954// within scripts/client/client.cs
 4955// Update the Ammo Counter with current ammo, if not any then hide the counter.
 4956function clientCmdSetAmmoAmountHud(%amount)
 4957{
 4958   if (!%amount)
 4959     AmmoAmount.setVisible(false);
 4960   else
 4961   {
 4962     AmmoAmount.setVisible(true);
 4963     AmmoAmount.setText("Ammo: "@%amount);
 4964   }
 4965}
 4966
 4967// Call it from a server function.  Needs to be executed on the server, 
 4968//such as within scripts/server/game.cs
 4969function GameConnection::setAmmoAmountHud(%client, %amount)
 4970{
 4971   commandToClient(%client, 'SetAmmoAmountHud', %amount);
 4972}
 4973@endtsexample
 4974
 4975@ingroup Networking*/
 4976void commandToClient(NetConnection client, string func, ...);
 4977/*!
 4978@brief Remove a tagged string from the Net String Table
 4979
 4980@param tag The tag associated with the string
 4981
 4982@see \ref syntaxDataTypes under Tagged %Strings
 4983@see addTaggedString()
 4984@see getTaggedString()
 4985@ingroup Networking*/
 4986void removeTaggedString( int tag=-1 );
 4987/*!
 4988@brief Use the addTaggedString function to tag a new string and add it to the NetStringTable
 4989
 4990@param str The string to be tagged and placed in the NetStringTable. Tagging ignores case, so tagging the same string (excluding case differences) will be ignored as a duplicated tag.
 4991
 4992@return Returns a string( containing a numeric value) equivalent to the string ID for the newly tagged string@see \ref syntaxDataTypes under Tagged %Strings
 4993@see removeTaggedString()
 4994@see getTaggedString()
 4995@ingroup Networking*/
 4996string addTaggedString( string str="" );
 4997/*!
 4998@brief Use the getTaggedString function to convert a tag to a string.
 4999
 5000This is not the same as detag() which can only be used within the context of a function that receives a tag. This function can be used any time and anywhere to convert a tag to a string.
 5001
 5002@param tag A numeric tag ID.
 5003@returns The string as found in the Net String table.
 5004@see \ref syntaxDataTypes under Tagged %Strings
 5005@see addTaggedString()
 5006@see removeTaggedString()
 5007@ingroup Networking*/
 5008string getTaggedString( string tag="" );
 5009/*!
 5010@brief Build a string using the specified tagged string format.
 5011
 5012This function takes an already tagged string (passed in as a tagged string ID) and one or more additional strings.  If the tagged string contains argument tags that range from %%1 through %%9, then each additional string will be substituted into the tagged string.  The final (non-tagged) combined string will be returned.  The maximum length of the tagged string plus any inserted additional strings is 511 characters.
 5013
 5014@param format A tagged string ID that contains zero or more argument tags, in the form of %%1 through %%9.
 5015@param ... A variable number of arguments that are insterted into the tagged string based on the argument tags within the format string.
 5016@returns An ordinary string that is a combination of the original tagged string with any additional strings passed in inserted in place of each argument tag.
 5017@tsexample
 5018// Create a tagged string with argument tags
 5019%taggedStringID = addTaggedString("Welcome %1 to the game!");
 5020
 5021// Some point later, combine the tagged string with some other string
 5022%string = buildTaggedString(%taggedStringID, %playerName);
 5023echo(%string);
 5024@endtsexample
 5025
 5026@see \ref syntaxDataTypes under Tagged %Strings
 5027@see addTaggedString()
 5028@see getTaggedString()
 5029@ingroup Networking*/
 5030string buildTaggedString(string format, ...);
 5031/*!
 5032@brief queryAllServers(...);
 5033
 5034
 5035@ingroup UNDOCUMENTED
 5036*/
 5037void queryAllServers( uint lanPort, uint flags, string gameType, string missionType, uint minPlayers, uint maxPlayers, uint maxBots, uint regionMask, uint maxPing, uint minCPU, uint filterFlags );
 5038/*!
 5039@brief queryLanServers(...);
 5040
 5041
 5042@ingroup UNDOCUMENTED
 5043*/
 5044void queryLanServers( uint lanPort, uint flags, string gameType, string missionType, uint minPlayers, uint maxPlayers, uint maxBots, uint regionMask, uint maxPing, uint minCPU, uint filterFlags );
 5045/*!
 5046@brief queryMasterServer(...);
 5047
 5048
 5049@ingroup UNDOCUMENTED
 5050*/
 5051void queryMasterServer( uint flags, string gameType, string missionType, uint minPlayers, uint maxPlayers, uint maxBots, uint regionMask, uint maxPing, uint minCPU, uint filterFlags );
 5052/*!
 5053@brief querySingleServer(address, flags);
 5054
 5055
 5056@ingroup UNDOCUMENTED
 5057*/
 5058void querySingleServer( string addrText, U8 flags=0 );
 5059/*!
 5060@brief cancelServerQuery();
 5061
 5062
 5063@ingroup UNDOCUMENTED
 5064*/
 5065void cancelServerQuery();
 5066/*!
 5067@brief stopServerQuery();
 5068
 5069
 5070@ingroup UNDOCUMENTED
 5071*/
 5072void stopServerQuery();
 5073/*!
 5074@brief startHeartbeat();
 5075
 5076
 5077@ingroup UNDOCUMENTED
 5078*/
 5079void startHeartbeat();
 5080/*!
 5081@brief stopHeartbeat();
 5082
 5083
 5084@ingroup UNDOCUMENTED
 5085*/
 5086void stopHeartbeat();
 5087/*!
 5088@brief getServerCount();
 5089
 5090
 5091@ingroup UNDOCUMENTED
 5092*/
 5093int getServerCount();
 5094/*!
 5095@brief setServerInfo(index);
 5096
 5097
 5098@ingroup UNDOCUMENTED
 5099*/
 5100bool setServerInfo( uint index );
 5101/*!
 5102@brief Get the version of the engine build, as a string.
 5103
 5104
 5105@ingroup Debugging*/
 5106int getVersionNumber();
 5107/*!
 5108@brief Get the version of the application build, as a string.
 5109
 5110
 5111@ingroup Debugging*/
 5112int getAppVersionNumber();
 5113/*!
 5114@brief Get the version of the engine build, as a human readable string.
 5115
 5116
 5117@ingroup Debugging*/
 5118string getVersionString();
 5119/*!
 5120@brief Get the version of the aplication build, as a human readable string.
 5121
 5122
 5123@ingroup Debugging*/
 5124string getAppVersionString();
 5125/*!
 5126@brief Get the name of the engine product that this is running from, as a string.
 5127
 5128
 5129@ingroup Debugging*/
 5130string getEngineName();
 5131/*!
 5132@brief Get the time of compilation.
 5133
 5134
 5135@ingroup Debugging*/
 5136string getCompileTimeString();
 5137/*!
 5138@brief Get the type of build, "Debug" or "Release".
 5139
 5140
 5141@ingroup Debugging*/
 5142string getBuildString();
 5143/*!
 5144@brief Return a newline-separated list of all active states.
 5145
 5146@return A list of the form
 5147@verbatim
 5148stateName1 NL stateName2 NL stateName3 ...
 5149@endverbatim
 5150where each element is the name of an active state object.
 5151
 5152@tsexample
 5153// Disable all active states.
 5154foreach$( %state in sfxGetActiveStates() )
 5155   %state.disable();
 5156@endtsexample
 5157
 5158@ingroup SFX*/
 5159string sfxGetActiveStates();
 5160/*!
 5161@brief Get a list of all available sound devices.
 5162
 5163The return value will be a newline-separated list of entries where each line describes one available sound device.  Each such line will have the following format:@verbatim
 5164provider TAB device TAB hasHardware TAB numMaxBuffers
 5165@endverbatim
 5166- provider: The name of the device provider (e.g. "FMOD").
 5167- device: The name of the device as returned by the device layer.
 5168- hasHardware: Whether the device supports hardware mixing or not.
 5169- numMaxBuffers: The maximum number of concurrent voices supported by the device's mixer.  If this limit limit is exceeded, i.e. if there are more active sounds playing at any one time, then voice virtualization will start culling voices and put them into virtualized playback mode.  Voice virtualization may or may not be provided by the device itself; if not provided by the device, it will be provided by Torque's sound system.
 5170
 5171@return A newline-separated list of information about all available sound devices.
 5172@see sfxCreateDevice
 5173@see sfxGetDeviceInfo
 5174
 5175@see $SFX::DEVICE_INFO_PROVIDER
 5176
 5177@see $SFX::DEVICE_INFO_NAME
 5178
 5179@see $SFX::DEVICE_INFO_USEHARDWARE
 5180
 5181@see $SFX::DEVICE_INFO_MAXBUFFERS
 5182
 5183@ref SFX_devices
 5184@ingroup SFX*/
 5185string sfxGetAvailableDevices();
 5186/*!
 5187@brief Try to create a new sound device using the given properties.
 5188
 5189If a sound device is currently initialized, it will be uninitialized first.  However, be aware that in this case, if this function fails, it will not restore the previously active device but rather leave the sound system in an uninitialized state.
 5190
 5191Sounds that are already playing while the new device is created will be temporarily transitioned to virtualized playback and then resume normal playback once the device has been created.
 5192
 5193In the core scripts, sound is automatically set up during startup in the sfxStartup() function.
 5194
 5195@param provider The name of the device provider as returned by sfxGetAvailableDevices().
 5196@param device The name of the device as returned by sfxGetAvailableDevices().
 5197@param useHardware Whether to enabled hardware mixing on the device or not.  Only relevant if supported by the given device.
 5198@param maxBuffers The maximum number of concurrent voices for this device to use or -1 for the device to pick its own reasonable default.@return True if the initialization was successful, false if not.
 5199@note This function must be called before any of the sound playback functions can be used.
 5200@see sfxGetAvailableDevices
 5201@see sfxGetDeviceInfo
 5202@see sfxDeleteDevice
 5203
 5204@ref SFX_devices
 5205@ingroup SFX*/
 5206bool sfxCreateDevice( string provider, string device, bool useHardware, int maxBuffers );
 5207/*!
 5208@brief Delete the currently active sound device and release all its resources.
 5209
 5210SFXSources that are still playing will be transitioned to virtualized playback mode. When creating a new device, they will automatically transition back to normal playback.
 5211
 5212In the core scripts, this is done automatically for you during shutdown in the sfxShutdown() function.
 5213
 5214@see sfxCreateDevice
 5215
 5216@ref SFX_devices
 5217@ingroup SFX*/
 5218void sfxDeleteDevice();
 5219/*!
 5220@brief Return information about the currently active sound device.
 5221
 5222The return value is a tab-delimited string of the following format:
 5223@verbatim
 5224provider TAB device TAB hasHardware TAB numMaxBuffers TAB caps
 5225@endverbatim
 5226- provider: The name of the device provider (e.g. "FMOD").
 5227- device: The name of the device as returned by the device layer.
 5228- hasHardware: Whether the device supports hardware mixing or not.
 5229- numMaxBuffers: The maximum number of concurrent voices supported by the device's mixer.  If this limit limit is exceeded, i.e. if there are more active sounds playing at any one time, then voice virtualization will start culling voices and put them into virtualized playback mode.  Voice virtualization may or may not be provided by the device itself; if not provided by the device, it will be provided by Torque's sound system.
 5230- caps: A bitfield of capability flags.
 5231
 5232@return A tab-separated list of properties of the currently active sound device or the empty string if no sound device has been initialized.
 5233@see sfxCreateDevice
 5234@see sfxGetAvailableDevices
 5235
 5236@see $SFX::DEVICE_INFO_PROVIDER
 5237
 5238@see $SFX::DEVICE_INFO_NAME
 5239
 5240@see $SFX::DEVICE_INFO_USEHARDWARE
 5241
 5242@see $SFX::DEVICE_INFO_MAXBUFFERS
 5243
 5244@see $SFX::DEVICE_INFO_CAPS
 5245
 5246@see $SFX::DEVICE_CAPS_REVERB
 5247
 5248@see $SFX::DEVICE_CAPS_VOICEMANAGEMENT
 5249
 5250@see $SFX::DEVICE_CAPS_OCCLUSION
 5251
 5252@see $SFX::DEVICE_CAPS_DSPEFFECTS
 5253
 5254@see $SFX::DEVICE_CAPS_MULTILISTENER
 5255
 5256@see $SFX::DEVICE_CAPS_FMODDESIGNER
 5257
 5258@ref SFX_devices
 5259@ingroup SFX*/
 5260string sfxGetDeviceInfo();
 5261/*!
 5262@brief Stop playback of the given @a source.
 5263
 5264This is equivalent to calling SFXSource::stop().
 5265
 5266@param source The source to put into stopped state.
 5267
 5268@ingroup SFX*/
 5269void sfxStop( SFXSource source );
 5270/*!
 5271@brief Stop playback of the given @a source (if it is not already stopped) and delete the @a source.
 5272
 5273
 5274The advantage of this function over directly calling delete() is that it will correctly handle volume fades that may be configured on the source.  Whereas calling delete() would immediately stop playback and delete the source, this functionality will wait for the fade-out to play and only then stop the source and delete it.
 5275
 5276@param source A sound source.
 5277
 5278@ref SFXSource_fades
 5279
 5280@ingroup SFX*/
 5281void sfxStopAndDelete( SFXSource source );
 5282/*!
 5283@brief Mark the given @a source for deletion as soon as it moves into stopped state.
 5284
 5285
 5286This function will retroactively turn the given @a source into a play-once source (see @ref SFXSource_playonce).
 5287
 5288@param source A sound source.
 5289
 5290@ingroup SFX*/
 5291void sfxDeleteWhenStopped( SFXSource source );
 5292/*!
 5293@brief Get the falloff curve type currently being applied to 3D sounds.
 5294
 5295
 5296@return The current distance model type.
 5297
 5298@ref SFXSource_volume
 5299
 5300@ref SFX_3d
 5301
 5302@ingroup SFX*/
 5303SFXDistanceModel sfxGetDistanceModel();
 5304/*!
 5305@brief Set the falloff curve type to use for distance-based volume attenuation of 3D sounds.
 5306
 5307
 5308@param model The distance model to use for 3D sound.
 5309
 5310@note This setting takes effect globally and is applied to all 3D sounds.
 5311
 5312@ingroup SFX*/
 5313void sfxSetDistanceModel( SFXDistanceModel model );
 5314/*!
 5315@brief Get the current global doppler effect setting.
 5316
 5317
 5318@return The current global doppler effect scale factor (>=0).
 5319
 5320@see sfxSetDopplerFactor
 5321
 5322@ref SFXSource_doppler
 5323
 5324@ingroup SFX*/
 5325float sfxGetDopplerFactor();
 5326/*!
 5327@brief Set the global doppler effect scale factor.
 5328
 5329@param value The new doppler shift scale factor.
 5330@pre @a value must be >= 0.
 5331@see sfxGetDopplerFactor
 5332
 5333@ref SFXSource_doppler
 5334
 5335@ingroup SFX*/
 5336void sfxSetDopplerFactor( float value );
 5337/*!
 5338@brief Get the current global scale factor applied to volume attenuation of 3D sounds in the logarithmic model.
 5339
 5340@return The current scale factor for logarithmic 3D sound falloff curves.
 5341
 5342@see sfxGetDistanceModel
 5343@see SFXDistanceModel
 5344
 5345@ref SFXSource_volume
 5346@ref SFX_3d
 5347@ingroup SFX*/
 5348float sfxGetRolloffFactor();
 5349/*!
 5350@brief Set the global scale factor to apply to volume attenuation of 3D sounds in the logarithmic model.
 5351
 5352@param value The new scale factor for logarithmic 3D sound falloff curves.
 5353
 5354@pre @a value must be > 0.
 5355@note This function has no effect if the currently distance model is set to SFXDistanceModel::Linear.
 5356
 5357@see sfxGetDistanceModel
 5358@see SFXDistanceModel
 5359
 5360@ref SFXSource_volume
 5361@ref SFX_3d
 5362@ingroup SFX*/
 5363void sfxSetRolloffFactor( float value );
 5364/*!
 5365@brief Dump information about all current SFXSource instances to the console.
 5366
 5367The dump includes information about the playback status for each source, volume levels, virtualization, etc.
 5368@param includeGroups If true, direct instances of SFXSources (which represent logical sound groups) will be included. Otherwise only instances of subclasses of SFXSources are included in the dump.
 5369@see SFXSource
 5370@see sfxDumpSourcesToString
 5371@ingroup SFX*/
 5372void sfxDumpSources( bool includeGroups=false );
 5373/*!
 5374@brief Dump information about all current SFXSource instances to a string.
 5375
 5376The dump includes information about the playback status for each source, volume levels, virtualization, etc.
 5377@param includeGroups If true, direct instances of SFXSources (which represent logical sound groups) will be included. Otherwise only instances of subclasses of SFXSources are included in the dump.
 5378@return A string containing a dump of information about all currently instantiated SFXSources.
 5379@see SFXSource
 5380@see sfxDumpSources
 5381@ingroup SFX*/
 5382string sfxDumpSourcesToString( bool includeGroups=false );
 5383/*!
 5384@brief Clears the console output.
 5385
 5386@ingroup Console*/
 5387void cls();
 5388/*!
 5389@brief Logs a message to the console.
 5390
 5391@param message The message text.
 5392@note By default, messages will appear white in the console.
 5393@ingroup Logging*/
 5394void log( string message );
 5395/*!
 5396@brief Logs an error message to the console.
 5397
 5398@param message The message text.
 5399@note By default, errors will appear red in the console.
 5400@ingroup Logging*/
 5401void logError( string message );
 5402/*!
 5403@brief Logs a warning message to the console.
 5404
 5405@param message The message text.
 5406
 5407@note By default, warnings will appear turquoise in the console.
 5408@ingroup Logging*/
 5409void logWarning( string message );
 5410/*!
 5411@brief Dumps all declared console classes to the console.
 5412
 5413@param dumpScript Optional parameter specifying whether or not classes defined in script should be dumped.
 5414@param dumpEngine Optional parameter specifying whether or not classes defined in the engine should be dumped.
 5415@ingroup Logging*/
 5416void dumpConsoleClasses( bool dumpScript=true, bool dumpEngine=true );
 5417/*!
 5418@brief Dumps all declared console functions to the console.
 5419@param dumpScript Optional parameter specifying whether or not functions defined in script should be dumped.
 5420@param dumpEngine Optional parameter specitying whether or not functions defined in the engine should be dumped.
 5421@ingroup Logging*/
 5422void dumpConsoleFunctions( bool dumpScript=true, bool dumpEngine=true );
 5423/*!
 5424@brief Return the integer character code value corresponding to the first character in the given string.
 5425
 5426@param chr a (one-character) string.
 5427@return the UTF32 code value for the first character in the given string.
 5428@ingroup Strings*/
 5429int strasc( string chr );
 5430/*!
 5431@brief Format the given value as a string using printf-style formatting.
 5432
 5433@param format A printf-style format string.
 5434@param value The value argument matching the given format string.
 5435
 5436@tsexample
 5437// Convert the given integer value to a string in a hex notation.
 5438%hex = strformat( "%x", %value );
 5439@endtsexample
 5440@ingroup Strings
 5441@see http://en.wikipedia.org/wiki/Printf*/
 5442string strformat( string format, string value );
 5443/*!
 5444@brief Compares two strings using case-<b>sensitive</b> comparison.
 5445
 5446@param str1 The first string.
 5447@param str2 The second string.
 5448@return 0 if both strings are equal, a value <0 if the first character different in str1 has a smaller character code value than the character at the same position in str2, and a value >1 otherwise.
 5449
 5450@tsexample
 5451if( strcmp( %var, "foobar" ) == 0 )
 5452   echo( "%var is equal to 'foobar'" );
 5453@endtsexample
 5454@see stricmp
 5455@see strnatcmp
 5456@ingroup Strings*/
 5457int strcmp( string str1, string str2 );
 5458/*!
 5459@brief Compares two strings using case-<b>insensitive</b> comparison.
 5460
 5461@param str1 The first string.
 5462@param str2 The second string.
 5463@return 0 if both strings are equal, a value <0 if the first character different in str1 has a smaller character code value than the character at the same position in str2, and a value >0 otherwise.
 5464
 5465@tsexample
 5466if( stricmp( "FOObar", "foobar" ) == 0 )
 5467   echo( "this is always true" );
 5468@endtsexample
 5469@see strcmp
 5470@see strinatcmp
 5471@ingroup Strings*/
 5472int stricmp( string str1, string str2 );
 5473/*!
 5474@brief Compares two strings using "natural order" case-<b>sensitive</b> comparison.
 5475
 5476Natural order means that rather than solely comparing single character code values, strings are ordered in a natural way.  For example, the string "hello10" is considered greater than the string "hello2" even though the first numeric character in "hello10" actually has a smaller character value than the corresponding character in "hello2".  However, since 10 is greater than 2, strnatcmp will put "hello10" after "hello2".
 5477@param str1 The first string.
 5478@param str2 The second string.
 5479
 5480@return 0 if the strings are equal, a value >0 if @a str1 comes after @a str2 in a natural order, and a value <0 if @a str1 comes before @a str2 in a natural order.
 5481
 5482@tsexample
 5483// Bubble sort 10 elements of %array using natural order
 5484do
 5485{
 5486   %swapped = false;
 5487   for( %i = 0; %i < 10 - 1; %i ++ )
 5488      if( strnatcmp( %array[ %i ], %array[ %i + 1 ] ) > 0 )
 5489      {
 5490         %temp = %array[ %i ];
 5491         %array[ %i ] = %array[ %i + 1 ];
 5492         %array[ %i + 1 ] = %temp;
 5493         %swapped = true;
 5494      }
 5495}
 5496while( %swapped );
 5497@endtsexample
 5498@see strcmp
 5499@see strinatcmp
 5500@ingroup Strings*/
 5501int strnatcmp( string str1, string str2 );
 5502/*!
 5503@brief Compares two strings using "natural order" case-<b>insensitive</b> comparison.
 5504
 5505Natural order means that rather than solely comparing single character code values, strings are ordered in a natural way.  For example, the string "hello10" is considered greater than the string "hello2" even though the first numeric character in "hello10" actually has a smaller character value than the corresponding character in "hello2".  However, since 10 is greater than 2, strnatcmp will put "hello10" after "hello2".
 5506@param str1 The first string.
 5507@param str2 The second string.
 5508@return 0 if the strings are equal, a value >0 if @a str1 comes after @a str2 in a natural order, and a value <0 if @a str1 comes before @a str2 in a natural order.
 5509
 5510@tsexample
 5511
 5512// Bubble sort 10 elements of %array using natural order
 5513do
 5514{
 5515   %swapped = false;
 5516   for( %i = 0; %i < 10 - 1; %i ++ )
 5517      if( strnatcmp( %array[ %i ], %array[ %i + 1 ] ) > 0 )
 5518      {
 5519         %temp = %array[ %i ];
 5520         %array[ %i ] = %array[ %i + 1 ];
 5521         %array[ %i + 1 ] = %temp;
 5522         %swapped = true;
 5523      }
 5524}
 5525while( %swapped );
 5526@endtsexample
 5527@see stricmp
 5528@see strnatcmp
 5529@ingroup Strings*/
 5530int strinatcmp( string str1, string str2 );
 5531/*!
 5532@brief Get the length of the given string in bytes.
 5533
 5534@note This does <b>not</b> return a true character count for strings with multi-byte characters!
 5535@param str A string.
 5536@return The length of the given string in bytes.
 5537@ingroup Strings*/
 5538int strlen( string str );
 5539/*!
 5540@brief Calculate the length of a string in characters, skipping everything between and including first and last.
 5541
 5542@param str A string.
 5543@param first First character to look for to skip block of text.
 5544@param last Second character to look for to skip block of text.
 5545@return The length of the given string skipping blocks of text between characters.
 5546@ingroup Strings*/
 5547int strlenskip( string str, string first, string last );
 5548/*!
 5549@brief Find the start of @a substring in the given @a string searching from left to right.
 5550
 5551@param string The string to search.
 5552@param substring The string to search for.
 5553@return The index into @a string at which the first occurrence of @a substring was found or -1 if @a substring could not be found.
 5554
 5555@tsexample
 5556strstr( "abcd", "c" ) // Returns 2.
 5557@endtsexample
 5558@ingroup Strings*/
 5559int strstr( string string, string substring );
 5560/*!
 5561@brief Find the start of @a needle in @a haystack searching from left to right beginning at the given offset.
 5562
 5563@param haystack The string to search.
 5564@param needle The string to search for.
 5565@return The index at which the first occurrence of @a needle was found in @a haystack or -1 if no match was found.
 5566
 5567@tsexample
 5568strpos( "b ab", "b", 1 ) // Returns 3.
 5569@endtsexample
 5570@ingroup Strings*/
 5571int strpos( string haystack, string needle, int offset=0 );
 5572/*!
 5573@brief Find the start of @a needle in @a haystack searching from right to left beginning at the given offset.
 5574
 5575@param haystack The string to search.
 5576@param needle The string to search for.
 5577@return The index at which the first occurrence of @a needle was found in @a heystack or -1 if no match was found.
 5578
 5579@tsexample
 5580strposr( "b ab", "b", 1 ) // Returns 2.
 5581@endtsexample
 5582@ingroup Strings*/
 5583int strposr( string haystack, string needle, int offset=0 );
 5584/*!
 5585@brief Remove leading whitespace from the string.
 5586
 5587@param str A string.
 5588@return A string that is the same as @a str but with any leading (i.e. leftmost) whitespace removed.
 5589
 5590@tsexample
 5591ltrim( "   string  " ); // Returns "string  ".
 5592@endtsexample
 5593@see rtrim
 5594@see trim
 5595@ingroup Strings*/
 5596string ltrim( string str );
 5597/*!
 5598@brief Remove trailing whitespace from the string.
 5599
 5600@param str A string.
 5601@return A string that is the same as @a str but with any trailing (i.e. rightmost) whitespace removed.
 5602
 5603@tsexample
 5604rtrim( "   string  " ); // Returns "   string".
 5605@endtsexample
 5606@see ltrim
 5607@see trim
 5608@ingroup Strings*/
 5609string rtrim( string str );
 5610/*!
 5611@brief Remove leading and trailing whitespace from the string.
 5612
 5613@param str A string.
 5614@return A string that is the same as @a str but with any leading (i.e. leftmost) and trailing (i.e. rightmost) whitespace removed.
 5615
 5616@tsexample
 5617trim( "   string  " ); // Returns "string".
 5618@endtsexample
 5619@ingroup Strings*/
 5620string trim( string str );
 5621/*!
 5622@brief Remove all occurrences of characters contained in @a chars from @a str.
 5623
 5624@param str The string to filter characters out from.
 5625@param chars A string of characters to filter out from @a str.
 5626@return A version of @a str with all occurrences of characters contained in @a chars filtered out.
 5627
 5628@tsexample
 5629stripChars( "teststring", "se" ); // Returns "tttring".@endtsexample
 5630@ingroup Strings*/
 5631string stripChars( string str, string chars );
 5632/*!
 5633@brief Return an all lower-case version of the given string.
 5634
 5635@param str A string.
 5636@return A version of @a str with all characters converted to lower-case.
 5637
 5638@tsexample
 5639strlwr( "TesT1" ) // Returns "test1"
 5640@endtsexample
 5641@see strupr
 5642@ingroup Strings*/
 5643string strlwr( string str );
 5644/*!
 5645@brief Return an all upper-case version of the given string.
 5646
 5647@param str A string.
 5648@return A version of @a str with all characters converted to upper-case.
 5649
 5650@tsexample
 5651strupr( "TesT1" ) // Returns "TEST1"
 5652@endtsexample
 5653@see strlwr
 5654@ingroup Strings*/
 5655string strupr( string str );
 5656/*!
 5657@brief Find the first occurrence of the given character in @a str.
 5658
 5659@param str The string to search.
 5660@param chr The character to search for.  Only the first character from the string is taken.
 5661@return The remainder of the input string starting with the given character or the empty string if the character could not be found.
 5662
 5663@see strrchr
 5664@ingroup Strings*/
 5665string strchr( string str, string chr );
 5666/*!
 5667@brief Find the last occurrence of the given character in @a str.@param str The string to search.
 5668
 5669@param chr The character to search for.  Only the first character from the string is taken.
 5670@return The remainder of the input string starting with the given character or the empty string if the character could not be found.
 5671
 5672@see strchr
 5673@ingroup Strings*/
 5674string strrchr( string str, string chr );
 5675/*!
 5676@brief Replace all occurrences of @a from in @a source with @a to.
 5677
 5678@param source The string in which to replace the occurrences of @a from.
 5679@param from The string to replace in @a source.
 5680@param to The string with which to replace occurrences of @from.
 5681@return A string with all occurrences of @a from in @a source replaced by @a to.
 5682
 5683@tsexample
 5684strreplace( "aabbccbb", "bb", "ee" ) // Returns "aaeeccee".
 5685@endtsexample
 5686@ingroup Strings*/
 5687string strreplace( string source, string from, string to );
 5688/*!
 5689@brief Return a string that repeats @a str @a numTimes number of times delimiting each occurrence with @a delimiter.
 5690
 5691@param str The string to repeat multiple times.
 5692@param numTimes The number of times to repeat @a str in the result string.
 5693@param delimiter The string to put between each repetition of @a str.
 5694@return A string containing @a str repeated @a numTimes times.
 5695
 5696@tsexample
 5697strrepeat( "a", 5, "b" ) // Returns "ababababa".
 5698@endtsexample
 5699@ingroup Strings*/
 5700string strrepeat( string str, int numTimes, string delimiter="" );
 5701/*!
 5702@brief Return a substring of @a str starting at @a start and continuing either through to the end of @a str (if @a numChars is -1) or for @a numChars characters (except if this would exceed the actual source string length).
 5703@param str The string from which to extract a substring.
 5704@param start The offset at which to start copying out characters.
 5705@param numChars Optional argument to specify the number of characters to copy.  If this is -1, all characters up the end of the input string are copied.
 5706@return A string that contains the given portion of the input string.
 5707
 5708@tsexample
 5709getSubStr( "foobar", 1, 2 ) // Returns "oo".
 5710@endtsexample
 5711
 5712@ingroup Strings*/
 5713string getSubStr( string str, int start, int numChars=-1 );
 5714/*!
 5715@brief Match a pattern against a string.
 5716
 5717@param pattern The wildcard pattern to match against.  The pattern can include characters, '*' to match any number of characters and '?' to match a single character.
 5718@param str The string which should be matched against @a pattern.
 5719@param caseSensitive If true, characters in the pattern are matched in case-sensitive fashion against this string.  If false, differences in casing are ignored.
 5720@return True if @a str matches the given @a pattern.
 5721
 5722@tsexample
 5723strIsMatchExpr( "f?o*R", "foobar" ) // Returns true.
 5724@endtsexample
 5725@see strIsMatchMultipleExpr
 5726@ingroup Strings*/
 5727bool strIsMatchExpr( string pattern, string str, bool caseSensitive=false );
 5728/*!
 5729@brief Match a multiple patterns against a single string.
 5730
 5731@param patterns A tab-separated list of patterns.  Each pattern can include charaters, '*' to match any number of characters and '?' to match a single character.  Each of the patterns is tried in turn.
 5732@param str The string which should be matched against @a patterns.
 5733@param caseSensitive If true, characters in the pattern are matched in case-sensitive fashion against this string.  If false, differences in casing are ignored.
 5734@return True if @a str matches any of the given @a patterns.
 5735
 5736@tsexample
 5737strIsMatchMultipleExpr( "*.cs *.gui *.mis", "mymission.mis" ) // Returns true.
 5738@endtsexample
 5739@see strIsMatchExpr
 5740@ingroup Strings*/
 5741bool strIsMatchMultipleExpr( string patterns, string str, bool caseSensitive=false );
 5742/*!
 5743@brief Get the numeric suffix of the given input string.
 5744
 5745@param str The string from which to read out the numeric suffix.
 5746@return The numeric value of the number suffix of @a str or -1 if @a str has no such suffix.
 5747
 5748@tsexample
 5749getTrailingNumber( "test123" ) // Returns '123'.
 5750@endtsexample
 5751
 5752@see stripTrailingNumber
 5753@ingroup Strings*/
 5754int getTrailingNumber( string str );
 5755/*!
 5756@brief Strip a numeric suffix from the given string.
 5757
 5758@param str The string from which to strip its numeric suffix.
 5759@return The string @a str without its number suffix or the original string @a str if it has no such suffix.
 5760
 5761@tsexample
 5762stripTrailingNumber( "test123" ) // Returns "test".
 5763@endtsexample
 5764
 5765@see getTrailingNumber
 5766@ingroup Strings*/
 5767String stripTrailingNumber( string str );
 5768/*!
 5769@brief Get the first occuring number from @a str.
 5770
 5771@param str The string from which to read out the first number.
 5772@return String representation of the number or  if no number.
 5773
 5774
 5775@ingroup UNDOCUMENTED
 5776*/
 5777String getFirstNumber( string str );
 5778/*!
 5779@brief Test whether the character at the given position is a whitespace character.
 5780
 5781Characters such as tab, space, or newline are considered whitespace.
 5782@param str The string to test.
 5783@param index The index of a character in @a str.
 5784@return True if the character at the given index in @a str is a whitespace character; false otherwise.
 5785
 5786@see isalnum
 5787@ingroup Strings*/
 5788bool isspace( string str, int index );
 5789/*!
 5790@brief Test whether the character at the given position is an alpha-numeric character.
 5791
 5792Alpha-numeric characters are characters that are either alphabetic (a-z, A-Z) or numbers (0-9).
 5793@param str The string to test.
 5794@param index The index of a character in @a str.
 5795@return True if the character at the given index in @a str is an alpha-numeric character; false otherwise.
 5796
 5797@see isspace
 5798@ingroup Strings*/
 5799bool isalnum( string str, int index );
 5800/*!
 5801@brief Test whether the given string begins with the given prefix.
 5802
 5803@param str The string to test.
 5804@param prefix The potential prefix of @a str.
 5805@param caseSensitive If true, the comparison will be case-sensitive; if false, differences in casing will not be taken into account.
 5806@return True if the first characters in @a str match the complete contents of @a prefix; false otherwise.
 5807
 5808@tsexample
 5809startsWith( "TEST123", "test" ) // Returns true.
 5810@endtsexample
 5811@see endsWith
 5812@ingroup Strings*/
 5813bool startsWith( string str, string prefix, bool caseSensitive=false );
 5814/*!
 5815@brief Test whether the given string ends with the given suffix.
 5816
 5817@param str The string to test.
 5818@param suffix The potential suffix of @a str.
 5819@param caseSensitive If true, the comparison will be case-sensitive; if false, differences in casing will not be taken into account.
 5820@return True if the last characters in @a str match the complete contents of @a suffix; false otherwise.
 5821
 5822@tsexample
 5823startsWith( "TEST123", "123" ) // Returns true.
 5824@endtsexample
 5825
 5826@see startsWith
 5827@ingroup Strings*/
 5828bool endsWith( string str, string suffix, bool caseSensitive=false );
 5829/*!
 5830@brief Find the first occurrence of the given character in the given string.
 5831
 5832@param str The string to search.
 5833@param chr The character to look for.  Only the first character of this string will be searched for.
 5834@param start The index into @a str at which to start searching for the given character.
 5835@return The index of the first occurrence of @a chr in @a str or -1 if @a str does not contain the given character.
 5836
 5837@tsexample
 5838strchrpos( "test", "s" ) // Returns 2.
 5839@endtsexample
 5840@ingroup Strings*/
 5841int strchrpos( string str, string chr, int start=0 );
 5842/*!
 5843@brief Find the last occurrence of the given character in the given string.
 5844
 5845@param str The string to search.
 5846@param chr The character to look for.  Only the first character of this string will be searched for.
 5847@param start The index into @a str at which to start searching for the given character.
 5848@return The index of the last occurrence of @a chr in @a str or -1 if @a str does not contain the given character.
 5849
 5850@tsexample
 5851strrchrpos( "test", "t" ) // Returns 3.
 5852@endtsexample
 5853@ingroup Strings*/
 5854int strrchrpos( string str, string chr, int start=0 );
 5855/*!
 5856@brief Convert from a float color to an integer color (0.0 - 1.0 to 0 to 255).
 5857
 5858@param color Float color value to be converted in the form "R G B A", where R is red, G is green, B is blue, and A is alpha.
 5859@return Converted color value (0 - 255)
 5860
 5861@tsexample
 5862ColorFloatToInt( "0 0 1 0.5" ) // Returns "0 0 255 128".
 5863@endtsexample
 5864@ingroup Strings*/
 5865ColorI ColorFloatToInt( LinearColorF color );
 5866/*!
 5867@brief Convert from a integer color to an float color (0 to 255 to 0.0 - 1.0).
 5868
 5869@param color Integer color value to be converted in the form "R G B A", where R is red, G is green, B is blue, and A is alpha.
 5870@return Converted color value (0.0 - 1.0)
 5871
 5872@tsexample
 5873ColorIntToFloat( "0 0 255 128" ) // Returns "0 0 1 0.5".
 5874@endtsexample
 5875@ingroup Strings*/
 5876LinearColorF ColorIntToFloat( ColorI color );
 5877/*!
 5878@brief Convert from a integer RGB (red, green, blue) color to hex color value (0 to 255 to 00 - FF).
 5879
 5880@param color Integer color value to be converted in the form "R G B A", where R is red, G is green, B is blue, and A is alpha. It excepts an alpha, but keep in mind this will not be converted.
 5881@return Hex color value (#000000 - #FFFFFF), alpha isn't handled/converted so it is only the RGB value
 5882
 5883@tsexample
 5884ColorRBGToHEX( "0 0 255 128" ) // Returns "#0000FF".
 5885@endtsexample
 5886@ingroup Strings*/
 5887string ColorRGBToHEX( ColorI color );
 5888/*!
 5889@brief Convert from a integer RGB (red, green, blue) color to HSB (hue, saturation, brightness). HSB is also know as HSL or HSV as well, with the last letter standing for lightness or value.
 5890
 5891@param color Integer color value to be converted in the form "R G B A", where R is red, G is green, B is blue, and A is alpha. It excepts an alpha, but keep in mind this will not be converted.
 5892@return HSB color value, alpha isn't handled/converted so it is only the RGB value
 5893
 5894@tsexample
 5895ColorRBGToHSB( "0 0 255 128" ) // Returns "240 100 100".
 5896@endtsexample
 5897@ingroup Strings*/
 5898string ColorRGBToHSB( ColorI color );
 5899/*!
 5900@brief Convert from a hex color value to an integer RGB (red, green, blue) color (00 - FF to 0 to 255).
 5901
 5902@param hex Hex color value (#000000 - #FFFFFF) to be converted to an RGB (red, green, blue) value.
 5903@return Integer color value to be converted in the form "R G B A", where R is red, G is green, B is blue, and A is alpha. Alpha isn't handled/converted so only pay attention to the RGB value
 5904
 5905@tsexample
 5906ColorHEXToRGB( "#0000FF" ) // Returns "0 0 255 0".
 5907@endtsexample
 5908@ingroup Strings*/
 5909ColorI ColorHEXToRGB( string hex );
 5910/*!
 5911@brief Convert from a HSB (hue, saturation, brightness) to an integer RGB (red, green, blue) color. HSB is also know as HSL or HSV as well, with the last letter standing for lightness or value.
 5912
 5913@param hsb HSB (hue, saturation, brightness) value to be converted.
 5914@return Integer color value to be converted in the form "R G B A", where R is red, G is green, B is blue, and A is alpha. Alpha isn't handled/converted so only pay attention to the RGB value
 5915
 5916@tsexample
 5917ColorHSBToRGB( "240 100 100" ) // Returns "0 0 255 0".
 5918@endtsexample
 5919@ingroup Strings*/
 5920ColorI ColorHSBToRGB( Point3I hsb );
 5921/*!
 5922@brief Parse a Toggle Case word into separate words.
 5923
 5924@param str The string to parse.
 5925@return new string space separated.
 5926
 5927@tsexample
 5928strToggleCaseToWords( "HelloWorld" ) // Returns "Hello World".
 5929@endtsexample
 5930@ingroup Strings*/
 5931string strToggleCaseToWords( string str );
 5932/*!
 5933@brief Returns true if the string is an integer.
 5934
 5935@param str The string to test.
 5936@return true if @a str is an integer and false if not
 5937
 5938@tsexample
 5939isInt( "13" ) // Returns true.
 5940@endtsexample
 5941@ingroup Strings*/
 5942bool isInt( string str );
 5943/*!
 5944@brief Returns true if the string is a float.
 5945
 5946@param str The string to test.
 5947@param sciOk Test for correct scientific notation and accept it (ex. 1.2e+14)@return true if @a str is a float and false if not
 5948
 5949@tsexample
 5950isFloat( "13.5" ) // Returns true.
 5951@endtsexample
 5952@ingroup Strings*/
 5953bool isFloat( string str, bool sciOk=false );
 5954/*!
 5955@brief Returns true if the string is a valid port number.
 5956
 5957@param str The string to test.
 5958@return true if @a str is a port and false if not
 5959
 5960@tsexample
 5961isValidPort( "8080" ) // Returns true.
 5962@endtsexample
 5963@ingroup Strings*/
 5964bool isValidPort( string str );
 5965/*!
 5966@brief Returns true if the string is a valid ip address, excepts localhost.
 5967
 5968@param str The string to test.
 5969@return true if @a str is a valid ip address and false if not
 5970
 5971@tsexample
 5972isValidIP( "localhost" ) // Returns true.
 5973@endtsexample
 5974@ingroup Strings*/
 5975bool isValidIP( string str );
 5976/*!
 5977@brief [string1, string2, ...]Adds case sensitive strings to the StringTable.
 5978
 5979
 5980@ingroup UNDOCUMENTED
 5981*/
 5982void addCaseSensitiveStrings;
 5983/*!
 5984@brief Extract the word at the given @a index in the whitespace-separated list in @a text.
 5985
 5986Words in @a text must be separated by newlines, spaces, and/or tabs.
 5987@param text A whitespace-separated list of words.
 5988@param index The zero-based index of the word to extract.
 5989@return The word at the given index or "" if the index is out of range.
 5990
 5991@tsexample
 5992getWord( "a b c", 1 ) // Returns "b"
 5993@endtsexample
 5994
 5995@see getWords
 5996@see getWordCount
 5997@see getToken
 5998@see getField
 5999@see getRecord
 6000@ingroup FieldManip*/
 6001string getWord( string text, int index );
 6002/*!
 6003@brief Extract a range of words from the given @a startIndex onwards thru @a endIndex.
 6004
 6005Words in @a text must be separated by newlines, spaces, and/or tabs.
 6006@param text A whitespace-separated list of words.
 6007@param startIndex The zero-based index of the first word to extract from @a text.
 6008@param endIndex The zero-based index of the last word to extract from @a text.  If this is -1, all words beginning with @a startIndex are extracted from @a text.
 6009@return A string containing the specified range of words from @a text or "" if @a startIndex is out of range or greater than @a endIndex.
 6010
 6011@tsexample
 6012getWords( "a b c d", 1, 2, ) // Returns "b c"
 6013@endtsexample
 6014
 6015@see getWord
 6016@see getWordCount
 6017@see getTokens
 6018@see getFields
 6019@see getRecords
 6020@ingroup FieldManip*/
 6021string getWords( string text, int startIndex, int endIndex=-1 );
 6022/*!
 6023@brief Replace the word in @a text at the given @a index with @a replacement.
 6024
 6025Words in @a text must be separated by newlines, spaces, and/or tabs.
 6026@param text A whitespace-separated list of words.
 6027@param index The zero-based index of the word to replace.
 6028@param replacement The string with which to replace the word.
 6029@return A new string with the word at the given @a index replaced by @a replacement or the original string if @a index is out of range.
 6030
 6031@tsexample
 6032setWord( "a b c d", 2, "f" ) // Returns "a b f d"
 6033@endtsexample
 6034
 6035@see getWord
 6036@see setToken
 6037@see setField
 6038@see setRecord
 6039@ingroup FieldManip*/
 6040string setWord( string text, int index, string replacement );
 6041/*!
 6042@brief Remove the word in @a text at the given @a index.
 6043
 6044Words in @a text must be separated by newlines, spaces, and/or tabs.
 6045@param text A whitespace-separated list of words.
 6046@param index The zero-based index of the word in @a text.
 6047@return A new string with the word at the given index removed or the original string if @a index is out of range.
 6048
 6049@tsexample
 6050removeWord( "a b c d", 2 ) // Returns "a b d"
 6051@endtsexample
 6052
 6053@see removeToken
 6054@see removeField
 6055@see removeRecord
 6056@ingroup FieldManip*/
 6057string removeWord( string text, int index );
 6058/*!
 6059@brief Return the number of whitespace-separated words in @a text.
 6060
 6061Words in @a text must be separated by newlines, spaces, and/or tabs.
 6062@param text A whitespace-separated list of words.
 6063@return The number of whitespace-separated words in @a text.
 6064
 6065@tsexample
 6066getWordCount( "a b c d e" ) // Returns 5
 6067@endtsexample
 6068
 6069@see getTokenCount
 6070@see getFieldCount
 6071@see getRecordCount
 6072@ingroup FieldManip*/
 6073int getWordCount( string text );
 6074/*!
 6075@brief returns month as a word given a number or "" if number is bad@return month as a word given a number or "" if number is bad@ingroup FileSystem*/
 6076String monthNumToStr( int num, bool abbreviate=false );
 6077/*!
 6078@brief returns weekday as a word given a number or "" if number is bad@return weekday as a word given a number or "" if number is bad@ingroup FileSystem*/
 6079String weekdayNumToStr( int num, bool abbreviate=false );
 6080/*!
 6081@brief Extract the field at the given @a index in the newline and/or tab separated list in @a text.
 6082
 6083Fields in @a text must be separated by newlines and/or tabs.
 6084@param text A list of fields separated by newlines and/or tabs.
 6085@param index The zero-based index of the field to extract.
 6086@return The field at the given index or "" if the index is out of range.
 6087
 6088@tsexample
 6089getField( "a b" TAB "c d" TAB "e f", 1 ) // Returns "c d"
 6090@endtsexample
 6091
 6092@see getFields
 6093@see getFieldCount
 6094@see getWord
 6095@see getRecord
 6096@ingroup FieldManip*/
 6097string getField( string text, int index );
 6098/*!
 6099@brief Extract a range of fields from the given @a startIndex onwards thru @a endIndex.
 6100
 6101Fields in @a text must be separated by newlines and/or tabs.
 6102@param text A list of fields separated by newlines and/or tabs.
 6103@param startIndex The zero-based index of the first field to extract from @a text.
 6104@param endIndex The zero-based index of the last field to extract from @a text.  If this is -1, all fields beginning with @a startIndex are extracted from @a text.
 6105@return A string containing the specified range of fields from @a text or "" if @a startIndex is out of range or greater than @a endIndex.
 6106
 6107@tsexample
 6108getFields( "a b" TAB "c d" TAB "e f", 1 ) // Returns "c d" TAB "e f"
 6109@endtsexample
 6110
 6111@see getField
 6112@see getFieldCount
 6113@see getWords
 6114@see getRecords
 6115@ingroup FieldManip*/
 6116string getFields( string text, int startIndex, int endIndex=-1 );
 6117/*!
 6118@brief Replace the field in @a text at the given @a index with @a replacement.
 6119
 6120Fields in @a text must be separated by newlines and/or tabs.
 6121@param text A list of fields separated by newlines and/or tabs.
 6122@param index The zero-based index of the field to replace.
 6123@param replacement The string with which to replace the field.
 6124@return A new string with the field at the given @a index replaced by @a replacement or the original string if @a index is out of range.
 6125
 6126@tsexample
 6127setField( "a b" TAB "c d" TAB "e f", 1, "g h" ) // Returns "a b" TAB "g h" TAB "e f"
 6128@endtsexample
 6129
 6130@see getField
 6131@see setWord
 6132@see setRecord
 6133@ingroup FieldManip*/
 6134string setField( string text, int index, string replacement );
 6135/*!
 6136@brief Remove the field in @a text at the given @a index.
 6137
 6138Fields in @a text must be separated by newlines and/or tabs.
 6139@param text A list of fields separated by newlines and/or tabs.
 6140@param index The zero-based index of the field in @a text.
 6141@return A new string with the field at the given index removed or the original string if @a index is out of range.
 6142
 6143@tsexample
 6144removeField( "a b" TAB "c d" TAB "e f", 1 ) // Returns "a b" TAB "e f"
 6145@endtsexample
 6146
 6147@see removeWord
 6148@see removeRecord
 6149@ingroup FieldManip*/
 6150string removeField( string text, int index );
 6151/*!
 6152@brief Return the number of newline and/or tab separated fields in @a text.
 6153
 6154@param text A list of fields separated by newlines and/or tabs.
 6155@return The number of newline and/or tab sepearated elements in @a text.
 6156
 6157@tsexample
 6158getFieldCount( "a b" TAB "c d" TAB "e f" ) // Returns 3
 6159@endtsexample
 6160
 6161@see getWordCount
 6162@see getRecordCount
 6163@ingroup FieldManip*/
 6164int getFieldCount( string text );
 6165/*!
 6166@brief Extract the record at the given @a index in the newline-separated list in @a text.
 6167
 6168Records in @a text must be separated by newlines.
 6169@param text A list of records separated by newlines.
 6170@param index The zero-based index of the record to extract.
 6171@return The record at the given index or "" if @a index is out of range.
 6172
 6173@tsexample
 6174getRecord( "a b" NL "c d" NL "e f", 1 ) // Returns "c d"
 6175@endtsexample
 6176
 6177@see getRecords
 6178@see getRecordCount
 6179@see getWord
 6180@see getField
 6181@ingroup FieldManip*/
 6182string getRecord( string text, int index );
 6183/*!
 6184@brief Extract a range of records from the given @a startIndex onwards thru @a endIndex.
 6185
 6186Records in @a text must be separated by newlines.
 6187@param text A list of records separated by newlines.
 6188@param startIndex The zero-based index of the first record to extract from @a text.
 6189@param endIndex The zero-based index of the last record to extract from @a text.  If this is -1, all records beginning with @a startIndex are extracted from @a text.
 6190@return A string containing the specified range of records from @a text or "" if @a startIndex is out of range or greater than @a endIndex.
 6191
 6192@tsexample
 6193getRecords( "a b" NL "c d" NL "e f", 1 ) // Returns "c d" NL "e f"
 6194@endtsexample
 6195
 6196@see getRecord
 6197@see getRecordCount
 6198@see getWords
 6199@see getFields
 6200@ingroup FieldManip*/
 6201string getRecords( string text, int startIndex, int endIndex=-1 );
 6202/*!
 6203@brief Replace the record in @a text at the given @a index with @a replacement.
 6204
 6205Records in @a text must be separated by newlines.
 6206@param text A list of records separated by newlines.
 6207@param index The zero-based index of the record to replace.
 6208@param replacement The string with which to replace the record.
 6209@return A new string with the record at the given @a index replaced by @a replacement or the original string if @a index is out of range.
 6210
 6211@tsexample
 6212setRecord( "a b" NL "c d" NL "e f", 1, "g h" ) // Returns "a b" NL "g h" NL "e f"
 6213@endtsexample
 6214
 6215@see getRecord
 6216@see setWord
 6217@see setField
 6218@ingroup FieldManip*/
 6219string setRecord( string text, int index, string replacement );
 6220/*!
 6221@brief Remove the record in @a text at the given @a index.
 6222
 6223Records in @a text must be separated by newlines.
 6224@param text A list of records separated by newlines.
 6225@param index The zero-based index of the record in @a text.
 6226@return A new string with the record at the given @a index removed or the original string if @a index is out of range.
 6227
 6228@tsexample
 6229removeRecord( "a b" NL "c d" NL "e f", 1 ) // Returns "a b" NL "e f"
 6230@endtsexample
 6231
 6232@see removeWord
 6233@see removeField
 6234@ingroup FieldManip*/
 6235string removeRecord( string text, int index );
 6236/*!
 6237@brief Return the number of newline-separated records in @a text.
 6238
 6239@param text A list of records separated by newlines.
 6240@return The number of newline-sepearated elements in @a text.
 6241
 6242@tsexample
 6243getRecordCount( "a b" NL "c d" NL "e f" ) // Returns 3
 6244@endtsexample
 6245
 6246@see getWordCount
 6247@see getFieldCount
 6248@ingroup FieldManip*/
 6249int getRecordCount( string text );
 6250/*!
 6251@brief Return the first word in @a text.
 6252
 6253@param text A list of words separated by newlines, spaces, and/or tabs.
 6254@return The word at index 0 in @a text or "" if @a text is empty.
 6255
 6256@note This is equal to 
 6257@tsexample_nopar
 6258getWord( text, 0 )
 6259@endtsexample
 6260
 6261@see getWord
 6262@ingroup FieldManip*/
 6263string firstWord( string text );
 6264/*!
 6265@brief Return all but the first word in @a text.
 6266
 6267@param text A list of words separated by newlines, spaces, and/or tabs.
 6268@return @a text with the first word removed.
 6269
 6270@note This is equal to 
 6271@tsexample_nopar
 6272getWords( text, 1 )
 6273@endtsexample
 6274
 6275@see getWords
 6276@ingroup FieldManip*/
 6277string restWords( string text );
 6278/*!
 6279@brief Tokenize a string using a set of delimiting characters.
 6280
 6281This function first skips all leading charaters in @a str that are contained in @a delimiters. From that position, it then scans for the next character in @a str that is contained in @a delimiters and stores all characters from the starting position up to the first delimiter in a variable in the current scope called @a token.  Finally, it skips all characters in @a delimiters after the token and then returns the remaining string contents in @a str.
 6282
 6283To scan out all tokens in a string, call this function repeatedly by passing the result it returns each time as the new @a str until the function returns "".
 6284
 6285@param str A string.
 6286@param token The name of the variable in which to store the current token.  This variable is set in the scope in which nextToken is called.
 6287@param delimiters A string of characters.  Each character is considered a delimiter.
 6288@return The remainder of @a str after the token has been parsed out or "" if no more tokens were found in @a str.
 6289
 6290@tsexample
 6291// Prints:
 6292// a
 6293// b
 6294// c
 6295%str = "a   b c";
 6296while ( %str !$= "" )
 6297{
 6298   // First time, stores "a" in the variable %token and sets %str to "b c".
 6299   %str = nextToken( %str, "token", " " );
 6300   echo( %token );
 6301}
 6302@endtsexample
 6303
 6304@ingroup Strings*/
 6305string nextToken( string str1, string token, string delim );
 6306/*!
 6307@brief Extract the substring at the given @a index in the @a delimiters separated list in @a text.
 6308
 6309@param text A @a delimiters list of substrings.
 6310@param delimiters Character or characters that separate the list of substrings in @a text.
 6311@param index The zero-based index of the substring to extract.
 6312@return The substring at the given index or "" if the index is out of range.
 6313
 6314@tsexample
 6315getToken( "a b c d", " ", 2 ) // Returns "c"
 6316@endtsexample
 6317
 6318@see getTokens
 6319@see getTokenCount
 6320@see getWord
 6321@see getField
 6322@see getRecord
 6323@ingroup FieldManip*/
 6324string getToken( string text, string delimiters, int index );
 6325/*!
 6326@brief Extract a range of substrings separated by @a delimiters at the given @a startIndex onwards thru @a endIndex.
 6327
 6328@param text A @a delimiters list of substrings.
 6329@param delimiters Character or characters that separate the list of substrings in @a text.
 6330@param startIndex The zero-based index of the first substring to extract from @a text.
 6331@param endIndex The zero-based index of the last substring to extract from @a text.  If this is -1, all words beginning with @a startIndex are extracted from @a text.
 6332@return A string containing the specified range of substrings from @a text or "" if @a startIndex is out of range or greater than @a endIndex.
 6333
 6334@tsexample
 6335getTokens( "a b c d", " ", 1, 2, ) // Returns "b c"
 6336@endtsexample
 6337
 6338@see getToken
 6339@see getTokenCount
 6340@see getWords
 6341@see getFields
 6342@see getRecords
 6343@ingroup FieldManip*/
 6344string getTokens( string text, string delimiters, int startIndex, int endIndex=-1 );
 6345/*!
 6346@brief Replace the substring in @a text separated by @a delimiters at the given @a index with @a replacement.
 6347
 6348@param text A @a delimiters list of substrings.
 6349@param delimiters Character or characters that separate the list of substrings in @a text.
 6350@param index The zero-based index of the substring to replace.
 6351@param replacement The string with which to replace the substring.
 6352@return A new string with the substring at the given @a index replaced by @a replacement or the original string if @a index is out of range.
 6353
 6354@tsexample
 6355setToken( "a b c d", " ", 2, "f" ) // Returns "a b f d"
 6356@endtsexample
 6357
 6358@see getToken
 6359@see setWord
 6360@see setField
 6361@see setRecord
 6362@ingroup FieldManip*/
 6363string setToken( string text, string delimiters, int index, string replacement );
 6364/*!
 6365@brief Remove the substring in @a text separated by @a delimiters at the given @a index.
 6366
 6367@param text A @a delimiters list of substrings.
 6368@param delimiters Character or characters that separate the list of substrings in @a text.
 6369@param index The zero-based index of the word in @a text.
 6370@return A new string with the substring at the given index removed or the original string if @a index is out of range.
 6371
 6372@tsexample
 6373removeToken( "a b c d", " ", 2 ) // Returns "a b d"
 6374@endtsexample
 6375
 6376@see removeWord
 6377@see removeField
 6378@see removeRecord
 6379@ingroup FieldManip*/
 6380string removeToken( string text, string delimiters, int index );
 6381/*!
 6382@brief Return the number of @a delimiters substrings in @a text.
 6383
 6384@param text A @a delimiters list of substrings.
 6385@param delimiters Character or characters that separate the list of substrings in @a text.
 6386@return The number of @a delimiters substrings in @a text.
 6387
 6388@tsexample
 6389getTokenCount( "a b c d e", " " ) // Returns 5
 6390@endtsexample
 6391
 6392@see getWordCount
 6393@see getFieldCount
 6394@see getRecordCount
 6395@ingroup FieldManip*/
 6396int getTokenCount( string text, string delimiters );
 6397/*!
 6398@brief Returns the string from a tag string.
 6399
 6400Should only be used within the context of a function that receives a tagged string, and is not meant to be used outside of this context.  Use getTaggedString() to convert a tagged string ID back into a regular string at any time.
 6401
 6402@tsexample
 6403// From scripts/client/message. cs
 6404function clientCmdChatMessage(%sender, %voice, %pitch, %msgString, %a1, %a2, %a3, %a4, %a5, %a6, %a7, %a8, %a9, %a10)
 6405{
 6406   onChatMessage(detag(%msgString), %voice, %pitch);
 6407}
 6408@endtsexample
 6409
 6410@see \ref syntaxDataTypes under Tagged %Strings
 6411@see getTag()
 6412@see getTaggedString()
 6413@ingroup Networking*/
 6414string detag( string str );
 6415/*!
 6416@brief Extracts the tag from a tagged string
 6417
 6418Should only be used within the context of a function that receives a tagged string, and is not meant to be used outside of this context.
 6419
 6420@param textTagString The tagged string to extract.
 6421@returns The tag ID of the string.
 6422@see \ref syntaxDataTypes under Tagged %Strings
 6423@see detag()
 6424@ingroup Networking*/
 6425string getTag( string textTagString );
 6426/*!
 6427@brief Logs a message to the console.
 6428
 6429Concatenates all given arguments to a single string and prints the string to the console. A newline is added automatically after the text.
 6430
 6431@param message Any number of string arguments.
 6432
 6433@ingroup Logging*/
 6434void echo( string message... );
 6435/*!
 6436@brief Logs a warning message to the console.
 6437
 6438Concatenates all given arguments to a single string and prints the string to the console as a warning message (in the in-game console, these will show up using a turquoise font by default). A newline is added automatically after the text.
 6439
 6440@param message Any number of string arguments.
 6441
 6442@ingroup Logging*/
 6443void warn( string message... );
 6444/*!
 6445@brief Logs an error message to the console.
 6446
 6447Concatenates all given arguments to a single string and prints the string to the console as an error message (in the in-game console, these will show up using a red font by default). A newline is added automatically after the text.
 6448
 6449@param message Any number of string arguments.
 6450
 6451@ingroup Logging*/
 6452void error( string message... );
 6453/*!
 6454@brief Logs the value of the given variable to the console.
 6455
 6456Prints a string of the form "<variableName> = <variable value>" to the console.
 6457
 6458@param variableName Name of the local or global variable to print.
 6459
 6460@tsexample
 6461%var = 1;
 6462debugv( "%var" ); // Prints "%var = 1"
 6463@endtsexample
 6464
 6465@ingroup Debugging*/
 6466void debugv( string variableName );
 6467/*!
 6468@brief Replace all characters in @a text that need to be escaped for the string to be a valid string literal with their respective escape sequences.
 6469
 6470All characters in @a text that cannot appear in a string literal will be replaced by an escape sequence (\\n, \\t, etc).
 6471
 6472The primary use of this function is for converting strings suitable for being passed as string literals to the TorqueScript compiler.
 6473
 6474@param text A string
 6475@return A duplicate of the text parameter with all unescaped characters that cannot appear in string literals replaced by their respective escape sequences.
 6476
 6477@tsxample
 6478expandEscape( "str" NL "ing" ) // Returns "str\ning".
 6479@endtsxample
 6480
 6481@see collapseEscape
 6482@ingroup Strings*/
 6483string expandEscape( string text );
 6484/*!
 6485@brief Replace all escape sequences in @a text with their respective character codes.
 6486
 6487
 6488This function replaces all escape sequences (\\n, \\t, etc) in the given string with the respective characters they represent.
 6489
 6490The primary use of this function is for converting strings from their literal form into their compiled/translated form, as is normally done by the TorqueScript compiler.
 6491
 6492@param text A string.
 6493@return A duplicate of @a text with all escape sequences replaced by their respective character codes.
 6494
 6495@tsexample
 6496// Print:
 6497//
 6498//    str
 6499//    ing
 6500//
 6501// to the console.  Note how the backslash in the string must be escaped here
 6502// in order to prevent the TorqueScript compiler from collapsing the escape
 6503// sequence in the resulting string.
 6504echo( collapseEscape( "str\ning" ) );
 6505@endtsexample
 6506
 6507@see expandEscape
 6508
 6509@ingroup Strings*/
 6510string collapseEscape( string text );
 6511/*!
 6512@brief Determines how log files are written.
 6513
 6514Sets the operational mode of the console logging system.
 6515
 6516@param mode Parameter specifying the logging mode.  This can be:
 6517- 1: Open and close the console log file for each seperate string of output.  This will ensure that all parts get written out to disk and that no parts remain in intermediate buffers even if the process crashes.
 6518- 2: Keep the log file open and write to it continuously.  This will make the system operate faster but if the process crashes, parts of the output may not have been written to disk yet and will be missing from the log.
 6519
 6520Additionally, when changing the log mode and thus opening a new log file, either of the two mode values may be combined by binary OR with 0x4 to cause the logging system to flush all console log messages that had already been issued to the console system into the newly created log file.
 6521
 6522@note Xbox 360 does not support logging to a file. Use Platform::OutputDebugStr in C++ instead.@ingroup Logging*/
 6523void setLogMode( int mode );
 6524/*!
 6525@brief Shut down the engine and exit its process.
 6526
 6527This function cleanly uninitializes the engine and then exits back to the system with a process exit status indicating a clean exit.
 6528
 6529@see quitWithErrorMessage
 6530
 6531@ingroup Platform*/
 6532void quit();
 6533/*! UNDOCUMENTED!
 6534@ingroup UNDOCUMENTED
 6535 */
 6536void realQuit();
 6537/*!
 6538@brief Display an error message box showing the given @a message and then shut down the engine and exit its process.
 6539
 6540This function cleanly uninitialized the engine and then exits back to the system with a process exit status indicating an error.
 6541
 6542@param message The message to log to the console and show in an error message box.
 6543@param status  The status code to return to the OS.
 6544
 6545@see quit
 6546
 6547@ingroup Platform*/
 6548void quitWithErrorMessage( string message, int status=0 );
 6549/*!
 6550@brief Shut down the engine and exit its process.
 6551
 6552This function cleanly uninitializes the engine and then exits back to the system with a given return status code.
 6553
 6554@param status The status code to return to the OS.
 6555
 6556@see quitWithErrorMessage
 6557
 6558@ingroup Platform*/
 6559void quitWithStatus( int status=0 );
 6560/*!
 6561@brief Open the given URL or file in the user's web browser.
 6562
 6563
 6564@param address The address to open.  If this is not prefixed by a protocol specifier ("...://"), then the function checks whether the address refers to a file or directory and if so, prepends "file://" to @a adress; if the file check fails, "http://" is prepended to @a address.
 6565
 6566@tsexample
 6567gotoWebPage( "http://www.garagegames.com" );
 6568@endtsexample
 6569
 6570@ingroup Platform*/
 6571void gotoWebPage( string address );
 6572/*!
 6573@brief Display a startup splash window suitable for showing while the engine still starts up.
 6574
 6575
 6576@note This is currently only implemented on Windows.
 6577
 6578@param path   relative path to splash screen image to display.
 6579@return True if the splash window could be successfully initialized.
 6580
 6581@ingroup Platform*/
 6582bool displaySplashWindow( string path="" );
 6583/*!
 6584@brief Close our startup splash window.
 6585
 6586
 6587@note This is currently only implemented on Windows.
 6588
 6589@ingroup Platform*/
 6590void closeSplashWindow();
 6591/*!
 6592@brief Test whether Torque is running in web-deployment mode.
 6593
 6594In this mode, Torque will usually run within a browser and certain restrictions apply (e.g. Torque will not be able to enter fullscreen exclusive mode).
 6595@return True if Torque is running in web-deployment mode.
 6596@ingroup Platform*/
 6597bool getWebDeployment();
 6598/*!
 6599@brief Count the number of bits that are set in the given 32 bit integer.
 6600
 6601@param v An integer value.
 6602
 6603@return The number of bits that are set in @a v.
 6604
 6605@ingroup Utilities*/
 6606int countBits( int v );
 6607/*!
 6608@brief Generate a new universally unique identifier (UUID).
 6609
 6610
 6611@return A newly generated UUID.
 6612
 6613@ingroup Utilities*/
 6614Torque::UUID generateUUID();
 6615/*!
 6616@brief Apply the given arguments to the specified global function and return the result of the call.
 6617
 6618
 6619@param functionName The name of the function to call.  This function must be in the global namespace, i.e. you cannot call a function in a namespace through #call.  Use eval() for that.
 6620@return The result of the function call.
 6621
 6622@tsexample
 6623function myFunction( %arg )
 6624{
 6625  return ( %arg SPC "World!" );
 6626}
 6627
 6628echo( call( "myFunction", "Hello" ) ); // Prints "Hello World!" to the console.
 6629@endtsexample
 6630
 6631@ingroup Scripting*/
 6632string call( string functionName, string args... );
 6633/*!
 6634@brief Get the absolute path to the file in which the compiled code for the given script file will be stored.
 6635
 6636@param scriptFileName %Path to the .cs script file.
 6637@return The absolute path to the .dso file for the given script file.
 6638
 6639@note The compiler will store newly compiled DSOs in the prefs path but pre-existing DSOs will be loaded from the current paths.
 6640
 6641@see compile
 6642@see getPrefsPath
 6643@ingroup Scripting*/
 6644string getDSOPath( string scriptFileName );
 6645/*!
 6646@brief Compile a file to bytecode.
 6647
 6648
 6649This function will read the TorqueScript code in the specified file, compile it to internal bytecode, and, if DSO generation is enabled or @a overrideNoDDSO is true, will store the compiled code in a .dso file in the current DSO path mirrorring the path of @a fileName.
 6650
 6651@param fileName Path to the file to compile to bytecode.
 6652@param overrideNoDSO If true, force generation of DSOs even if the engine is compiled to not generate write compiled code to DSO files.
 6653
 6654@return True if the file was successfully compiled, false if not.
 6655
 6656@note The definitions contained in the given file will not be made available and no code will actually be executed.  Use exec() for that.
 6657
 6658@see getDSOPath
 6659@see exec
 6660@ingroup Scripting*/
 6661bool compile( string fileName, bool overrideNoDSO=false );
 6662/*!
 6663@brief Execute the given script file.
 6664
 6665@param fileName Path to the file to execute
 6666@param noCalls Deprecated
 6667@param journalScript Deprecated
 6668@return True if the script was successfully executed, false if not.
 6669
 6670@tsexample
 6671// Execute the init.cs script file found in the same directory as the current script file.
 6672exec( "./init.cs" );
 6673@endtsexample
 6674
 6675@see compile
 6676@see eval
 6677@ingroup Scripting*/
 6678bool exec( string fileName, bool noCalls=false, bool journalScript=false );
 6679/*!
 6680@brief eval(consoleString)
 6681
 6682
 6683@ingroup UNDOCUMENTED
 6684*/
 6685string eval( string consoleString );
 6686/*!
 6687@brief Returns the value of the named variable or an empty string if not found.
 6688
 6689@varName Name of the variable to search for
 6690@return Value contained by varName, "" if the variable does not exist
 6691@ingroup Scripting*/
 6692string getVariable( string varName );
 6693/*!
 6694@brief Sets the value of the named variable.
 6695
 6696@param varName Name of the variable to locate
 6697@param value New value of the variable
 6698@return True if variable was successfully found and set
 6699@ingroup Scripting*/
 6700void setVariable( string varName, string value );
 6701/*!
 6702@brief Determines if a function exists or not
 6703
 6704@param funcName String containing name of the function
 6705@return True if the function exists, false if not
 6706@ingroup Scripting*/
 6707bool isFunction( string funcName );
 6708/*!
 6709@brief Provides the name of the package the function belongs to
 6710
 6711@param funcName String containing name of the function
 6712@return The name of the function's package
 6713@ingroup Packages*/
 6714string getFunctionPackage( string funcName );
 6715/*!
 6716@brief Determines if a class/namespace method exists
 6717
 6718@param namespace Class or namespace, such as Player
 6719@param method Name of the function to search for
 6720@return True if the method exists, false if not
 6721@ingroup Scripting*/
 6722bool isMethod( string nameSpace, string method );
 6723/*!
 6724@brief Provides the name of the package the method belongs to
 6725
 6726@param namespace Class or namespace, such as Player
 6727@param method Name of the funciton to search for
 6728@return The name of the method's package
 6729@ingroup Packages*/
 6730string getMethodPackage( string nameSpace, string method );
 6731/*!
 6732@brief Determines if a variable exists and contains a value
 6733@param varName Name of the variable to search for
 6734@return True if the variable was defined in script, false if not
 6735@tsexample
 6736isDefined( "$myVar" );
 6737@endtsexample
 6738
 6739@ingroup Scripting*/
 6740bool isDefined( string varName, string varValue="" );
 6741/*!
 6742@brief Manually execute a special script file that contains game or editor preferences
 6743
 6744@param relativeFileName Name and path to file from project folder
 6745@param noCalls Deprecated
 6746@param journalScript Deprecated
 6747@return True if script was successfully executed
 6748@note Appears to be useless in Torque 3D, should be deprecated
 6749@ingroup Scripting*/
 6750bool execPrefs( string relativeFileName, bool noCalls=false, bool journalScript=false );
 6751/*!
 6752@brief Write out the definitions of all global variables matching the given name @a pattern.
 6753
 6754If @a fileName is not "", the variable definitions are written to the specified file.  Otherwise the definitions will be printed to the console.
 6755
 6756The output are valid TorqueScript statements that can be executed to restore the global variable values.
 6757
 6758@param pattern A global variable name pattern.  Must begin with '$'.
 6759@param filename %Path of the file to which to write the definitions or "" to write the definitions to the console.
 6760@param append If true and @a fileName is not "", then the definitions are appended to the specified file. Otherwise existing contents of the file (if any) will be overwritten.
 6761
 6762@tsexample
 6763// Write out all preference variables to a prefs.cs file.
 6764export( "$prefs::*", "prefs.cs" );
 6765@endtsexample
 6766
 6767@ingroup Scripting*/
 6768void export( string pattern, string filename="", bool append=false );
 6769/*!
 6770@brief Undefine all global variables matching the given name @a pattern.
 6771
 6772@param pattern A global variable name pattern.  Must begin with '$'.
 6773@tsexample
 6774// Define a global variable in the "My" namespace.
 6775$My::Variable = "value";
 6776
 6777// Undefine all variable in the "My" namespace.
 6778deleteVariables( "$My::*" );
 6779@endtsexample
 6780
 6781@see strIsMatchExpr
 6782@ingroup Scripting*/
 6783void deleteVariables( string pattern );
 6784/*!
 6785@brief Enable or disable tracing in the script code VM.
 6786
 6787
 6788When enabled, the script code runtime will trace the invocation and returns from all functions that are called and log them to the console. This is helpful in observing the flow of the script program.
 6789
 6790@param enable New setting for script trace execution, on by default.
 6791@ingroup Debugging*/
 6792void trace( bool enable=true );
 6793/*!
 6794@brief Drops the engine into the native C++ debugger.
 6795
 6796
 6797This function triggers a debug break and drops the process into the IDE's debugger.  If the process is not running with a debugger attached it will generate a runtime error on most platforms.
 6798
 6799@note This function is not available in shipping builds.@ingroup Debugging*/
 6800void debug();
 6801/*!
 6802@brief Test whether the engine has been compiled with TORQUE_SHIPPING, i.e. in a form meant for final release.
 6803
 6804
 6805@return True if this is a shipping build; false otherwise.
 6806
 6807@ingroup Platform*/
 6808bool isShippingBuild();
 6809/*!
 6810@brief Test whether the engine has been compiled with TORQUE_DEBUG, i.e. if it includes debugging functionality.
 6811
 6812
 6813@return True if this is a debug build; false otherwise.
 6814
 6815@ingroup Platform*/
 6816bool isDebugBuild();
 6817/*!
 6818@brief Test whether the engine has been compiled with TORQUE_TOOLS, i.e. if it includes tool-related functionality.
 6819
 6820
 6821@return True if this is a tool build; false otherwise.
 6822
 6823@ingroup Platform*/
 6824bool isToolBuild();
 6825/*!
 6826@brief Get max number of allowable dynamic vertices in a single vertex buffer.
 6827
 6828
 6829@return the max number of allowable dynamic vertices in a single vertex buffer
 6830@ingroup UNDOCUMENTED
 6831*/
 6832int getMaxDynamicVerts();
 6833/*!
 6834@brief Prints the scripting call stack to the console log.
 6835
 6836Used to trace functions called from within functions. Can help discover what functions were called (and not yet exited) before the current point in scripts.
 6837
 6838@ingroup Debugging*/
 6839void backtrace();
 6840/*!
 6841@brief Returns true if the identifier is the name of a declared package.
 6842
 6843@ingroup Packages*/
 6844bool isPackage( String identifier );
 6845/*!
 6846@brief Activates an existing package.
 6847
 6848The activation occurs by updating the namespace linkage of existing functions and methods. If the package is already activated the function does nothing.
 6849@ingroup Packages*/
 6850void activatePackage( String packageName );
 6851/*!
 6852@brief Deactivates a previously activated package.
 6853
 6854The package is deactivated by removing its namespace linkages to any function or method. If there are any packages above this one in the stack they are deactivated as well. If the package is not on the stack this function does nothing.
 6855@ingroup Packages*/
 6856void deactivatePackage( String packageName );
 6857/*!
 6858@brief Returns a space delimited list of the active packages in stack order.
 6859
 6860@ingroup Packages*/
 6861string getPackageList();
 6862/*!
 6863@brief Returns true if the passed identifier is the name of a declared class.
 6864
 6865@ingroup Console*/
 6866bool isClass( string identifier );
 6867/*!
 6868@brief Returns true if the class is derived from the super class.
 6869
 6870If either class doesn't exist this returns false.
 6871@param className The class name.
 6872@param superClassName The super class to look for.
 6873@ingroup Console*/
 6874bool isMemberOfClass( string className, string superClassName );
 6875/*!
 6876@brief Returns the description string for the named class.
 6877
 6878@param className The name of the class.
 6879@return The class description in string format.
 6880@ingroup Console*/
 6881string getDescriptionOfClass( string className );
 6882/*!
 6883@brief Returns the category of the given class.
 6884
 6885@param className The name of the class.
 6886@ingroup Console*/
 6887string getCategoryOfClass( string className );
 6888/*!
 6889@brief Dumps network statistics for each class to the console.
 6890
 6891The returned <i>avg</i>, <i>min</i> and <i>max</i> values are in bits sent per update.  The <i>num</i> value is the total number of events collected.
 6892@note This method only works when TORQUE_NET_STATS is defined in torqueConfig.h.
 6893@ingroup Networking*/
 6894void dumpNetStats();
 6895/*!
 6896@brief Determines the memory consumption of a class or object.
 6897
 6898@param objectOrClass The object or class being measured.
 6899@return Returns the total size of an object in bytes.
 6900@ingroup Debugging*/
 6901int sizeof( string objectOrClass );
 6902/*!
 6903@brief Dumps the engine scripting documentation to the specified file overwriting any existing content.
 6904
 6905@param outputFile The relative or absolute output file path and name.
 6906@return Returns true if successful.
 6907@ingroup Console*/
 6908bool dumpEngineDocs( string outputFile );
 6909/*!
 6910@brief Dumps all current EngineObject instances to the console.
 6911
 6912@note This function is only available in debug builds.
 6913
 6914@ingroup Debugging*/
 6915void debugDumpAllObjects();
 6916/*!
 6917@brief Create a XML document containing a dump of the entire exported engine API.
 6918
 6919
 6920@return A SimXMLDocument containing a dump of the engine's export information or NULL if the operation failed.
 6921
 6922@ingroup Console*/
 6923SimXMLDocument exportEngineAPIToXML();
 6924/*!
 6925@brief Returns the first file in the directory system matching the given pattern.
 6926
 6927Use the corresponding findNextFile() to step through the results.  If you're only interested in the number of files returned by the pattern match, use getFileCount().
 6928
 6929This function differs from findFirstFileMultiExpr() in that it supports a single search pattern being passed in.
 6930
 6931@note You cannot run multiple simultaneous file system searches with these functions.  Each call to findFirstFile() and findFirstFileMultiExpr() initiates a new search and renders a previous search invalid.
 6932
 6933@param pattern The path and file name pattern to match against.
 6934@param recurse If true, the search will exhaustively recurse into subdirectories of the given path and match the given filename pattern.
 6935@return The path of the first file matched by the search or an empty string if no matching file could be found.
 6936
 6937@tsexample
 6938// Execute all .cs files in a subdirectory and its subdirectories.
 6939for( %file = findFirstFile( "subdirectory/*.cs" ); %file !$= ""; %file = findNextFile() )
 6940   exec( %file );
 6941@endtsexample
 6942
 6943@see findNextFile()@see getFileCount()@see findFirstFileMultiExpr()@ingroup FileSearches*/
 6944String findFirstFile( string pattern="", bool recurse=true );
 6945/*!
 6946@brief Returns the next file matching a search begun in findFirstFile().
 6947
 6948@param pattern The path and file name pattern to match against.  This is optional and may be left out as it is not used by the code.  It is here for legacy reasons.
 6949@return The path of the next filename matched by the search or an empty string if no more files match.
 6950
 6951@tsexample
 6952// Execute all .cs files in a subdirectory and its subdirectories.
 6953for( %file = findFirstFile( "subdirectory/*.cs" ); %file !$= ""; %file = findNextFile() )
 6954   exec( %file );
 6955@endtsexample
 6956
 6957@see findFirstFile()@ingroup FileSearches*/
 6958String findNextFile( string pattern="" );
 6959/*!
 6960@brief Returns the number of files in the directory tree that match the given patterns
 6961
 6962This function differs from getFileCountMultiExpr() in that it supports a single search pattern being passed in.
 6963
 6964If you're interested in a list of files that match the given pattern and not just the number of files, use findFirstFile() and findNextFile().
 6965
 6966@param pattern The path and file name pattern to match against.
 6967@param recurse If true, the search will exhaustively recurse into subdirectories of the given path and match the given filename pattern counting files in subdirectories.
 6968@return Number of files located using the pattern
 6969
 6970@tsexample
 6971// Count the number of .cs files in a subdirectory and its subdirectories.
 6972getFileCount( "subdirectory/*.cs" );
 6973@endtsexample
 6974
 6975@see findFirstFile()@see findNextFile()@see getFileCountMultiExpr()@ingroup FileSearches*/
 6976int getFileCount( string pattern="", bool recurse=true );
 6977/*!
 6978@brief Returns the first file in the directory system matching the given patterns.
 6979
 6980Use the corresponding findNextFileMultiExpr() to step through the results.  If you're only interested in the number of files returned by the pattern match, use getFileCountMultiExpr().
 6981
 6982This function differs from findFirstFile() in that it supports multiple search patterns to be passed in.
 6983
 6984@note You cannot run multiple simultaneous file system searches with these functions.  Each call to findFirstFile() and findFirstFileMultiExpr() initiates a new search and renders a previous search invalid.
 6985
 6986@param pattern The path and file name pattern to match against, such as *.cs.  Separate multiple patterns with TABs.  For example: "*.cs" TAB "*.dso"
 6987@param recurse If true, the search will exhaustively recurse into subdirectories of the given path and match the given filename patterns.
 6988@return String of the first matching file path, or an empty string if no matching files were found.
 6989
 6990@tsexample
 6991// Find all DTS or Collada models
 6992%filePatterns = "*.dts" TAB "*.dae";
 6993%fullPath = findFirstFileMultiExpr( %filePatterns );
 6994while ( %fullPath !$= "" )
 6995{
 6996   echo( %fullPath );
 6997   %fullPath = findNextFileMultiExpr( %filePatterns );
 6998}
 6999@endtsexample
 7000
 7001@see findNextFileMultiExpr()@see getFileCountMultiExpr()@see findFirstFile()@ingroup FileSearches*/
 7002String findFirstFileMultiExpr( string pattern="", bool recurse=true );
 7003/*!
 7004@brief Returns the next file matching a search begun in findFirstFileMultiExpr().
 7005
 7006@param pattern The path and file name pattern to match against.  This is optional and may be left out as it is not used by the code.  It is here for legacy reasons.
 7007@return String of the next matching file path, or an empty string if no matching files were found.
 7008
 7009@tsexample
 7010// Find all DTS or Collada models
 7011%filePatterns = "*.dts" TAB "*.dae";
 7012%fullPath = findFirstFileMultiExpr( %filePatterns );
 7013while ( %fullPath !$= "" )
 7014{
 7015   echo( %fullPath );
 7016   %fullPath = findNextFileMultiExpr( %filePatterns );
 7017}
 7018@endtsexample
 7019
 7020@see findFirstFileMultiExpr()@ingroup FileSearches*/
 7021String findNextFileMultiExpr( string pattern="" );
 7022/*!
 7023@brief Returns the number of files in the directory tree that match the given patterns
 7024
 7025If you're interested in a list of files that match the given patterns and not just the number of files, use findFirstFileMultiExpr() and findNextFileMultiExpr().
 7026
 7027@param pattern The path and file name pattern to match against, such as *.cs.  Separate multiple patterns with TABs.  For example: "*.cs" TAB "*.dso"
 7028@param recurse If true, the search will exhaustively recurse into subdirectories of the given path and match the given filename pattern.
 7029@return Number of files located using the patterns
 7030
 7031@tsexample
 7032// Count all DTS or Collada models
 7033%filePatterns = "*.dts" TAB "*.dae";
 7034echo( "Nunmer of shape files:" SPC getFileCountMultiExpr( %filePatterns ) );
 7035@endtsexample
 7036
 7037@see findFirstFileMultiExpr()@see findNextFileMultiExpr()@ingroup FileSearches*/
 7038int getFileCountMultiExpr( string pattern="", bool recurse=true );
 7039/*!
 7040@brief Provides the CRC checksum of the given file.
 7041
 7042@param fileName The path to the file.
 7043@return The calculated CRC checksum of the file, or -1 if the file could not be found.
 7044@ingroup FileSystem*/
 7045int getFileCRC( string fileName );
 7046/*!
 7047@brief Determines if the specified file exists or not
 7048
 7049@param fileName The path to the file.
 7050@return Returns true if the file was found.
 7051@ingroup FileSystem*/
 7052bool isFile( string fileName );
 7053/*!
 7054@brief Determines if a specified directory exists or not
 7055
 7056@param directory String containing path in the form of "foo/bar"
 7057@return Returns true if the directory was found.
 7058@note Do not include a trailing slash '/'.
 7059@ingroup FileSystem*/
 7060bool IsDirectory( string directory );
 7061/*!
 7062@brief Determines if a file name can be written to using File I/O
 7063
 7064@param fileName Name and path of file to check
 7065@return Returns true if the file can be written to.
 7066@ingroup FileSystem*/
 7067bool isWriteableFileName( string fileName );
 7068/*!
 7069@brief Start watching resources for file changes
 7070
 7071Typically this is called during initializeCore().
 7072
 7073@see stopFileChangeNotifications()
 7074@ingroup FileSystem*/
 7075void startFileChangeNotifications();
 7076/*!
 7077@brief Stop watching resources for file changes
 7078
 7079Typically this is called during shutdownCore().
 7080
 7081@see startFileChangeNotifications()
 7082@ingroup FileSystem*/
 7083void stopFileChangeNotifications();
 7084/*!
 7085@brief Gathers a list of directories starting at the given path.
 7086
 7087@param path String containing the path of the directory
 7088@param depth Depth of search, as in how many subdirectories to parse through
 7089@return Tab delimited string containing list of directories found during search, "" if no files were found
 7090@ingroup FileSystem*/
 7091String getDirectoryList( string path="", int depth=0 );
 7092/*!
 7093@brief Determines the size of a file on disk
 7094
 7095@param fileName Name and path of the file to check
 7096@return Returns filesize in bytes, or -1 if no file
 7097@ingroup FileSystem*/
 7098int fileSize( string fileName );
 7099/*!
 7100@brief Returns a platform specific formatted string with the last modified time for the file.
 7101
 7102@param fileName Name and path of file to check
 7103@return Formatted string (OS specific) containing modified time, "9/3/2010 12:33:47 PM" for example
 7104@ingroup FileSystem*/
 7105String fileModifiedTime( string fileName );
 7106/*!
 7107@brief Returns a platform specific formatted string with the creation time for the file.@param fileName Name and path of file to check
 7108@return Formatted string (OS specific) containing created time, "9/3/2010 12:33:47 PM" for example
 7109@ingroup FileSystem*/
 7110String fileCreatedTime( string fileName );
 7111/*!
 7112@brief Delete a file from the hard drive
 7113
 7114@param path Name and path of the file to delete
 7115@note THERE IS NO RECOVERY FROM THIS. Deleted file is gone for good.
 7116@return True if file was successfully deleted
 7117@ingroup FileSystem*/
 7118bool fileDelete( string path );
 7119/*!
 7120@brief Get the extension of a file
 7121
 7122@param fileName Name and path of file
 7123@return String containing the extension, such as ".exe" or ".cs"
 7124@ingroup FileSystem*/
 7125String fileExt( string fileName );
 7126/*!
 7127@brief Get the base of a file name (removes extension and path)
 7128
 7129@param fileName Name and path of file to check
 7130@return String containing the file name, minus extension and path
 7131@ingroup FileSystem*/
 7132String fileBase( string fileName );
 7133/*!
 7134@brief Get only the file name of a path and file name string (removes path)
 7135
 7136@param fileName Name and path of file to check
 7137@return String containing the file name, minus the path
 7138@ingroup FileSystem*/
 7139String fileName( string fileName );
 7140/*!
 7141@brief Get the path of a file (removes name and extension)
 7142
 7143@param fileName Name and path of file to check
 7144@return String containing the path, minus name and extension
 7145@ingroup FileSystem*/
 7146String filePath( string fileName );
 7147/*!
 7148@brief Reports the current directory
 7149
 7150@return String containing full file path of working directory
 7151@ingroup FileSystem*/
 7152String getWorkingDirectory();
 7153/*!
 7154@brief Converts a relative file path to a full path
 7155
 7156For example, "./console.log" becomes "C:/Torque/t3d/examples/FPS Example/game/console.log"
 7157@param path Name of file or path to check
 7158@param cwd Optional current working directory from which to build the full path.
 7159@return String containing non-relative directory of path
 7160@ingroup FileSystem*/
 7161String makeFullPath( string path="", string cwd="" );
 7162/*!
 7163@brief Turns a full or local path to a relative one
 7164
 7165For example, "./game/art" becomes "game/art"
 7166@param path Full path (may include a file) to convert
 7167@param to Optional base path used for the conversion.  If not supplied the current working directory is used.
 7168@returns String containing relative path
 7169@ingroup FileSystem*/
 7170String makeRelativePath( string path="", string to="" );
 7171/*!
 7172@brief Combines two separate strings containing a file path and file name together into a single string
 7173
 7174@param path String containing file path
 7175@param file String containing file name
 7176@return String containing concatenated file name and path
 7177@ingroup FileSystem*/
 7178String pathConcat( string path="", string file="" );
 7179/*!
 7180@brief Gets the name of the game's executable
 7181
 7182@return String containing this game's executable name
 7183@ingroup FileSystem*/
 7184String getExecutableName();
 7185/*!
 7186@brief Get the absolute path to the directory that contains the main.cs script from which the engine was started.
 7187
 7188This directory will usually contain all the game assets and, in a user-side game installation, will usually be read-only.
 7189
 7190@return The path to the main game assets.
 7191
 7192@ingroup FileSystem*/
 7193String getMainDotCsDir();
 7194/*!
 7195@brief Open the given folder in the system's file manager.
 7196
 7197@param path full path to a directory.
 7198
 7199@note Only present in a Tools build of Torque.
 7200@ingroup FileSystem*/
 7201void openFolder( string path );
 7202/*!
 7203@brief Open the given @a file through the system.  This will usually open the file in its associated application.
 7204@param file %Path of the file to open.
 7205
 7206@note Only present in a Tools build of Torque.
 7207@ingroup FileSystem*/
 7208void openFile( string file );
 7209/*!
 7210@brief Copy a file to a new location.
 7211@param fromFile %Path of the file to copy.
 7212@param toFile %Path where to copy @a fromFile to.
 7213@param noOverwrite If true, then @a fromFile will not overwrite a file that may already exist at @a toFile.
 7214@return True if the file was successfully copied, false otherwise.
 7215@note Only present in a Tools build of Torque.
 7216@ingroup FileSystem*/
 7217bool pathCopy( string fromFile="", string toFile="", bool noOverwrite=true );
 7218/*!
 7219@brief Return the current working directory.
 7220
 7221@return The absolute path of the current working directory.
 7222
 7223@note Only present in a Tools build of Torque.
 7224@see getWorkingDirectory()@ingroup FileSystem*/
 7225String getCurrentDirectory();
 7226/*!
 7227@brief Set the current working directory.
 7228
 7229@param path The absolute or relative (to the current working directory) path of the directory which should be made the new working directory.
 7230
 7231@return True if the working directory was successfully changed to @a path, false otherwise.
 7232
 7233@note Only present in a Tools build of Torque.
 7234@ingroup FileSystem*/
 7235bool setCurrentDirectory( string path );
 7236/*!
 7237@brief Create the given directory or the path leading to the given filename.
 7238
 7239If @a path ends in a trailing slash, then all components in the given path will be created as directories (if not already in place).  If @a path, does @b not end in a trailing slash, then the last component of the path is taken to be a file name and only the directory components of the path will be created.
 7240
 7241@param path The path to create.
 7242
 7243@note Only present in a Tools build of Torque.
 7244@ingroup FileSystem*/
 7245bool createPath( string path );
 7246/*!
 7247@brief Grabs the full path of a specified file
 7248
 7249@param filename Name of the local file to locate
 7250@return String containing the full filepath on disk
 7251@ingroup FileSystem*/
 7252string expandFilename( string filename );
 7253/*!
 7254@brief Retrofits a filepath that uses old Torque style
 7255
 7256@return String containing filepath with new formatting
 7257@ingroup FileSystem*/
 7258string expandOldFilename( string filename );
 7259/*!
 7260@brief nameToID(object)
 7261
 7262
 7263@ingroup UNDOCUMENTED
 7264*/
 7265int nameToID( string objectName );
 7266/*!
 7267@brief isObject(object)
 7268
 7269
 7270@ingroup UNDOCUMENTED
 7271*/
 7272bool isObject( string objectName );
 7273/*!
 7274@brief cancel(eventId)
 7275
 7276
 7277@ingroup UNDOCUMENTED
 7278*/
 7279void cancel( int eventId );
 7280/*!
 7281@brief cancelAll(objectId): cancel pending events on the specified object.  Events will be automatically cancelled if object is deleted.
 7282
 7283
 7284@ingroup UNDOCUMENTED
 7285*/
 7286void cancelAll( string objectId );
 7287/*!
 7288@brief isEventPending(%scheduleId);
 7289
 7290
 7291@ingroup UNDOCUMENTED
 7292*/
 7293bool isEventPending( int scheduleId );
 7294/*!
 7295@brief getEventTimeLeft(scheduleId) Get the time left in ms until this event will trigger.
 7296
 7297
 7298@ingroup UNDOCUMENTED
 7299*/
 7300int getEventTimeLeft( int scheduleId );
 7301/*!
 7302@brief getScheduleDuration(%scheduleId);
 7303
 7304
 7305@ingroup UNDOCUMENTED
 7306*/
 7307int getScheduleDuration( int scheduleId );
 7308/*!
 7309@brief getTimeSinceStart(%scheduleId);
 7310
 7311
 7312@ingroup UNDOCUMENTED
 7313*/
 7314int getTimeSinceStart( int scheduleId );
 7315/*!
 7316@brief schedule(time, refobject|0, command, <arg1...argN>)
 7317
 7318
 7319@ingroup UNDOCUMENTED
 7320*/
 7321int schedule;
 7322/*!
 7323@brief Return true if the given name makes for a valid object name.
 7324
 7325@param name Name of object
 7326@return True if name is allowed, false if denied (usually because it starts with a number, _, or invalid character@ingroup Console*/
 7327bool isValidObjectName( string name );
 7328/*!
 7329@brief Preload all datablocks in client mode.
 7330
 7331
 7332(Server parameter is set to false).  This will take some time to complete.
 7333@ingroup UNDOCUMENTED
 7334*/
 7335void preloadClientDataBlocks();
 7336/*!
 7337@brief Delete all the datablocks we've downloaded.
 7338
 7339
 7340This is usually done in preparation of downloading a new set of datablocks, such as occurs on a mission change, but it's also good post-mission cleanup.
 7341@ingroup UNDOCUMENTED
 7342*/
 7343void deleteDataBlocks();
 7344/*!
 7345@brief Call the given function for each instance of the given class.
 7346
 7347@param className Name of the class for which to enumerate instances.
 7348@param functionName Name of function to call and pass each instance of the given class.
 7349@note This function is only available in debug builds and primarily meant as an aid in debugging.@ingroup Console*/
 7350void debugEnumInstances( string className, string functionName );
 7351/*!
 7352@brief Serialize the object to a file.
 7353
 7354@param object The object to serialize.
 7355@param filename The file name and path.
 7356@ingroup Console*/
 7357bool saveObject( SimObject  object, string filename );
 7358/*!
 7359@brief Loads a serialized object from a file.
 7360
 7361@param Name and path to text file containing the object
 7362@ingroup Console*/
 7363SimObject loadObject( string filename );
 7364/*!
 7365@brief Initializes and open the telnet console.
 7366
 7367@param port        Port to listen on for console connections (0 will shut down listening).
 7368@param consolePass Password for read/write access to console.
 7369@param listenPass  Password for read access to console.
 7370@param remoteEcho  [optional] Enable echoing back to the client, off by default.
 7371
 7372@ingroup Debugging*/
 7373void telnetSetParameters( int port, string consolePass, string listenPass, bool remoteEcho=false );
 7374/*!
 7375@brief Gets a count of available stock colors.
 7376@return A count of available stock colors.
 7377@ingroup UNDOCUMENTED
 7378*/
 7379int getStockColorCount();
 7380/*!
 7381@brief Gets the stock color name at the specified index.
 7382@param stockColorIndex The zero-based index of the stock color name to retrieve.
 7383@return The stock color name at the specified index or nothing if the string is invalid.
 7384@ingroup UNDOCUMENTED
 7385*/
 7386string getStockColorName( int stockColorIndex );
 7387/*!
 7388@brief Gets whether the specified name is a stock color or not.
 7389@param stockColorName - The stock color name to test for.
 7390@return Whether the specified name is a stock color or not.
 7391@ingroup UNDOCUMENTED
 7392*/
 7393bool isStockColor( string stockColorName );
 7394/*!
 7395@brief Gets a floating-point-based stock color by name.
 7396@param stockColorName - The stock color name to retrieve.
 7397@return The stock color that matches the specified color name.  Returns nothing if the color name is not found.
 7398@ingroup UNDOCUMENTED
 7399*/
 7400LinearColorF getStockColorF( string stockColorName );
 7401/*!
 7402@brief Gets a byte-based stock color by name.
 7403@param stockColorName - The stock color name to retrieve.
 7404@return The stock color that matches the specified color name.  Returns nothing if the color name is not found.
 7405@ingroup UNDOCUMENTED
 7406*/
 7407ColorI getStockColorI( string stockColorName );
 7408/*!
 7409@brief Enables logging of the connection protocols
 7410
 7411When enabled a lot of network debugging information is sent to the console.
 7412@param enabled True to enable, false to disable
 7413@ingroup Networking*/
 7414void DNetSetLogging( bool enabled );
 7415/*! UNDOCUMENTED!
 7416@ingroup UNDOCUMENTED
 7417 */
 7418int getMaxFrameAllocation();
 7419/*! UNDOCUMENTED!
 7420@ingroup UNDOCUMENTED
 7421 */
 7422void sbmDumpStats();
 7423/*! UNDOCUMENTED!
 7424@ingroup UNDOCUMENTED
 7425 */
 7426void sbmDumpStrings();
 7427/*!
 7428@brief Dumps information about String memory usage
 7429
 7430@ingroup Debugging
 7431@ingroup Strings*/
 7432void dumpStringMemStats();
 7433/*!
 7434@brief Gets the primary LangTable used by the game
 7435
 7436@return ID of the core LangTable
 7437@ingroup Localization*/
 7438int getCoreLangTable();
 7439/*!
 7440@brief Sets the primary LangTable used by the game
 7441
 7442@param LangTable ID of the core LangTable
 7443@ingroup Localization*/
 7444void setCoreLangTable( string lgTable );
 7445/*!
 7446@brief Compiles a LSO language file. if createIndex is true, will also create languageMap.cs with the global variables for each string index. The input file must follow this example layout: TXT_HELLO_WORLD = Hello world in english!
 7447@ingroup UNDOCUMENTED
 7448*/
 7449void CompileLanguage( string inputFile, bool createMap=false );
 7450/*!
 7451@brief Returns the current %ActionMap.
 7452@see ActionMap@ingroup Input*/
 7453ActionMap getCurrentActionMap();
 7454/*!
 7455allowConnections(bool allow)@brief Sets whether or not the global NetInterface allows connections from remote hosts.
 7456
 7457@param allow Set to true to allow remote connections.
 7458@ingroup Networking*/
 7459void allowConnections( bool allow );
 7460/*!
 7461@brief Dump the current contents of the networked string table to the console.
 7462
 7463The results are returned in three columns.  The first column is the network string ID.  The second column is the string itself.  The third column is the reference count to the network string.
 7464
 7465@note This function is available only in debug builds.
 7466
 7467@ingroup Networking*/
 7468void dumpNetStringTable();
 7469/*!
 7470@brief Reset FPS stats (fps::)
 7471
 7472@ingroup Game*/
 7473void resetFPSTracker();
 7474/*!
 7475@brief Takes a string informing the backend where to store sample data and optionally a name of the specific logging backend to use.  The default is the CSV backend. In most cases, the logging store will be a file name.@tsexample
 7476beginSampling( "mysamples.csv" );
 7477@endtsexample
 7478
 7479@ingroup Rendering*/
 7480void beginSampling( string location, string backend="CSV" );
 7481/*!
 7482@brief Stops the rendering sampler
 7483
 7484@ingroup Rendering*/
 7485void stopSampling();
 7486/*!
 7487@brief Enable sampling for all keys that match the given name pattern. Slashes are treated as separators.
 7488
 7489@ingroup Rendering*/
 7490void enableSamples( string pattern, bool state=true );
 7491/*!
 7492@brief Solve a quadratic equation (2nd degree polynomial) of form a*x^2 + b*x + c = 0.
 7493
 7494@param a First Coefficient.@param b Second Coefficient.@param c Third Coefficient.@returns A triple, containing: (sol x0 x1). (sol) is the number of solutions(being 0, 1, or 2), and (x0) and (x1) are the solutions, if any.@ingroup Math*/
 7495string mSolveQuadratic( float a, float b, float c );
 7496/*!
 7497@brief Solve a cubic equation (3rd degree polynomial) of form a*x^3 + b*x^2 + c*x + d = 0.
 7498
 7499@param a First Coefficient.@param b Second Coefficient.@param c Third Coefficient.@param d Fourth Coefficient.@returns A 4-tuple, containing: (sol x0 x1 x2). (sol) is the number of solutions(being 0, 1, 2 or 3), and (x0), (x1) and (x2) are the solutions, if any.@ingroup Math*/
 7500string mSolveCubic( float a, float b, float c, float d );
 7501/*!
 7502@brief Solve a quartic equation (4th degree polynomial) of form a*x^4 + b*x^3 + c*x^2 + d*x + e = 0.
 7503
 7504@param a First Coefficient.@param b Second Coefficient.@param c Third Coefficient.@param d Fourth Coefficient.@param e Fifth Coefficient.@returns A 5-tuple, containing: (sol x0 x1 x2 c3). (sol) is the number of solutions(being 0, 1, 2, 3 or 4), and (x0), (x1), (x2) and (x3) are the solutions, if any.@ingroup Math*/
 7505string mSolveQuartic( float a, float b, float c, float d, float e );
 7506/*!
 7507@brief Round v down to the nearest integer.
 7508
 7509@param v Number to convert to integer.@returns Number converted to integer.@ingroup Math*/
 7510int mFloor( float v );
 7511/*!
 7512@brief Round v to the nth decimal place or the nearest whole number by default.@param v Value to roundn@return The rounded value as a S32.@ingroup Math
 7513
 7514
 7515@ingroup UNDOCUMENTED
 7516*/
 7517int mRound( float v );
 7518/*!
 7519@brief Round v to the nearest number based on the delta@param v Value to round@param d Delta use when rounding@return The rounded value as a S32.@ingroup Math
 7520
 7521
 7522@ingroup UNDOCUMENTED
 7523*/
 7524int mRoundDelta( float v=0.0, int d=1 );
 7525/*!
 7526@brief Round v to the nth decimal place or the nearest whole number by default.@param v Value to roundn@param n Number of decimal places to round to, 0 by defaultn@return The rounded value as a S32.@ingroup Math
 7527
 7528
 7529@ingroup UNDOCUMENTED
 7530*/
 7531float mRoundColour( float v, int n=0 );
 7532/*!
 7533@brief Round v up to the nearest integer.
 7534
 7535@param v Number to convert to integer.@returns Number converted to integer.@ingroup Math*/
 7536int mCeil( float v );
 7537/*!
 7538@brief Formats the specified number to the given number of decimal places.
 7539
 7540@param v Number to format.@param precision Number of decimal places to format to (1-9).@returns Number formatted to the specified number of decimal places.@ingroup Math*/
 7541string mFloatLength( float v, uint precision );
 7542/*!
 7543@brief Calculate absolute value of specified value.
 7544
 7545@param v Input Value.@returns Absolute value of specified value.@ingroup Math*/
 7546float mAbs( float v );
 7547/*!
 7548@brief Calculate the remainder of v/d.
 7549
 7550@param v Input Value.@param d Divisor Value.@returns The remainder of v/d.@ingroup Math*/
 7551float mFMod( float v, float d );
 7552/*!
 7553@brief Calculate the square-root of v.
 7554
 7555@param v Input Value.@returns The square-root of the input value.@ingroup Math*/
 7556float mSqrt( float v );
 7557/*!
 7558@brief Calculate b raised to the p-th power.
 7559
 7560@param v Input Value.@param p Power to raise value by.@returns v raised to the p-th power.@ingroup Math*/
 7561float mPow( float v, float p );
 7562/*!
 7563@brief Calculate the natural logarithm of v.
 7564
 7565@param v Input Value.@returns The natural logarithm of the input value.@ingroup Math*/
 7566float mLog( float v );
 7567/*!
 7568@brief Calculate the sine of v.
 7569
 7570@param v Input Value (in radians).@returns The sine of the input value.@ingroup Math*/
 7571float mSin( float v );
 7572/*!
 7573@brief Calculate the cosine of v.
 7574
 7575@param v Input Value (in radians).@returns The cosine of the input value.@ingroup Math*/
 7576float mCos( float v );
 7577/*!
 7578@brief Calculate the tangent of v.
 7579
 7580@param v Input Value (in radians).@returns The tangent of the input value.@ingroup Math*/
 7581float mTan( float v );
 7582/*!
 7583@brief Calculate the arc-sine of v.
 7584
 7585@param v Input Value (in radians).@returns The arc-sine of the input value.@ingroup Math*/
 7586float mAsin( float v );
 7587/*!
 7588@brief Calculate the arc-cosine of v.
 7589
 7590@param v Input Value (in radians).@returns The arc-cosine of the input value.@ingroup Math*/
 7591float mAcos( float v );
 7592/*!
 7593@brief Calculate the arc-tangent (slope) of a line defined by rise and run.
 7594
 7595@param rise of line.@param run of line.@returns The arc-tangent (slope) of a line defined by rise and run.@ingroup Math*/
 7596float mAtan( float rise, float run );
 7597/*!
 7598@brief Convert specified radians into degrees.
 7599
 7600@param radians Input Value (in radians).@returns The specified radians value converted to degrees.@ingroup Math*/
 7601float mRadToDeg( float radians );
 7602/*!
 7603@brief Convert specified degrees into radians.
 7604
 7605@param degrees Input Value (in degrees).@returns The specified degrees value converted to radians.@ingroup Math*/
 7606float mDegToRad( float degrees );
 7607/*!
 7608@brief Clamp the specified value between two bounds.
 7609
 7610@param v Input value.@param min Minimum Bound.@param max Maximum Bound.@returns The specified value clamped to the specified bounds.@ingroup Math*/
 7611float mClamp( float v, float min, float max );
 7612/*!
 7613@brief Clamp the specified value between 0 and 1 (inclusive).
 7614
 7615@param v Input value.@returns The specified value clamped between 0 and 1 (inclusive).@ingroup Math*/
 7616float mSaturate( float v );
 7617/*!
 7618@brief Wrap the specified value between two bounds.
 7619
 7620@param v Input value.@param min Minimum Bound.@param max Maximum Bound.@returns The specified value wrapped to the specified bounds.@ingroup Math*/
 7621float mWrapF( float v, float min, float max );
 7622/*!
 7623@brief Wrap the specified value between two bounds.
 7624
 7625@param v Input value.@param min Minimum Bound.@param max Maximum Bound.@returns The specified value wrapped to the specified bounds.@ingroup Math*/
 7626int mWrap( int v, int min, int max );
 7627/*!
 7628@brief Calculate the greater of two specified numbers.
 7629
 7630@param v1 Input value.@param v2 Input value.@returns The greater value of the two specified values.@ingroup Math*/
 7631float getMax( float v1, float v2 );
 7632/*!
 7633@brief Calculate the lesser of two specified numbers.
 7634
 7635@param v1 Input value.@param v2 Input value.@returns The lesser value of the two specified values.@ingroup Math*/
 7636float getMin( float v1, float v2 );
 7637/*!
 7638@brief Calculate linearly interpolated value between two specified numbers using specified normalized time.
 7639
 7640@param v1 Interpolate From Input value.@param v2 Interpolate To Input value.@param time Normalized time used to interpolate values (0-1).@returns The interpolated value between the two specified values at normalized time t.@ingroup Math*/
 7641float mLerp( float v1, float v2, float time );
 7642/*!
 7643@brief Return the value of PI (half-circle in radians).
 7644
 7645@returns The value of PI.@ingroup Math*/
 7646float mPi();
 7647/*!
 7648@brief Return the value of 2*PI (full-circle in radians).
 7649
 7650@returns The value of 2*PI.@ingroup Math*/
 7651float m2Pi();
 7652/*!
 7653@brief Returns whether the value is an exact power of two.
 7654
 7655@param v Input value.@returns Whether the specified value is an exact power of two.@ingroup Math*/
 7656bool mIsPow2( int v );
 7657/*!
 7658@brief Returns a randomized direction based on a starting axis and the min/max angles.
 7659
 7660@param axis Main axis to deviate the direction from.@param angleMin minimum amount of deviation from the axis.@param angleMax maximum amount of deviation from the axis.@returns Randomized direction vector.@ingroup Math*/
 7661Point3F mRandomDir( Point3F axis, float angleMin, float angleMax );
 7662/*!
 7663@brief Returns a randomized point inside a sphere of a given radius.
 7664
 7665@param radius The radius of the sphere to find a point in.@returns Randomized point inside a sphere.@ingroup Math*/
 7666Point3F mRandomPointInSphere( float radius );
 7667/*!
 7668@brief Returns angle between two vectors.
 7669
 7670@param vecA First input vector.@param vecB Second input vector.@returns Angle between both vectors in radians.@ingroup Math*/
 7671float mGetAngleBetweenVectors( VectorF vecA, VectorF vecB );
 7672/*!
 7673@brief Returns signed angle between two vectors, using a normal for orientation.
 7674
 7675@param vecA First input vector.@param vecB Second input vector.@param norm Normal/Cross Product vector.@returns Angle between both vectors in radians.@ingroup Math*/
 7676float mGetSignedAngleBetweenVectors( VectorF vecA=VectorF::Zero, VectorF vecB=VectorF::Zero, VectorF norm=VectorF::Zero );
 7677/*!
 7678@brief Adds two rotations together.
 7679
 7680@param a Rotation one.@param b Rotation two.@returns v sum of both rotations.@ingroup Math*/
 7681RotationF AddRotation( RotationF a, RotationF b );
 7682/*!
 7683@brief Subtracts two rotations.
 7684
 7685@param a Rotation one.@param b Rotation two.@returns v difference of both rotations.@ingroup Math*/
 7686RotationF SubtractRotation( RotationF a, RotationF b );
 7687/*!
 7688@brief Interpolates between two rotations.
 7689
 7690@param a Rotation one.@param b Rotation two.@param factor The amount to interpolate between the two.@returns v, interpolated result.@ingroup Math*/
 7691RotationF InterpolateRotation( RotationF a, RotationF b, float factor );
 7692/*!
 7693@brief Provides a rotation orientation to look at a target from a given position.
 7694
 7695@param origin Position of the object doing the looking.@param target Position to be looked at.@param up The up angle to orient the rotation.@returns v orientation result.@ingroup Math*/
 7696RotationF RotationLookAt( Point3F origin=Point3F(0, 0, 0), Point3F target=Point3F(0, 0, 0), Point3F up=Point3F(0, 0, 1) );
 7697/*!
 7698@brief Sets the right vector of the rotation.
 7699
 7700@param Starting rotation.@param New up vector.@returns New rotation with the set right vector.@ingroup Math*/
 7701RotationF setRotationRightVector( RotationF rot, VectorF rightVec );
 7702/*!
 7703@brief Sets the up vector of the rotation.
 7704
 7705@param Starting rotation.@param New up vector.@returns New rotation with the set up vector.@ingroup Math*/
 7706RotationF setRotationUpVector( RotationF rot, VectorF upVec );
 7707/*!
 7708@brief Get the forward vector of a rotation.
 7709
 7710@ingroup Math*/
 7711VectorF getRotationForwardVector( RotationF rot );
 7712/*!
 7713@brief Gets the right vector of a rotation.
 7714
 7715@param Our rotation.@ingroup Math*/
 7716VectorF getRotationRightVector( RotationF rot );
 7717/*!
 7718@brief Gets the up vector of a rotation.
 7719
 7720@param Our rotation.@ingroup Math*/
 7721VectorF getRotationUpVector( RotationF rot );
 7722/*!
 7723@brief Gets the direction from the rotation's angles.
 7724
 7725@param Our rotation.@ingroup Math*/
 7726Point3F getRotationDirection( RotationF rot );
 7727/*!
 7728@brief Add two vectors.
 7729
 7730@param a The first vector.
 7731@param b The second vector.
 7732@return The vector @a a + @a b.
 7733
 7734@tsexample
 7735//-----------------------------------------------------------------------------
 7736//
 7737// VectorAdd( %a, %b );
 7738//
 7739// The sum of vector a, (ax, ay, az), and vector b, (bx, by, bz) is:
 7740//
 7741//     a + b = ( ax + bx, ay + by, az + bz )
 7742//
 7743//-----------------------------------------------------------------------------
 7744%a = "1 0 0";
 7745%b = "0 1 0";
 7746
 7747// %r = "( 1 + 0, 0 + 1, 0 + 0 )";
 7748// %r = "1 1 0";
 7749%r = VectorAdd( %a, %b );
 7750@endtsexample
 7751
 7752@ingroup Vectors*/
 7753VectorF VectorAdd( VectorF a, VectorF b );
 7754/*!
 7755@brief Subtract two vectors.
 7756
 7757@param a The first vector.
 7758@param b The second vector.
 7759@return The vector @a a - @a b.
 7760
 7761@tsexample
 7762//-----------------------------------------------------------------------------
 7763//
 7764// VectorSub( %a, %b );
 7765//
 7766// The difference of vector a, (ax, ay, az), and vector b, (bx, by, bz) is:
 7767//
 7768//     a - b = ( ax - bx, ay - by, az - bz )
 7769//
 7770//-----------------------------------------------------------------------------
 7771
 7772%a = "1 0 0";
 7773%b = "0 1 0";
 7774
 7775// %r = "( 1 - 0, 0 - 1, 0 - 0 )";
 7776// %r = "1 -1 0";
 7777%r = VectorSub( %a, %b );
 7778@endtsexample
 7779
 7780@ingroup Vectors*/
 7781VectorF VectorSub( VectorF a, VectorF b );
 7782/*!
 7783@brief Scales a vector by a scalar.
 7784
 7785@param a The vector to scale.
 7786@param scalar The scale factor.
 7787@return The vector @a a * @a scalar.
 7788
 7789@tsexample
 7790//-----------------------------------------------------------------------------
 7791//
 7792// VectorScale( %a, %v );
 7793//
 7794// Scaling vector a, (ax, ay, az), but the scalar, v, is:
 7795//
 7796//     a * v = ( ax * v, ay * v, az * v )
 7797//
 7798//-----------------------------------------------------------------------------
 7799
 7800%a = "1 1 0";
 7801%v = "2";
 7802
 7803// %r = "( 1 * 2, 1 * 2, 0 * 2 )";
 7804// %r = "2 2 0";
 7805%r = VectorScale( %a, %v );
 7806@endtsexample
 7807
 7808@ingroup Vectors*/
 7809VectorF VectorScale( VectorF a, float scalar );
 7810/*!
 7811@brief Multiplies two vectors.
 7812
 7813@param a The first vector.
 7814@param b The second vector.
 7815@return The vector @a a * @a b.
 7816
 7817@tsexample
 7818//-----------------------------------------------------------------------------
 7819//
 7820// VectorMul( %a, %b );
 7821//
 7822// The multiplication of vector a, (ax, ay, az), and vector b, (bx, by, bz) is:
 7823//
 7824//     a * b = ( ax * bx, ay * by, az * bz )
 7825//
 7826//-----------------------------------------------------------------------------
 7827
 7828%a = "1 0 0";
 7829%b = "0 1 0";
 7830
 7831// %r = "( 1 * 0, 0 * 1, 0 * 0 )";
 7832// %r = "0 0 0";
 7833%r = VectorMul( %a, %b );
 7834@endtsexample
 7835
 7836@ingroup Vectors*/
 7837VectorF VectorMul( VectorF a, VectorF b );
 7838/*!
 7839@brief Divide two vectors.
 7840
 7841@param a The first vector.
 7842@param b The second vector.
 7843@return The vector @a a / @a b.
 7844
 7845@tsexample
 7846//-----------------------------------------------------------------------------
 7847//
 7848// VectorDiv( %a, %b );
 7849//
 7850// The division of vector a, (ax, ay, az), and vector b, (bx, by, bz) is:
 7851//
 7852//     a * b = ( ax / bx, ay / by, az / bz )
 7853//
 7854//-----------------------------------------------------------------------------
 7855
 7856%a = "1 1 1";
 7857%b = "2 2 2";
 7858
 7859// %r = "( 1 / 2, 1 / 2, 1 / 2 )";
 7860// %r = "0.5 0.5 0.5";
 7861%r = VectorDiv( %a, %b );
 7862@endtsexample
 7863
 7864@ingroup Vectors*/
 7865VectorF VectorDiv( VectorF a, VectorF b );
 7866/*!
 7867@brief Brings a vector into its unit form, i.e. such that it has the magnitute 1.
 7868
 7869@param v The vector to normalize.
 7870@return The vector @a v scaled to length 1.
 7871
 7872@tsexample
 7873//-----------------------------------------------------------------------------
 7874//
 7875// VectorNormalize( %a );
 7876//
 7877// The normalized vector a, (ax, ay, az), is:
 7878//
 7879//     a^ = a / ||a||
 7880//        = ( ax / ||a||, ay / ||a||, az / ||a|| )
 7881//
 7882//-----------------------------------------------------------------------------
 7883
 7884%a = "1 1 0";
 7885%l = 1.414;
 7886
 7887// %r = "( 1 / 1.141, 1 / 1.141, 0 / 1.141 )";
 7888// %r = "0.707 0.707 0";
 7889%r = VectorNormalize( %a );
 7890@endtsexample
 7891
 7892@ingroup Vectors*/
 7893VectorF VectorNormalize( VectorF v );
 7894/*!
 7895@brief Compute the dot product of two vectors.
 7896
 7897@param a The first vector.
 7898@param b The second vector.
 7899@return The dot product @a a * @a b.
 7900
 7901@tsexample
 7902//-----------------------------------------------------------------------------
 7903//
 7904// VectorDot( %a, %b );
 7905//
 7906// The dot product between vector a, (ax, ay, az), and vector b, (bx, by, bz), is:
 7907//
 7908//     a . b = ( ax * bx + ay * by + az * bz )
 7909//
 7910//-----------------------------------------------------------------------------
 7911
 7912%a = "1 1 0";
 7913%b = "2 0 1";
 7914
 7915// %r = "( 1 * 2 + 1 * 0 + 0 * 1 )";
 7916// %r = 2;
 7917%r = VectorDot( %a, %b );
 7918@endtsexample
 7919
 7920@ingroup Vectors*/
 7921float VectorDot( VectorF a, VectorF b );
 7922/*!
 7923@brief Calculcate the cross product of two vectors.
 7924
 7925@param a The first vector.
 7926@param b The second vector.
 7927@return The cross product @a x @a b.
 7928
 7929@tsexample
 7930//-----------------------------------------------------------------------------
 7931//
 7932// VectorCross( %a, %b );
 7933//
 7934// The cross product of vector a, (ax, ay, az), and vector b, (bx, by, bz), is
 7935//
 7936//     a x b = ( ( ay * bz ) - ( az * by ), ( az * bx ) - ( ax * bz ), ( ax * by ) - ( ay * bx ) )
 7937//
 7938//-----------------------------------------------------------------------------
 7939
 7940%a = "1 1 0";
 7941%b = "2 0 1";
 7942
 7943// %r = "( ( 1 * 1 ) - ( 0 * 0 ), ( 0 * 2 ) - ( 1 * 1 ), ( 1 * 0 ) - ( 1 * 2 ) )";
 7944// %r = "1 -1 -2";
 7945%r = VectorCross( %a, %b );
 7946@endtsexample
 7947
 7948@ingroup Vectors*/
 7949VectorF VectorCross( VectorF a, VectorF b );
 7950/*!
 7951@brief Compute the distance between two vectors.
 7952
 7953@param a The first vector.
 7954@param b The second vector.
 7955@return The length( @a b - @a a ).
 7956
 7957@tsexample
 7958//-----------------------------------------------------------------------------
 7959//
 7960// VectorDist( %a, %b );
 7961//
 7962// The distance between vector a, (ax, ay, az), and vector b, (bx, by, bz), is
 7963//
 7964//     a -> b = ||( b - a )||
 7965//            = ||( bx - ax, by - ay, bz - az )||
 7966//            = mSqrt( ( bx - ax ) * ( bx - ax ) + ( by - ay ) * ( by - ay ) + ( bz - az ) * ( bz - az ) )
 7967//
 7968//-----------------------------------------------------------------------------
 7969
 7970%a = "1 1 0";
 7971%b = "2 0 1";
 7972
 7973// %r = mSqrt( ( 2 - 1 ) * ( 2 - 1) + ( 0 - 1 ) * ( 0 - 1 ) + ( 1 - 0 ) * ( 1 - 0 ) );
 7974// %r = mSqrt( 3 );
 7975%r = VectorDist( %a, %b );
 7976@endtsexample
 7977
 7978@ingroup Vectors*/
 7979float VectorDist( VectorF a, VectorF b );
 7980/*!
 7981@brief Gets the midpoint between the two vectors.
 7982
 7983@param a The first vector.
 7984@param b The second vector.
 7985@return The vector (@a a + @a b) / 2.
 7986
 7987@tsexample
 7988//-----------------------------------------------------------------------------
 7989//
 7990// VectorMidPoint( %a, %b );
 7991//
 7992// The midpoint of vector a, (ax, ay, az), and vector b, (bx, by, bz) is:
 7993//
 7994//     (a + b)/2 = ( (ax + bx) /2, ay + by) /2, (az + bz) /2 )
 7995//
 7996//-----------------------------------------------------------------------------
 7997@endtsexample
 7998
 7999@ingroup Vectors*/
 8000VectorF VectorMidPoint( VectorF a, VectorF b );
 8001/*!
 8002@brief Calculate the magnitude of the given vector.
 8003
 8004@param v A vector.
 8005@return The length of vector @a v.
 8006
 8007@tsexample
 8008//-----------------------------------------------------------------------------
 8009//
 8010// VectorLen( %a );
 8011//
 8012// The length or magnitude of  vector a, (ax, ay, az), is:
 8013//
 8014//     ||a|| = Sqrt( ax * ax + ay * ay + az * az )
 8015//
 8016//-----------------------------------------------------------------------------
 8017
 8018%a = "1 1 0";
 8019
 8020// %r = mSqrt( 1 * 1 + 1 * 1 + 0 * 0 );
 8021// %r = mSqrt( 2 );
 8022// %r = 1.414;
 8023%r = VectorLen( %a );
 8024@endtsexample
 8025
 8026@ingroup Vectors*/
 8027float VectorLen( VectorF v );
 8028/*!
 8029@brief Create an orthogonal basis from the given vector.
 8030
 8031@param aaf The vector to create the orthogonal basis from.
 8032@return A matrix representing the orthogonal basis.
 8033@ingroup Vectors*/
 8034MatrixF VectorOrthoBasis( AngAxisF aa );
 8035/*!
 8036@brief rotate a vector in 2d
 8037
 8038
 8039@ingroup UNDOCUMENTED
 8040*/
 8041string VectorRot( Point3F v, float angle );
 8042/*!
 8043@brief Linearly interpolate between two vectors by @a t.
 8044
 8045@param a Vector to start interpolation from.
 8046@param b Vector to interpolate to.
 8047@param t Interpolation factor (0-1).  At zero, @a a is returned and at one, @a b is returned.  In between, an interpolated vector between @a a and @a b is returned.
 8048@return An interpolated vector between @a a and @a b.
 8049
 8050@tsexample
 8051//-----------------------------------------------------------------------------
 8052//
 8053// VectorLerp( %a, %b );
 8054//
 8055// The point between vector a, (ax, ay, az), and vector b, (bx, by, bz), which is
 8056// weighted by the interpolation factor, t, is
 8057//
 8058//     r = a + t * ( b - a )
 8059//       = ( ax + t * ( bx - ax ), ay + t * ( by - ay ), az + t * ( bz - az ) )
 8060//
 8061//-----------------------------------------------------------------------------
 8062
 8063%a = "1 1 0";
 8064%b = "2 0 1";
 8065%v = "0.25";
 8066
 8067// %r = "( 1 + 0.25 * ( 2 - 1 ), 1 + 0.25 * ( 0 - 1 ), 0 + 0.25 * ( 1 - 0 ) )";
 8068// %r = "1.25 0.75 0.25";
 8069%r = VectorLerp( %a, %b );
 8070@endtsexample
 8071
 8072@ingroup Vectors*/
 8073VectorF VectorLerp( VectorF a, VectorF b, float t );
 8074/*!
 8075@brief Compute the reflection of a vector based on a normal.
 8076
 8077@param a The vector.
 8078@param b The normal.
 8079@return The reflected vector.
 8080
 8081@ingroup Vectors*/
 8082VectorF VectorReflect( VectorF vec, VectorF normal );
 8083/*!
 8084@brief Create a transform from the given translation and orientation.
 8085
 8086@param position The translation vector for the transform.
 8087@param orientation The axis and rotation that orients the transform.
 8088@return A transform based on the given position and orientation.
 8089@ingroup Matrices*/
 8090TransformF MatrixCreate( VectorF position, AngAxisF orientation );
 8091/*!
 8092@brief @Create a matrix from the given rotations.
 8093
 8094
 8095@param Vector3F X, Y, and Z rotation in *radians*.
 8096@return A transform based on the given orientation.
 8097@ingroup Matrices*/
 8098TransformF MatrixCreateFromEuler( Point3F angles );
 8099/*!
 8100@brief Multiply the two matrices.
 8101
 8102@param left First transform.
 8103@param right Right transform.
 8104@return Concatenation of the two transforms.
 8105@ingroup Matrices*/
 8106TransformF MatrixMultiply( TransformF left, TransformF right );
 8107/*!
 8108@brief Multiply the vector by the transform assuming that w=0.
 8109
 8110This function will multiply the given vector by the given transform such that translation will not affect the vector.
 8111
 8112@param transform A transform.
 8113@param vector A vector.
 8114@return The transformed vector.
 8115@ingroup Matrices*/
 8116VectorF MatrixMulVector( TransformF transform, VectorF vector );
 8117/*!
 8118@brief Multiply the given point by the given transform assuming that w=1.
 8119
 8120This function will multiply the given vector such that translation with take effect.
 8121@param transform A transform.
 8122@param point A vector.
 8123@return The transformed vector.
 8124@ingroup Matrices*/
 8125Point3F MatrixMulPoint( TransformF transform, Point3F point );
 8126/*!
 8127@brief Get the center point of an axis-aligned box.
 8128
 8129
 8130@param b A Box3F, in string format using "minExtentX minExtentY minExtentZ maxExtentX maxExtentY maxExtentZ"
 8131@return Center of the box.
 8132@ingroup Math*/
 8133Point3F getBoxCenter( Box3F box );
 8134/*!
 8135@brief Set the current seed for the random number generator.
 8136
 8137Based on this seed, a repeatable sequence of numbers will be produced by getRandom().
 8138@param seed The seed with which to initialize the randon number generator with.  The same seed will always leed tothe same sequence of pseudo-random numbers.
 8139If -1, the current timestamp will be used as the seed which is a good basis for randomization.
 8140@ingroup Random*/
 8141void setRandomSeed( int seed=-1 );
 8142/*!
 8143@brief Get the current seed used by the random number generator.
 8144
 8145@return The current random number generator seed value.
 8146@ingroup Random*/
 8147int getRandomSeed();
 8148/*!
 8149@brief Returns a random number based on parameters passed in..
 8150
 8151If no parameters are passed in, getRandom() will return a float between 0.0 and 1.0. If one parameter is passed an integer between 0 and the passed in value will be returned. Two parameters will return an integer between the specified numbers.
 8152
 8153@param a If this is the only parameter, a number between 0 and a is returned. Elsewise represents the lower bound.
 8154@param b Upper bound on the random number.  The random number will be <= @a b.
 8155@return A pseudo-random integer between @a a and @a b, between 0 and a, or a float between 0.0 and 1.1 depending on usage.
 8156
 8157@note All parameters are optional.@see setRandomSeed
 8158@ingroup Random*/
 8159float getRandom( int a=S32_MAX, int b=S32_MAX );
 8160/*!
 8161@brief restartInstance()
 8162
 8163
 8164@ingroup UNDOCUMENTED
 8165*/
 8166void restartInstance;
 8167/*!
 8168@brief Fatal Script Assertion
 8169
 8170
 8171@ingroup UNDOCUMENTED
 8172*/
 8173void Assert( bool condition, string message );
 8174/*!
 8175@brief getUserDataDirectory()
 8176
 8177
 8178@ingroup UNDOCUMENTED
 8179*/
 8180string getUserDataDirectory();
 8181/*!
 8182@brief getUserHomeDirectory()
 8183
 8184
 8185@ingroup UNDOCUMENTED
 8186*/
 8187string getUserHomeDirectory();
 8188/*!
 8189@brief setMainDotCsDir()
 8190
 8191
 8192@ingroup UNDOCUMENTED
 8193*/
 8194void setMainDotCsDir( string path );
 8195/*!
 8196@brief Used to validate memory space for the game.
 8197
 8198@ingroup Debugging*/
 8199void validateMemory();
 8200/*!
 8201@brief Dumps some useful statistics regarding free memory.
 8202
 8203Dumps an analysis of 'free chunks' of memory. Does not print how much memory is free.
 8204
 8205@ingroup Debugging*/
 8206void freeMemoryDump();
 8207/*!
 8208@brief Flags all current memory allocations.
 8209
 8210Flags all current memory allocations for exclusion in subsequent calls to dumpUnflaggedAllocs(). Helpful in detecting memory leaks and analyzing memory usage.
 8211
 8212@ingroup Debugging*/
 8213void flagCurrentAllocs();
 8214/*!
 8215@brief Dumps all unflagged memory allocations.
 8216
 8217Dumps all memory allocations that were made after a call to flagCurrentAllocs(). Helpful when used with flagCurrentAllocs() for detecting memory leaks and analyzing general memory usage.
 8218
 8219@param fileName Optional file path and location to dump all memory allocations not flagged by flagCurrentAllocs(). If left blank, data will be dumped to the console.
 8220
 8221@tsexample
 8222dumpMemSnapshot(); // dumps info to console
 8223dumpMemSnapshot( "C:/Torque/profilerlog1.txt" ); // dumps info to file
 8224@endtsexample
 8225
 8226@note Available in debug builds only. In torqueConfig.h, TORQUE_DISABLE_MEMORY_MANAGER must be undefined to use this function.
 8227
 8228@ingroup Debugging*/
 8229void dumpUnflaggedAllocs( string fileName="" );
 8230/*!
 8231@brief Dumps information about the given allocated memory block.
 8232
 8233@param allocNum Memory block to dump information about.@note Available in debug builds only. In torqueConfig.h, TORQUE_DISABLE_MEMORY_MANAGER must be undefined to use this function.
 8234
 8235@ingroup Debugging*/
 8236void dumpAlloc( int allocNum );
 8237/*!
 8238@brief Dumps a snapshot of current memory to a file.
 8239
 8240The total memory used will also be output to the console.
 8241This function will attempt to create the file if it does not already exist.
 8242@param fileName Name and path of file to save profiling stats to. Must use forward slashes (/)
 8243@tsexample
 8244dumpMemSnapshot( "C:/Torque/ProfilerLogs/profilerlog1.txt" );
 8245@endtsexample
 8246
 8247@note Available in debug builds only. In torqueConfig.h, TORQUE_DISABLE_MEMORY_MANAGER must be undefined to use this function.
 8248
 8249@ingroup Debugging*/
 8250void dumpMemSnapshot( string fileName );
 8251/*!
 8252@brief startPrecisionTimer() - Create and start a high resolution platform timer. Returns the timer id.
 8253
 8254
 8255@ingroup UNDOCUMENTED
 8256*/
 8257int startPrecisionTimer();
 8258/*!
 8259@brief stopPrecisionTimer( S32 id ) - Stop and destroy timer with the passed id.  Returns the elapsed milliseconds.
 8260
 8261
 8262@ingroup UNDOCUMENTED
 8263*/
 8264int stopPrecisionTimer( int id );
 8265/*!
 8266@brief Enable or disable a specific profile.
 8267
 8268@param enable   Optional paramater to enable or disable the profile.
 8269@param markerName Name of a specific marker to enable or disable.
 8270@note Calling this function will first call profilerReset(), clearing all data from profiler. All profile markers are enabled by default.
 8271
 8272@ingroup Debugging*/
 8273void profilerMarkerEnable( string markerName, bool enable=true );
 8274/*!
 8275@brief Enables or disables the profiler.
 8276
 8277Data is only gathered while the profiler is enabled.
 8278
 8279@note Profiler is not available in shipping builds.
 8280T3D has predefined profiling areas surrounded by markers, but you may need to define additional markers (in C++) around areas you wish to profile, by using the PROFILE_START( markerName ); and PROFILE_END(); macros.
 8281
 8282@ingroup Debugging*/
 8283void profilerEnable( bool enable );
 8284/*!
 8285@brief Dumps current profiling stats to the console window.
 8286
 8287@note Markers disabled with profilerMarkerEnable() will be skipped over. If the profiler is currently running, it will be disabled.
 8288@ingroup Debugging*/
 8289void profilerDump();
 8290/*!
 8291@brief Dumps current profiling stats to a file.
 8292
 8293@note If the profiler is currently running, it will be disabled.
 8294@param fileName Name and path of file to save profiling stats to. Must use forward slashes (/). Will attempt to create the file if it does not already exist.
 8295@tsexample
 8296profilerDumpToFile( "C:/Torque/log1.txt" );
 8297@endtsexample
 8298
 8299@ingroup Debugging*/
 8300void profilerDumpToFile( string fileName );
 8301/*!
 8302@brief Resets the profiler, clearing it of all its data.
 8303
 8304If the profiler is currently running, it will first be disabled. All markers will retain their current enabled/disabled status.
 8305
 8306@ingroup Debugging*/
 8307void profilerReset();
 8308/*!
 8309@brief Display a modal message box using the platform's native message box implementation.
 8310
 8311
 8312@param title The title to display on the message box window.
 8313@param message The text message to display in the box.
 8314@param buttons Which buttons to put on the message box.
 8315@param icons Which icon to show next to the message.
 8316@return One of $MROK, $MRCancel, $MRRetry, and $MRDontSave identifying the button that the user pressed.
 8317@tsexample
 8318messageBox( "Error", "" );
 8319@endtsexample
 8320
 8321@ingroup Platform*/
 8322int messageBox( string title, string message, MBButtons buttons=MBOkCancel, MBIcons icons=MIInformation );
 8323/*!
 8324@brief Determines if a dispatcher queue exists
 8325
 8326@param queueName String containing the name of queue
 8327@ingroup Messaging*/
 8328bool isQueueRegistered( string queueName );
 8329/*!
 8330@brief Registeres a dispatcher queue
 8331
 8332@param queueName String containing the name of queue
 8333@ingroup Messaging*/
 8334void registerMessageQueue( string queueName );
 8335/*!
 8336@brief Unregisters a dispatcher queue
 8337
 8338@param queueName String containing the name of queue
 8339@ingroup Messaging*/
 8340void unregisterMessageQueue( string queueName );
 8341/*!
 8342@brief Registers an event message
 8343
 8344@param queueName String containing the name of queue to attach listener to
 8345@param listener Name of event messenger
 8346@ingroup Messaging*/
 8347bool registerMessageListener( string queueName, string listenerName );
 8348/*!
 8349@brief Unregisters an event message
 8350
 8351@param queueName String containing the name of queue
 8352@param listener Name of event messenger
 8353@ingroup Messaging*/
 8354void unregisterMessageListener( string queueName, string listenerName );
 8355/*!
 8356@brief Dispatch a message to a queue
 8357
 8358@param queueName Queue to dispatch the message to
 8359@param message Message to dispatch
 8360@param data Data for message
 8361@return True for success, false for failure
 8362@see dispatchMessageObject
 8363@ingroup Messaging*/
 8364bool dispatchMessage( string queueName, string message, string data="" );
 8365/*!
 8366@brief Dispatch a message object to a queue
 8367
 8368@param queueName Queue to dispatch the message to
 8369@param message Message to dispatch
 8370@return true for success, false for failure
 8371@see dispatchMessage
 8372@ingroup Messaging*/
 8373bool dispatchMessageObject( string queueName="", string message="" );
 8374/*!
 8375@brief Returns the count of active DDSs files in memory.
 8376
 8377@ingroup Rendering
 8378*/
 8379int getActiveDDSFiles();
 8380/*!
 8381@brief Returns image info in the following format: width TAB height TAB bytesPerPixel TAB format. It will return an empty string if the file is not found.
 8382
 8383@ingroup Rendering
 8384*/
 8385String getBitmapInfo( string filename );
 8386/*!
 8387@brief Begins a video capture session.
 8388
 8389@see stopVideoCapture
 8390@ingroup Rendering
 8391*/
 8392void startVideoCapture( GuiCanvas  canvas, string filename, string encoder="THEORA", float framerate=30.0f, Point2I resolution=Point2I::Zero );
 8393/*!
 8394@brief Stops the video capture session.
 8395
 8396@see startVideoCapture
 8397@ingroup Rendering
 8398*/
 8399void stopVideoCapture();
 8400/*!
 8401@brief Load a journal file and capture it video.
 8402
 8403@ingroup Rendering
 8404*/
 8405void playJournalToVideo( string journalFile, string videoFile=nullAsType<const char*>(), string encoder="THEORA", float framerate=30.0f, Point2I resolution=Point2I::Zero );
 8406/*!
 8407@brief Populate the font cache for the specified font with characters from the specified string.
 8408
 8409@param faceName The name of the font face.
 8410@param fontSize The size of the font in pixels.
 8411@param string The string to populate.
 8412@ingroup Font
 8413*/
 8414void populateFontCacheString( string faceName, int fontSize, string string );
 8415/*!
 8416@brief Populate the font cache for the specified font with Unicode code points in the specified range.
 8417
 8418@param faceName The name of the font face.
 8419@param fontSize The size of the font in pixels.
 8420@param rangeStart The start Unicode point.
 8421@param rangeEnd The end Unicode point.
 8422@note We only support BMP-0, so code points range from 0 to 65535.
 8423@ingroup Font
 8424*/
 8425void populateFontCacheRange( string faceName, int fontSize, uint rangeStart, uint rangeEnd );
 8426/*!
 8427@brief Dumps to the console a full description of all cached fonts, along with info on the codepoints each contains.
 8428
 8429@ingroup Font
 8430*/
 8431void dumpFontCacheStatus();
 8432/*!
 8433@brief Force all cached fonts to serialize themselves to the cache.
 8434
 8435@ingroup Font
 8436*/
 8437void writeFontCache();
 8438/*!
 8439@brief Populate the font cache for all fonts with characters from the specified string.
 8440
 8441@ingroup Font
 8442*/
 8443void populateAllFontCacheString( string string );
 8444/*!
 8445@brief Populate the font cache for all fonts with Unicode code points in the specified range.
 8446
 8447@param rangeStart The start Unicode point.
 8448@param rangeEnd The end Unicode point.
 8449@note We only support BMP-0, so code points range from 0 to 65535.
 8450@ingroup Font
 8451*/
 8452void populateAllFontCacheRange( uint rangeStart, uint rangeEnd );
 8453/*!
 8454@brief Export specified font to the specified filename as a PNG. The image can then be processed in Photoshop or another tool and reimported using importCachedFont. Characters in the font are exported as one long strip.
 8455
 8456@param faceName The name of the font face.
 8457@param fontSize The size of the font in pixels.
 8458@param fileName The file name and path for the output PNG.
 8459@param padding The padding between characters.
 8460@param kerning The kerning between characters.
 8461@ingroup Font
 8462*/
 8463void exportCachedFont( string faceName, int fontSize, string fileName, int padding, int kerning );
 8464/*!
 8465@brief Import an image strip from exportCachedFont. Call with the same parameters you called exportCachedFont.
 8466
 8467@param faceName The name of the font face.
 8468@param fontSize The size of the font in pixels.
 8469@param fileName The file name and path for the input PNG.
 8470@param padding The padding between characters.
 8471@param kerning The kerning between characters.
 8472@ingroup Font
 8473*/
 8474void importCachedFont( string faceName, int fontSize, string fileName, int padding, int kerning );
 8475/*!
 8476@brief Copy the specified old font to a new name. The new copy will not have a platform font backing it, and so will never have characters added to it. But this is useful for making copies of fonts to add postprocessing effects to via exportCachedFont.
 8477
 8478@param oldFontName The name of the font face to copy.
 8479@param oldFontSize The size of the font to copy.
 8480@param newFontName The name of the new font face.
 8481@ingroup Font
 8482*/
 8483void duplicateCachedFont( string oldFontName, int oldFontSize, string newFontName );
 8484/*!
 8485@brief Returns a tab-seperated string of the detected devices across all adapters.
 8486
 8487@ingroup GFX
 8488*/
 8489String getDisplayDeviceList();
 8490/*!
 8491@brief Returns a list of the unflagged GFX resources. See flagCurrentGFXResources for usage details.
 8492
 8493@ingroup GFX
 8494@see flagCurrentGFXResources, clearGFXResourceFlags, describeGFXResources*/
 8495void listGFXResources( bool unflaggedOnly=false );
 8496/*!
 8497@brief Flags all currently allocated GFX resources.
 8498Used for resource allocation and leak tracking by flagging current resources then dumping a list of unflagged resources at some later point in execution.
 8499@ingroup GFX
 8500@see listGFXResources, clearGFXResourceFlags, describeGFXResources*/
 8501void flagCurrentGFXResources();
 8502/*!
 8503@brief Clears the flagged state on all allocated GFX resources. See flagCurrentGFXResources for usage details.
 8504
 8505@ingroup GFX
 8506@see flagCurrentGFXResources, listGFXResources, describeGFXResources*/
 8507void clearGFXResourceFlags();
 8508/*!
 8509@brief Dumps a description of GFX resources to a file or the console.
 8510@param resourceTypes A space seperated list of resource types or an empty string for all resources.
 8511@param filePath A file to dump the list to or an empty string to write to the console.
 8512@param unflaggedOnly If true only unflagged resources are dumped. See flagCurrentGFXResources.
 8513@note The resource types can be one or more of the following:
 8514
 8515  - texture
 8516  - texture target
 8517  - window target
 8518  - vertex buffers
 8519  - primitive buffers
 8520  - fences
 8521  - cubemaps
 8522  - shaders
 8523  - stateblocks
 8524
 8525@ingroup GFX*/
 8526void describeGFXResources( string resourceTypes, string filePath, bool unflaggedOnly=false );
 8527/*!
 8528@brief Dumps a description of all state blocks.
 8529
 8530@param filePath A file to dump the state blocks to or an empty string to write to the console.
 8531@ingroup GFX
 8532*/
 8533void describeGFXStateBlocks( string filePath );
 8534/*!
 8535@brief Returns the pixel shader version for the active device.
 8536
 8537@ingroup GFX
 8538*/
 8539float getPixelShaderVersion();
 8540/*!
 8541@brief Sets the pixel shader version for the active device.
 8542This can be used to force a lower pixel shader version than is supported by the device for testing or performance optimization.
 8543@param version The floating point shader version number.
 8544@note This will only affect shaders/materials created after the call and should be used before the game begins.
 8545@see $pref::Video::forcedPixVersion
 8546@ingroup GFX*/
 8547void setPixelShaderVersion( float version );
 8548/*!
 8549@brief Get the string describing the active GFX device.
 8550
 8551@ingroup GFX
 8552*/
 8553string getDisplayDeviceInformation();
 8554/*!
 8555@brief Get the string describing the active GFX device type.
 8556
 8557@ingroup GFX
 8558*/
 8559GFXAdapterType getDisplayDeviceType();
 8560/*!
 8561@brief Returns the best texture format for storage of HDR data for the active device.
 8562
 8563@ingroup GFX
 8564*/
 8565GFXFormat getBestHDRFormat();
 8566/*!
 8567@brief forces the gbuffer to be reinitialized in cases of improper/lack of buffer clears.
 8568
 8569
 8570@ingroup UNDOCUMENTED
 8571*/
 8572void ResetGFX();
 8573/*!
 8574@brief Returns the width, height, and bitdepth of the screen/desktop.
 8575
 8576
 8577@ingroup GFX*/
 8578Point3F getDesktopResolution();
 8579/*!
 8580@brief Adds a global shader macro which will be merged with the script defined macros on every shader.  The macro will replace the value of an existing macro of the same name.  For the new macro to take effect all the shaders in the system need to be reloaded.
 8581
 8582@see resetLightManager, removeGlobalShaderMacro
 8583@ingroup Rendering
 8584*/
 8585void addGlobalShaderMacro( string name, string value=nullAsType<const char*>() );
 8586/*!
 8587@brief Removes an existing global macro by name.
 8588
 8589@see addGlobalShaderMacro
 8590@ingroup Rendering
 8591*/
 8592void removeGlobalShaderMacro( string name );
 8593/*!
 8594@brief File1,file2,file3,file4,[chanels for r g b and a locations],saveAs
 8595
 8596
 8597@ingroup UNDOCUMENTED
 8598*/
 8599void saveCompositeTexture( string pathR="", string pathG="", string pathB="", string pathA="", string inputKeyString="", string saveAs="" );
 8600/*!
 8601@brief Releases all textures and resurrects the texture manager.
 8602
 8603@ingroup GFX
 8604*/
 8605void flushTextureCache();
 8606/*!
 8607@brief Release the unused pooled textures in texture manager freeing up video memory.
 8608
 8609@ingroup GFX
 8610*/
 8611void cleanupTexturePool();
 8612/*!
 8613@brief Reload all the textures from disk.
 8614
 8615@ingroup GFX
 8616*/
 8617void reloadTextures();
 8618/*!
 8619@brief Dumps a list of all active texture objects to the console.
 8620
 8621@note This function is only available in debug builds.
 8622@ingroup GFX
 8623*/
 8624void dumpTextureObjects();
 8625/*!
 8626@brief Returns a list of texture profiles in the format: ProfileName TextureCount TextureMB
 8627
 8628@ingroup GFX
 8629*/
 8630String getTextureProfileStats();
 8631/*!
 8632@brief Takes a screenshot with optional tiling to produce huge screenshots.
 8633
 8634@param file The output image file path.
 8635@param format Either JPEG or PNG.
 8636@param tileCount If greater than 1 will tile the current screen size to take a large format screenshot.
 8637@param tileOverlap The amount of horizontal and vertical overlap between the tiles used to remove tile edge artifacts from post effects.
 8638@ingroup GFX
 8639*/
 8640void screenShot( string file, string format, uint tileCount=1, float tileOverlap=0 );
 8641/*!
 8642@brief Strip TorqueML control characters from the specified string, returning a 'clean' version.
 8643
 8644@param inString String to strip TorqueML control characters from.
 8645@tsexample
 8646// Define the string to strip TorqueML control characters from
 8647%string = "<font:Arial:24>How Now <color:c43c12>Brown <color:000000>Cow";
 8648
 8649// Request the stripped version of the string
 8650%strippedString = StripMLControlChars(%string);
 8651@endtsexample
 8652
 8653@return Version of the inputted string with all TorqueML characters removed.
 8654
 8655@see References
 8656
 8657@ingroup GuiCore*/
 8658string StripMLControlChars( string inString );
 8659/*!
 8660@brief Used to exclude/prevent all other instances using the same identifier specified
 8661
 8662@note Not used on OSX, Xbox, or in Win debug builds
 8663
 8664@param appIdentifier Name of the app set up for exclusive use.
 8665@return False if another app is running that specified the same appIdentifier
 8666
 8667@ingroup Platform
 8668@ingroup GuiCore*/
 8669bool excludeOtherInstance( string appIdentifer );
 8670/*! UNDOCUMENTED!
 8671@ingroup UNDOCUMENTED
 8672 */
 8673String getNamedTargetList();
 8674/*!
 8675@brief Flushes all procedural shaders and re-initializes all active material instances.
 8676
 8677@ingroup Materials*/
 8678void reInitMaterials();
 8679/*!
 8680@brief Maps the given texture to the given material.
 8681
 8682Generates a console warning before overwriting.
 8683
 8684Material maps are used by terrain and interiors for triggering effects when an object moves onto a terrain block or interior surface using the associated texture.
 8685
 8686@ingroup Materials*/
 8687void addMaterialMapping( string texName, string matName );
 8688/*!
 8689@brief Returns the name of the material mapped to this texture.
 8690
 8691If no materials are found, an empty string is returned.
 8692
 8693@param texName Name of the texture
 8694
 8695@ingroup Materials*/
 8696string getMaterialMapping( string texName );
 8697/*!
 8698@brief Dumps a formatted list of currently allocated material instances to the console.
 8699
 8700@ingroup Materials*/
 8701void dumpMaterialInstances();
 8702/*!
 8703@brief Dumps a formatted list of currently allocated material instances to the console.
 8704
 8705@ingroup Materials*/
 8706void getMaterialInstances( BaseMaterialDefinition target=nullAsType<BaseMaterialDefinition*>(), GuiTreeViewCtrl tree=nullAsType<GuiTreeViewCtrl*>() );
 8707/*!
 8708@brief Finds and activates the named light manager.
 8709
 8710@return Returns true if the light manager is found and activated.
 8711@ingroup Lighting
 8712*/
 8713bool setLightManager( string name );
 8714/*!
 8715@brief Will generate static lighting for the scene if supported by the active light manager.
 8716
 8717
 8718If mode is "forceAlways", the lightmaps will be regenerated regardless of whether lighting cache files can be written to. If mode is "forceWritable", then the lightmaps will be regenerated only if the lighting cache files can be written.
 8719@param completeCallbackFn The name of the function to execute when the lighting is complete.
 8720@param mode One of "forceAlways",  "forceWritable" or "loadOnly".
 8721@return Returns true if the scene lighting process was started.
 8722@ingroup Lighting
 8723*/
 8724bool lightScene( string completeCallbackFn=nullAsType<const char*>(), string mode=nullAsType<const char*>() );
 8725/*!
 8726@brief Returns a tab seperated list of light manager names.
 8727
 8728@ingroup Lighting
 8729*/
 8730String getLightManagerNames();
 8731/*!
 8732@brief Returns the active light manager name.
 8733
 8734@ingroup Lighting
 8735*/
 8736string getActiveLightManager();
 8737/*!
 8738@brief Deactivates and then activates the currently active light manager.This causes most shaders to be regenerated and is often used when global rendering changes have occured.
 8739@ingroup Lighting*/
 8740void resetLightManager();
 8741/*!
 8742@brief string sShadowSystemName
 8743
 8744
 8745@ingroup UNDOCUMENTED
 8746*/
 8747bool setShadowManager( string sShadowSystemName="" );
 8748/*! UNDOCUMENTED!
 8749@ingroup UNDOCUMENTED
 8750 */
 8751void clearServerPaths();
 8752/*! UNDOCUMENTED!
 8753@ingroup UNDOCUMENTED
 8754 */
 8755void clearClientPaths();
 8756/*!
 8757@brief Set the reflection texture format.
 8758
 8759@ingroup GFX
 8760*/
 8761void setReflectFormat( GFXFormat format );
 8762/*!
 8763@brief See if any objects of the given types are present in box of given extent.
 8764
 8765@note Extent parameter is last since only one radius is often needed.  If one radius is provided, the yRadius and zRadius are assumed to be the same.  Unfortunately, if you need to use the client container, you'll need to set all of the radius parameters.  Fortunately, this function is mostly used on the server.
 8766@param  mask   Indicates the type of objects we are checking against.
 8767@param  center Center of box.
 8768@param  xRadius Search radius in the x-axis. See note above.
 8769@param  yRadius Search radius in the y-axis. See note above.
 8770@param  zRadius Search radius in the z-axis. See note above.
 8771@param useClientContainer Optionally indicates the search should be within the client container.
 8772@return true if the box is empty, false if any object is found.
 8773@ingroup Game*/
 8774bool containerBoxEmpty( uint mask, Point3F center, float xRadius, float yRadius=-1, float zRadius=-1, bool useClientContainer=false );
 8775/*!
 8776@brief Start a search for items at the given position and within the given radius, filtering by mask.
 8777
 8778@param pos Center position for the search
 8779@param radius Search radius
 8780@param mask Bitmask of object types to include in the search
 8781@param useClientContainer Optionally indicates the search should be within the client container.
 8782@see containerSearchNext
 8783@ingroup Game*/
 8784void initContainerRadiusSearch( Point3F pos, float radius, uint mask, bool useClientContainer=false );
 8785/*!
 8786@brief Start a search for all items of the types specified by the bitset mask.
 8787
 8788@param mask Bitmask of object types to include in the search
 8789@param useClientContainer Optionally indicates the search should be within the client container.
 8790@see containerSearchNext
 8791@ingroup Game*/
 8792void initContainerTypeSearch( uint mask, bool useClientContainer=false );
 8793/*!
 8794@brief Get next item from a search started with initContainerRadiusSearch() or initContainerTypeSearch().
 8795
 8796@param useClientContainer Optionally indicates the search should be within the client container.
 8797@return the next object found in the search, or null if no more
 8798@tsexample
 8799// print the names of all nearby ShapeBase derived objects
 8800%position = %obj.getPosition;
 8801%radius = 20;
 8802%mask = $TypeMasks::ShapeBaseObjectType;
 8803initContainerRadiusSearch( %position, %radius, %mask );
 8804while ( (%targetObject = containerSearchNext()) != 0 )
 8805{
 8806   echo( "Found: " @ %targetObject.getName() );
 8807}
 8808@endtsexample
 8809@see initContainerRadiusSearch()
 8810@see initContainerTypeSearch()
 8811@ingroup Game*/
 8812SceneObject containerSearchNext( bool useClientContainer=false );
 8813/*!
 8814@brief Get distance of the center of the current item from the center of the current initContainerRadiusSearch.
 8815
 8816@param useClientContainer Optionally indicates the search should be within the client container.
 8817@return distance from the center of the current object to the center of the search
 8818@see containerSearchNext
 8819@ingroup Game*/
 8820float containerSearchCurrDist( bool useClientContainer=false );
 8821/*!
 8822@brief Get the distance of the closest point of the current item from the center of the current initContainerRadiusSearch.
 8823
 8824@param useClientContainer Optionally indicates the search should be within the client container.
 8825@return distance from the closest point of the current object to the center of the search
 8826@see containerSearchNext
 8827@ingroup Game*/
 8828float containerSearchCurrRadiusDist( bool useClientContainer=false );
 8829/*!
 8830@brief Cast a ray from start to end, checking for collision against items matching mask.
 8831
 8832If pExempt is specified, then it is temporarily excluded from collision checks (For instance, you might want to exclude the player if said player was firing a weapon.)
 8833@param start An XYZ vector containing the tail position of the ray.
 8834@param end An XYZ vector containing the head position of the ray
 8835@param mask A bitmask corresponding to the type of objects to check for
 8836@param pExempt An optional ID for a single object that ignored for this raycast
 8837@param useClientContainer Optionally indicates the search should be within the client container.
 8838@returns A string containing either null, if nothing was struck, or these fields:
 8839<ul><li>The ID of the object that was struck.</li><li>The x, y, z position that it was struck.</li><li>The x, y, z of the normal of the face that was struck.</li><li>The distance between the start point and the position we hit.</li></ul>@ingroup Game*/
 8840string containerRayCast( Point3F start, Point3F end, uint mask, SceneObject  pExempt=nullAsType<SceneObject*>(), bool useClientContainer=false );
 8841/*!
 8842@brief Cast a ray from start to end, checking for collision against items matching mask.
 8843
 8844If pExempt is specified, then it is temporarily excluded from collision checks (For instance, you might want to exclude the player if said player was firing a weapon.)
 8845@param start An XYZ vector containing the tail position of the ray.
 8846@param end An XYZ vector containing the head position of the ray
 8847@param mask A bitmask corresponding to the type of objects to check for
 8848@param pExempt An optional ID for a single object that ignored for this raycast
 8849@param useClientContainer Optionally indicates the search should be within the client container.
 8850@returns A string containing either null, if nothing was struck, or these fields:
 8851<ul><li>The ID of the object that was struck.</li><li>The x, y, z position that it was struck.</li><li>The x, y, z of the normal of the face that was struck.</li><li>The distance between the start point and the position we hit.</li></ul>@ingroup Game*/
 8852string materialRayCast( Point3F start, Point3F end, uint mask, SceneObject pExempt=nullAsType<SceneObject*>(), bool useClientContainer=false );
 8853/*!
 8854@brief Dump the current zoning states of all zone spaces in the scene to the console.
 8855
 8856
 8857@param updateFirst If true, zoning states are brought up to date first; if false, the zoning states are dumped as is.
 8858
 8859@note Only valid on the client.
 8860@ingroup Game*/
 8861void sceneDumpZoneStates( bool updateFirst=true );
 8862/*!
 8863@brief Return the SceneObject that contains the given zone.
 8864
 8865
 8866@param zoneId ID of zone.
 8867@return A SceneObject or NULL if the given @a zoneId is invalid.
 8868
 8869@note Only valid on the client.
 8870@ingroup Game*/
 8871SceneObject sceneGetZoneOwner( uint zoneId );
 8872/*!
 8873@brief Load all Path information from the mission.
 8874
 8875This function is usually called from the loadMissionStage2() server-side function after the mission file has loaded.  Internally it places all Paths into the server's PathManager.  From this point the Paths are ready for transmission to the clients.
 8876
 8877@tsexample
 8878// Inform the engine to load all Path information from the mission.
 8879pathOnMissionLoadDone();
 8880
 8881@endtsexample
 8882@see NetConnection::transmitPaths()
 8883@see NetConnection::clearPaths()
 8884@see Path
 8885@ingroup Networking*/
 8886void pathOnMissionLoadDone();
 8887/*!
 8888@brief Resizes the rendertargets of the Volumetric Fog object.
 8889@params new_quality new quality for the rendertargets 1 = full size, 2 = halfsize, 3 = 1/3, 4 = 1/4 ...
 8890@ingroup UNDOCUMENTED
 8891*/
 8892int SetFogVolumeQuality( uint new_quality );
 8893/*!
 8894@brief tsUpdateImposterImages( bool forceupdate )
 8895
 8896
 8897@ingroup UNDOCUMENTED
 8898*/
 8899void tsUpdateImposterImages( bool forceUpdate=false );
 8900/*!
 8901@brief Creates a 64x64 normal map texture filled with noise. The texture is saved to randNormTex.png in the location of the game executable.
 8902
 8903
 8904@ingroup GFX*/
 8905void dumpRandomNormalMap();
 8906/*! UNDOCUMENTED!
 8907@ingroup UNDOCUMENTED
 8908 */
 8909void dumpActivePostFX();
 8910/*!
 8911@brief Get the root Scene object that is loaded.
 8912
 8913@return The id of the Root Scene. Will be 0 if no root scene is loaded
 8914@ingroup UNDOCUMENTED
 8915*/
 8916Scene getScene( uint sceneId=0 );
 8917/*!
 8918@brief Get the number of active Scene objects that are loaded.
 8919
 8920@return The number of active scenes
 8921@ingroup UNDOCUMENTED
 8922*/
 8923int getSceneCount();
 8924/*!
 8925@brief Get the root Scene object that is loaded.
 8926
 8927@return The id of the Root Scene. Will be 0 if no root scene is loaded
 8928@ingroup UNDOCUMENTED
 8929*/
 8930int getRootScene();
 8931/*!
 8932@brief 'playerName'[, 'AIClassType'] );
 8933
 8934
 8935@ingroup UNDOCUMENTED
 8936*/
 8937int aiAddPlayer( string name, string ns="" );
 8938/*!
 8939@brief Creates a new AIConnection, and passes arguments to its onConnect script callback.
 8940
 8941@returns The newly created AIConnection
 8942@see GameConnection for parameter information
 8943@ingroup AI*/
 8944int aiConnect(...);
 8945/*!
 8946@brief Find objects matching the bitmask type within a box centered at point, with extents x, y, z.
 8947
 8948@returns The first object found, or an empty string if nothing was found.  Thereafter, you can get more results using containerFindNext().@see containerFindNext
 8949@ingroup Game*/
 8950string containerFindFirst( uint typeMask, Point3F origin, Point3F size );
 8951/*!
 8952@brief Get more results from a previous call to containerFindFirst().
 8953
 8954@note You must call containerFindFirst() to begin the search.
 8955@returns The next object found, or an empty string if nothing else was found.
 8956@see containerFindFirst()
 8957@ingroup Game*/
 8958string containerFindNext();
 8959/*!
 8960@brief Set the default FOV for a camera.
 8961@param defaultFOV The default field of view in degrees
 8962@ingroup CameraSystem*/
 8963void setDefaultFov( float defaultFOV );
 8964/*!
 8965@brief Set the zoom speed of the camera.
 8966This affects how quickly the camera changes from one field of view to another.
 8967@param speed The camera's zoom speed in ms per 90deg FOV change
 8968@ingroup CameraSystem*/
 8969void setZoomSpeed( int speed );
 8970/*!
 8971@brief Set the FOV of the camera.
 8972@param FOV The camera's new FOV in degrees
 8973@ingroup CameraSystem*/
 8974void setFov( float FOV );
 8975/*!
 8976@brief Prevents mouse movement from being processed
 8977
 8978In the source, whenever a mouse move event occurs GameTSCtrl::onMouseMove() is called. Whenever snapToggle() is called, it will flag a variable that can prevent this from happening: gSnapLine. This variable is not exposed to script, so you need to call this function to trigger it.
 8979
 8980@tsexample
 8981// Snapping is off by default, so we will toggle
 8982// it on first:
 8983PlayGui.snapToggle();
 8984
 8985// Mouse movement should be disabled
 8986// Let's turn it back on
 8987PlayGui.snapToggle();
 8988@endtsexample
 8989
 8990@ingroup GuiGame*/
 8991void snapToggle();
 8992/*!
 8993@brief Get the MissionArea object, if any.
 8994
 8995
 8996@ingroup enviroMisc
 8997
 8998*/
 8999MissionArea getMissionAreaServerObject();
 9000/*!
 9001@brief Calculates how much an explosion effects a specific object.
 9002
 9003Use this to determine how much damage to apply to objects based on their distance from the explosion's center point, and whether the explosion is blocked by other objects.
 9004
 9005@param pos Center position of the explosion.
 9006@param id Id of the object of which to check coverage.
 9007@param covMask Mask of object types that may block the explosion.
 9008@return Coverage value from 0 (not affected by the explosion) to 1 (fully affected)
 9009
 9010@tsexample
 9011// Get the position of the explosion.
 9012%position = %explosion.getPosition();
 9013
 9014// Set a list of TypeMasks (defined in gameFunctioncs.cpp), seperated by the | character.
 9015%TypeMasks = $TypeMasks::StaticObjectType | $TypeMasks::ItemObjectType
 9016
 9017// Acquire the damage value from 0.0f - 1.0f.
 9018%coverage = calcExplosionCoverage( %position, %sceneObject, %TypeMasks );
 9019
 9020// Apply damage to object
 9021%sceneObject.applyDamage( %coverage * 20 );
 9022@endtsexample
 9023@ingroup FX*/
 9024float calcExplosionCoverage( Point3F pos, int id, uint covMask );
 9025/*!
 9026@brief Activates the foliage replicator.
 9027
 9028@tsexample
 9029// Call the function
 9030StartFoliageReplication();
 9031@endtsexample
 9032@ingroup Foliage*/
 9033void StartFoliageReplication();
 9034/*!
 9035@brief Activates the shape replicator.
 9036
 9037@tsexample
 9038// Call the function
 9039StartClientReplication()
 9040@endtsexample
 9041@ingroup Foliage*/
 9042void StartClientReplication();
 9043/*!
 9044physicsPluginPresent()@brief Returns true if a physics plugin exists and is initialized.
 9045
 9046@ingroup Physics*/
 9047bool physicsPluginPresent();
 9048/*!
 9049@brief physicsInit( [string library] )
 9050
 9051
 9052@ingroup UNDOCUMENTED
 9053*/
 9054bool physicsInit( string library="default" );
 9055/*!
 9056@brief physicsDestroy()
 9057
 9058
 9059@ingroup UNDOCUMENTED
 9060*/
 9061void physicsDestroy();
 9062/*!
 9063@brief physicsInitWorld( String worldName )
 9064
 9065
 9066@ingroup UNDOCUMENTED
 9067*/
 9068bool physicsInitWorld( string worldName );
 9069/*!
 9070@brief physicsDestroyWorld( String worldName )
 9071
 9072
 9073@ingroup UNDOCUMENTED
 9074*/
 9075void physicsDestroyWorld( string worldName );
 9076/*!
 9077@brief physicsStartSimulation( String worldName )
 9078
 9079
 9080@ingroup UNDOCUMENTED
 9081*/
 9082void physicsStartSimulation( string worldName );
 9083/*!
 9084@brief physicsStopSimulation( String worldName )
 9085
 9086
 9087@ingroup UNDOCUMENTED
 9088*/
 9089void physicsStopSimulation( string worldName );
 9090/*!
 9091@brief physicsStopSimulation( String worldName )
 9092
 9093
 9094@ingroup UNDOCUMENTED
 9095*/
 9096bool physicsSimulationEnabled();
 9097/*!
 9098@brief physicsSetTimeScale( F32 scale )
 9099
 9100
 9101@ingroup UNDOCUMENTED
 9102*/
 9103void physicsSetTimeScale( float scale );
 9104/*!
 9105@brief physicsGetTimeScale()
 9106
 9107
 9108@ingroup UNDOCUMENTED
 9109*/
 9110float physicsGetTimeScale();
 9111/*!
 9112@brief physicsStoreState()
 9113
 9114
 9115@ingroup UNDOCUMENTED
 9116*/
 9117void physicsStoreState();
 9118/*!
 9119@brief physicsRestoreState()
 9120
 9121
 9122@ingroup UNDOCUMENTED
 9123*/
 9124void physicsRestoreState();
 9125/*!
 9126@brief physicsDebugDraw( bool enable )
 9127
 9128
 9129@ingroup UNDOCUMENTED
 9130*/
 9131void physicsDebugDraw( bool enable );
 9132/*!
 9133@brief Saves the decals for the active mission in the entered filename.
 9134
 9135@param decalSaveFile Filename to save the decals to.
 9136@tsexample
 9137// Set the filename to save the decals in. If no filename is set, then the
 9138// decals will default to <activeMissionName>.mis.decals
 9139%fileName = "./missionDecals.mis.decals";
 9140// Inform the decal manager to save the decals for the active mission.
 9141decalManagerSave( %fileName );
 9142@endtsexample
 9143@ingroup Decals*/
 9144void decalManagerSave( String decalSaveFile="" );
 9145/*!
 9146@brief Clears existing decals and replaces them with decals loaded from the specified file.
 9147
 9148@param fileName Filename to load the decals from.
 9149@return True if the decal manager was able to load the requested file, false if it could not.
 9150@tsexample
 9151// Set the filename to load the decals from.
 9152%fileName = "./missionDecals.mis.decals";
 9153// Inform the decal manager to load the decals from the entered filename.
 9154decalManagerLoad( %fileName );
 9155@endtsexample
 9156@ingroup Decals*/
 9157bool decalManagerLoad( string fileName );
 9158/*!
 9159@brief Returns whether the decal manager has unsaved modifications.
 9160
 9161@return True if the decal manager has unsaved modifications, false if everything has been saved.
 9162@tsexample
 9163// Ask the decal manager if it has unsaved modifications.
 9164%hasUnsavedModifications = decalManagerDirty();
 9165@endtsexample
 9166@ingroup Decals*/
 9167bool decalManagerDirty();
 9168/*!
 9169@brief Removes all decals currently loaded in the decal manager.
 9170
 9171@tsexample
 9172// Tell the decal manager to remove all existing decals.
 9173decalManagerClear();
 9174@endtsexample
 9175@ingroup Decals*/
 9176void decalManagerClear();
 9177/*!
 9178@brief Adds a new decal to the decal manager.
 9179
 9180@param position World position for the decal.
 9181@param normal Decal normal vector (if the decal was a tire lying flat on a surface, this is the vector pointing in the direction of the axle).
 9182@param rot Angle (in radians) to rotate this decal around its normal vector.
 9183@param scale Scale factor applied to the decal.
 9184@param decalData DecalData datablock to use for the new decal.
 9185@param isImmortal Whether or not this decal is immortal. If immortal, it does not expire automatically and must be removed explicitly.
 9186@return Returns the ID of the new Decal object or -1 on failure.
 9187@tsexample
 9188// Specify the decal position
 9189%position = "1.0 1.0 1.0";
 9190
 9191// Specify the up vector
 9192%normal = "0.0 0.0 1.0";
 9193
 9194// Add the new decal.
 9195%decalObj = decalManagerAddDecal( %position, %normal, 0.5, 0.35, ScorchBigDecal, false );
 9196@endtsexample
 9197@ingroup Decals*/
 9198int decalManagerAddDecal( Point3F position, Point3F normal, float rot, float scale, DecalData decalData, bool isImmortal=false );
 9199/*!
 9200@brief Remove specified decal from the scene.
 9201
 9202@param decalID ID of the decal to remove.
 9203@return Returns true if successful, false if decal ID not found.
 9204@tsexample
 9205// Specify a decal ID to be removed
 9206%decalID = 1;
 9207
 9208// Tell the decal manager to remove the specified decal ID.
 9209decalManagerRemoveDecal( %decalId )
 9210@endtsexample
 9211@ingroup Decals*/
 9212bool decalManagerRemoveDecal( int decalID );
 9213/*!
 9214@brief Edit specified decal of the decal manager.
 9215
 9216@param decalID ID of the decal to edit.
 9217@param pos World position for the decal.
 9218@param normal Decal normal vector (if the decal was a tire lying flat on a surface, this is the vector pointing in the direction of the axle).
 9219@param rotAroundNormal Angle (in radians) to rotate this decal around its normal vector.
 9220@param decalScale Scale factor applied to the decal.
 9221@return Returns true if successful, false if decalID not found.
 9222
 9223@ingroup UNDOCUMENTED
 9224*/
 9225bool decalManagerEditDecal( int decalID, Point3F pos, Point3F normal, float rotAroundNormal, float decalScale );
 9226/*! UNDOCUMENTED!
 9227@ingroup UNDOCUMENTED
 9228 */
 9229void resetDatablockCache();
 9230/*! UNDOCUMENTED!
 9231@ingroup UNDOCUMENTED
 9232 */
 9233bool isDatablockCacheSaved();
 9234/*! UNDOCUMENTED!
 9235@ingroup UNDOCUMENTED
 9236 */
 9237int getDatablockCacheCRC();
 9238/*! UNDOCUMENTED!
 9239@ingroup UNDOCUMENTED
 9240 */
 9241int extractDatablockCacheCRC( string fileName );
 9242/*! UNDOCUMENTED!
 9243@ingroup UNDOCUMENTED
 9244 */
 9245void setDatablockCacheCRC( uint crc );
 9246/*!
 9247@brief Dumps all ProcessObjects in ServerProcessList and ClientProcessList to the console.
 9248
 9249
 9250@ingroup UNDOCUMENTED
 9251*/
 9252void dumpProcessList();
 9253/*!
 9254@brief Writes an object to a file using Taml.
 9255
 9256@param object The object to write.
 9257@param filename The filename to write to.
 9258@param format The file format to use.  Optional: Defaults to 'xml'.  Can be set to 'binary'.
 9259@param compressed Whether ZIP compression is used on binary formatting or not.  Optional: Defaults to 'true'.
 9260@return Whether the write was successful or not.
 9261@ingroup UNDOCUMENTED
 9262*/
 9263bool TamlWrite( SimObject simObject, string filename, string format="xml", bool compressed=true );
 9264/*!
 9265@brief Read an object from a file using Taml.
 9266
 9267@param filename The filename to read from.
 9268@param format The file format to use.  Optional: Defaults to 'xml'.  Can be set to 'binary'.
 9269@return (Object) The object read from the file or an empty string if read failed.
 9270@ingroup UNDOCUMENTED
 9271*/
 9272string TamlRead( string filename, string format="xml" );
 9273/*!
 9274@brief Generate a TAML schema file of all engine types.
 9275
 9276The schema file is specified using the console variable '$pref::T2D::TAMLSchema'.
 9277@return Whether the schema file was writtent or not.
 9278@ingroup UNDOCUMENTED
 9279*/
 9280bool GenerateTamlSchema();
 9281/*!
 9282@brief Returns a list of supported shape format extensions separated by tabs.Example output: *.dsq TAB *.dae TAB
 9283
 9284
 9285@ingroup UNDOCUMENTED
 9286*/
 9287string getFormatExtensions();
 9288/*!
 9289@brief Returns a list of supported shape formats in filter form.
 9290
 9291Example output: DSQ Files|*.dsq|COLLADA Files|*.dae|
 9292@ingroup UNDOCUMENTED
 9293*/
 9294string getFormatFilters();
 9295/*! UNDOCUMENTED!
 9296@ingroup UNDOCUMENTED
 9297 */
 9298bool isSupportedFormat( string extension );
 9299/*! UNDOCUMENTED!
 9300@ingroup UNDOCUMENTED
 9301 */
 9302string setShadowVizLight( string name="" );
 9303/*!
 9304@brief Instantiates the effectron defined by datablock.
 9305
 9306
 9307@ingroup AFX*/
 9308int startEffectron( afxEffectronData datablock=nullAsType<afxEffectronData*>(), string constraintSource=nullAsType<const char*>(), string constraintName=nullAsType<const char*>(), SimObject extra=nullAsType<SimObject*>() );
 9309/*!
 9310@brief Instantiates the magic spell defined by datablock and cast by caster.
 9311
 9312
 9313@ingroup AFX*/
 9314int castSpell( afxMagicSpellData datablock=nullAsType<afxMagicSpellData*>(), ShapeBase caster=nullAsType<ShapeBase*>(), SceneObject target=nullAsType<SceneObject*>(), SimObject extra=nullAsType<SimObject*>() );
 9315/*!
 9316@brief Instantiates a selectron.
 9317
 9318
 9319@ingroup AFX*/
 9320int startSelectron( SceneObject selectedObj=nullAsType<SceneObject*>(), unsigned int subcode=0, SimObject extra=nullAsType<SimObject*>() );
 9321/*!
 9322@brief ...
 9323
 9324
 9325@ingroup AFX*/
 9326void afxEndMissionNotify();
 9327/*!
 9328@brief ...
 9329
 9330
 9331@ingroup AFX*/
 9332string afxGetVersion();
 9333/*!
 9334@brief ...
 9335
 9336
 9337@ingroup AFX*/
 9338string afxGetEngine();
 9339/*!
 9340@brief Performs a raycast from points start to end and returns the ID of nearest intersecting object with a type found in the specified mask. Returns -1 if no object is found.
 9341
 9342
 9343@ingroup AFX*/
 9344int rolloverRayCast( Point3F start, Point3F end, uint mask );
 9345/*!
 9346@brief Get a random float number between a and b.
 9347
 9348
 9349@ingroup AFX*/
 9350float getRandomF( float a=F32_MAX, float b=F32_MAX );
 9351/*!
 9352@brief Get a random direction vector.
 9353
 9354
 9355@ingroup AFX*/
 9356Point3F getRandomDir( Point3F axis=Point3F(0.0f,0.0f,0.0f), float thetaMin=0.0f, float thetaMax=180.0f, float phiMin=0.0f, float phiMax=360.0f );
 9357/*!
 9358@brief Multiply the vector by the affine inverse of the transform.
 9359
 9360@ingroup AFX*/
 9361Point3F MatrixInverseMulVector( MatrixF xfrm, Point3F vector );
 9362/*!
 9363@brief Move the transform to the new absolute position.
 9364
 9365@ingroup AFX*/
 9366MatrixF moveTransformAbs( MatrixF xfrm, Point3F pos );
 9367/*!
 9368@brief Move the transform to the new relative position.
 9369
 9370@ingroup AFX*/
 9371MatrixF moveTransformRel( MatrixF xfrm, Point3F pos );
 9372/*!
 9373@brief Returns the current location of the free target.
 9374
 9375@ingroup AFX*/
 9376Point3F getFreeTargetPosition();
 9377/*!
 9378@brief Called before a series of datablocks are reloaded to help distinguish reloaded datablocks from already loaded ones.
 9379
 9380@ingroup AFX*/
 9381void markDataBlocks();
 9382/*!
 9383@brief Called after a series of datablocks are reloaded to trigger some important actions on the reloaded datablocks.
 9384
 9385@ingroup AFX*/
 9386void touchDataBlocks();
 9387/*!
 9388@brief Returns true if script compiler had a syntax error. Useful for detecting syntax errors after reloading a script.
 9389
 9390@ingroup AFX*/
 9391bool wasSyntaxError();
 9392/*!
 9393@brief Coverts an HSV formatted color into an RBG color.
 9394
 9395
 9396@param hue The hue of the color (0-360).
 9397@param sat The saturation of the color (0-1).
 9398@param val The value of the color (0-1).
 9399@param alpha The alpha of the color (0-1).
 9400@ingroup AFX*/
 9401string getColorFromHSV( float hue=0.0, float sat=0.0, float val=1.0, float alpha=1.0 );
 9402/*!
 9403@brief Returns color scaled by scalar (color*scalar).
 9404
 9405
 9406@param color The color to be scaled.
 9407@param scalar The amount to scale the color.
 9408@ingroup AFX*/
 9409string ColorScale( LinearColorF color, float scalar );
 9410/*!
 9411@brief Returns the lesser of the two arguments.
 9412
 9413
 9414@ingroup AFX*/
 9415float getMinF( float a, float b );
 9416/*!
 9417@brief Returns the greater of the two arguments.
 9418
 9419
 9420@ingroup AFX*/
 9421float getMaxF( float a, float b );
 9422/*!
 9423@brief Like echo(), but first argument is returned.
 9424
 9425@ingroup AFX*/
 9426string echoThru(string passthru, string text...);
 9427/*!
 9428@brief Like warn(), but first argument is returned.
 9429
 9430@ingroup AFX*/
 9431string warnThru(string passthru, string text...);
 9432/*!
 9433@brief Like error(), but first argument is returned.
 9434
 9435@ingroup AFX*/
 9436string errorThru(string passthru, string text...);
 9437/*!
 9438@brief Get the EventManager object for all NavMesh updates.
 9439@ingroup UNDOCUMENTED
 9440*/
 9441int getNavMeshEventManager();
 9442/*!
 9443@brief Update all NavMesh tiles that intersect the given object's world box.
 9444@ingroup UNDOCUMENTED
 9445*/
 9446void NavMeshUpdateAll( int objid=0, bool remove=false );
 9447/*!
 9448@brief Update all NavMesh tiles that intersect the given object's world box.
 9449@ingroup UNDOCUMENTED
 9450*/
 9451void NavMeshUpdateAroundObject( int objid=0, bool remove=false );
 9452/*!
 9453@brief Flag this object as not generating a navmesh result.
 9454@ingroup UNDOCUMENTED
 9455*/
 9456void NavMeshIgnore( int objid=0, bool _ignore=true );
 9457/*!
 9458@brief Update all tiles in a given NavMesh that intersect the given object's world box.
 9459@ingroup UNDOCUMENTED
 9460*/
 9461void NavMeshUpdateOne( int meshid=0, int objid=0, bool remove=false );
 9462/*! UNDOCUMENTED!
 9463@ingroup UNDOCUMENTED
 9464 */
 9465void ShakeCamera( float duration=0, float falloff=0, VectorF amplitude=VectorF::Zero, VectorF frequency=VectorF::Zero );
 9466/*! UNDOCUMENTED!
 9467@ingroup UNDOCUMENTED
 9468 */
 9469int getServerPathSet();
 9470/*!
 9471@brief enableWinConsole(bool);
 9472
 9473
 9474@ingroup UNDOCUMENTED
 9475*/
 9476void enableWinConsole( bool _enable );
 9477/*!
 9478@brief Install the math library with specified extensions.
 9479
 9480Possible parameters are:
 9481
 9482    - 'DETECT' Autodetect math lib settings.
 9483
 9484    - 'C' Enable the C math routines. C routines are always enabled.
 9485
 9486    - 'SSE' Enable SSE math routines.
 9487
 9488@ingroup Math*/
 9489void mathInit( ... );
 9490
 9491/*! @name Callbacks
 9492@{ */
 9493/// @}
 9494
 9495/*!
 9496@brief Base class for almost all objects involved in the simulation.
 9497
 9498@ingroup Console
 9499
 9500*/
 9501class SimObject {
 9502public:
 9503/*!
 9504@brief Dump the hierarchy of this object up to RootGroup to the console.
 9505
 9506*/
 9507void dumpGroupHierarchy();
 9508/*!
 9509@brief Test whether the given method is defined on this object.
 9510
 9511@param The name of the method.
 9512@return True if the object implements the given method.*/
 9513bool isMethod( string methodName );
 9514/*!
 9515@brief Test whether the object belongs directly or indirectly to the given group.
 9516
 9517@param group The SimGroup object.
 9518@return True if the object is a child of the given group or a child of a group that the given group is directly or indirectly a child to.*/
 9519bool isChildOfGroup( SimGroup group );
 9520/*!
 9521@brief Get the name of the class namespace assigned to this object.
 9522
 9523@return The name of the 'class' namespace.*/
 9524string getClassNamespace();
 9525/*!
 9526@brief Get the name of the superclass namespace assigned to this object.
 9527
 9528@return The name of the 'superClass' namespace.*/
 9529string getSuperClassNamespace();
 9530/*!
 9531@brief Assign a class namespace to this object.
 9532
 9533@param name The name of the 'class' namespace for this object.*/
 9534void setClassNamespace( string name );
 9535/*!
 9536@brief Assign a superclass namespace to this object.
 9537
 9538@param name The name of the 'superClass' namespace for this object.*/
 9539void setSuperClassNamespace( string name );
 9540/*!
 9541@brief Get whether the object has been marked as selected. (in editor)
 9542
 9543@return True if the object is currently selected.*/
 9544bool isSelected();
 9545/*!
 9546@brief Set whether the object has been marked as selected. (in editor)
 9547
 9548@param state True if object is to be marked selected; false if not.*/
 9549void setIsSelected( bool state=true );
 9550/*!
 9551@brief Get whether the object has been marked as expanded. (in editor)
 9552
 9553@return True if the object is marked expanded.*/
 9554bool isExpanded();
 9555/*!
 9556@brief Set whether the object has been marked as expanded. (in editor)
 9557
 9558@param state True if the object is to be marked expanded; false if not.*/
 9559void setIsExpanded( bool state=true );
 9560/*!
 9561@brief Returns the filename the object is attached to.
 9562
 9563@return The name of the file the object is associated with; usually the file the object was loaded from.*/
 9564string getFilename();
 9565/*!
 9566@brief Sets the object's file name and path
 9567
 9568@param fileName The name of the file to associate this object with.*/
 9569void setFilename( string fileName );
 9570/*!
 9571@brief Get the line number at which the object is defined in its file.
 9572
 9573
 9574@return The line number of the object's definition in script.
 9575@see getFilename()*/
 9576int getDeclarationLine();
 9577/*!
 9578@brief Copy fields from another object onto this one.  The objects must be of same type. Everything from the object will overwrite what's in this object; extra fields in this object will remain. This includes dynamic fields.
 9579
 9580@param fromObject The object from which to copy fields.*/
 9581void assignFieldsFrom( SimObject fromObject );
 9582/*!
 9583@brief Assign a persistent ID to the object if it does not already have one.
 9584
 9585*/
 9586void assignPersistentId();
 9587/*!
 9588@brief Get whether the object will be included in saves.
 9589
 9590@return True if the object will be saved; false otherwise.*/
 9591bool getCanSave();
 9592/*!
 9593@brief Set whether the object will be included in saves.
 9594
 9595@param value If true, the object will be included in saves; if false, it will be excluded.*/
 9596void setCanSave( bool value=true );
 9597/*!
 9598@brief Return true if the object is only used by the editor.
 9599
 9600@return True if this object exists only for the sake of editing.*/
 9601bool isEditorOnly();
 9602/*!
 9603@brief Set/clear the editor-only flag on this object.
 9604
 9605@param value If true, the object is marked as existing only for the editor.*/
 9606void setEditorOnly( bool value=true );
 9607/*!
 9608@brief Get whether this object may be renamed.
 9609
 9610@return True if this object can be renamed; false otherwise.*/
 9611bool isNameChangeAllowed();
 9612/*!
 9613@brief Set whether this object can be renamed from its first name.
 9614
 9615@param value If true, renaming is allowed for this object; if false, trying to change the name of the object will generate a console error.*/
 9616void setNameChangeAllowed( bool value=true );
 9617/*!
 9618@brief Create a copy of this object.
 9619
 9620@return An exact duplicate of this object.*/
 9621SimObject clone();
 9622/*!
 9623@brief Create a copy of this object and all its subobjects.
 9624
 9625@return An exact duplicate of this object and all objects it references.*/
 9626SimObject deepClone();
 9627/*!
 9628@brief Lock/unlock the object in the editor.
 9629
 9630@param value If true, the object will be locked; if false, the object will be unlocked.*/
 9631void setLocked( bool value=true );
 9632/*!
 9633@brief Hide/unhide the object.
 9634
 9635@param value If true, the object will be hidden; if false, the object will be unhidden.*/
 9636void setHidden( bool value=true );
 9637/*!
 9638@brief List the methods defined on this object.
 9639
 9640
 9641Each description is a newline-separated vector with the following elements:
 9642- Minimum number of arguments.
 9643- Maximum number of arguments.
 9644- Prototype string.
 9645- Full script file path (if script method).
 9646- Line number of method definition in script (if script method).
 9647
 9648- Documentation string (not including prototype).  This takes up the remainder of the vector.
 9649@return An ArrayObject populated with (name,description) pairs of all methods defined on the object.*/
 9650ArrayObject dumpMethods();
 9651/*!
 9652@brief Dump a description of all fields and methods defined on this object to the console.
 9653
 9654@param detailed Whether to print detailed information about members.*/
 9655void dump( bool detailed=false );
 9656/*!
 9657@brief Save out the object to the given file.
 9658
 9659@param fileName The name of the file to save to.@param selectedOnly If true, only objects marked as selected will be saved out.
 9660@param preAppendString Text which will be preprended directly to the object serialization.
 9661@param True on success, false on failure.*/
 9662bool save( string fileName, bool selectedOnly=false, string preAppendString="" );
 9663/*!
 9664@brief Set the global name of the object.
 9665
 9666@param newName The new global name to assign to the object.
 9667@note If name changing is disallowed on the object, the method will fail with a console error.*/
 9668void setName( string newName );
 9669/*!
 9670@brief Get the global name of the object.
 9671
 9672@return The global name assigned to the object.*/
 9673string getName();
 9674/*!
 9675@brief Get the name of the C++ class which the object is an instance of.
 9676
 9677@return The name of the C++ class of the object.*/
 9678string getClassName();
 9679/*!
 9680@brief Test whether the given field is defined on this object.
 9681
 9682@param fieldName The name of the field.
 9683@return True if the object implements the given field.*/
 9684bool isField( string fieldName );
 9685/*!
 9686@brief Return the value of the given field on this object.
 9687
 9688@param fieldName The name of the field.  If it includes a field index, the index is parsed out.
 9689@param index Optional parameter to specify the index of an array field separately.
 9690@return The value of the given field or "" if undefined.*/
 9691string getFieldValue( string fieldName, int index=-1 );
 9692/*!
 9693@brief Set the value of the given field on this object.
 9694
 9695@param fieldName The name of the field to assign to.  If it includes an array index, the index will be parsed out.
 9696@param value The new value to assign to the field.
 9697@param index Optional argument to specify an index for an array field.
 9698@return True.*/
 9699bool setFieldValue( string fieldName, string value, int index=-1 );
 9700/*!
 9701@brief Get the console type code of the given field.
 9702
 9703@return The numeric type code for the underlying console type of the given field.*/
 9704string getFieldType( string fieldName );
 9705/*!
 9706@brief Set the console type code for the given field.
 9707
 9708@param fieldName The name of the dynamic field to change to type for.
 9709@param type The name of the console type.
 9710@note This only works for dynamic fields.  Types of static fields cannot be changed.*/
 9711void setFieldType( string fieldName, string type );
 9712/*!
 9713@brief Dynamically call a method on an object.
 9714
 9715@param method Name of method to call.
 9716@param args Zero or more arguments for the method.
 9717@return The result of the method call.*/
 9718string call( string method, string args... );
 9719/*!
 9720@brief Set the internal name of the object.
 9721
 9722@param newInternalName The new internal name for the object.*/
 9723void setInternalName( string newInternalName );
 9724/*!
 9725@brief Get the internal name of the object.
 9726
 9727@return The internal name of the object.*/
 9728string getInternalName();
 9729/*!
 9730@brief Dump the native C++ class hierarchy of this object's C++ class to the console.
 9731
 9732*/
 9733void dumpClassHierarchy();
 9734/*!
 9735@brief Test whether this object is a member of the specified class.
 9736
 9737@param className Name of a native C++ class.
 9738@return True if this object is an instance of the given C++ class or any of its super classes.*/
 9739bool isMemberOfClass( string className );
 9740/*!
 9741@brief Test whether the namespace of this object is a direct or indirect child to the given namespace.
 9742
 9743@param name The name of a namespace.
 9744@return True if the given namespace name is within the namespace hierarchy of this object.*/
 9745bool isInNamespaceHierarchy( string name );
 9746/*!
 9747@brief Get the underlying unique numeric ID of the object.
 9748
 9749@note Object IDs are unique only during single engine runs.
 9750@return The unique numeric ID of the object.*/
 9751int getId();
 9752/*!
 9753@brief Get the group that this object is contained in.
 9754
 9755@note If not assigned to particular SimGroup, an object belongs to RootGroup.
 9756@return The SimGroup object to which the object belongs.*/
 9757SimGroup getGroup();
 9758/*!
 9759@brief Delete and remove the object.
 9760
 9761*/
 9762void delete();
 9763/*!
 9764@brief Delay an invocation of a method.
 9765
 9766@param time The number of milliseconds after which to invoke the method.  This is a soft limit.
 9767@param method The method to call.
 9768@param args The arguments with which to call the method.
 9769@return The numeric ID of the created schedule.  Can be used to cancel the call.
 9770*/
 9771int schedule( float time, string method, string args... );
 9772/*!
 9773@brief Get the number of dynamic fields defined on the object.
 9774
 9775@return The number of dynamic fields defined on the object.*/
 9776int getDynamicFieldCount();
 9777/*!
 9778@brief Get a value of a dynamic field by index.
 9779
 9780@param index The index of the dynamic field.
 9781@return The value of the dynamic field at the given index or "".*/
 9782string getDynamicField( int index );
 9783/*!
 9784@brief Get the number of static fields on the object.
 9785
 9786@return The number of static fields defined on the object.*/
 9787int getFieldCount();
 9788/*!
 9789@brief Retrieve the value of a static field by index.
 9790
 9791@param index The index of the static field.
 9792@return The value of the static field with the given index or "".*/
 9793string getField( int index );
 9794/*!
 9795@brief Return some behind-the-scenes information on the object.
 9796
 9797@return An ArrayObject filled with internal information about the object.*/
 9798ArrayObject getDebugInfo();
 9799
 9800/*! @name Callbacks
 9801@{ */
 9802/*!
 9803@brief Generic callback for when an object is edited
 9804
 9805*/
 9806void onInspectPostApply( SimObject obj );
 9807/// @}
 9808
 9809
 9810/*! @name Ungrouped
 9811@{ */
 9812/*!
 9813@brief Optional global name of this object.
 9814*/
 9815string Name;
 9816/// @}
 9817
 9818
 9819/*! @name Object
 9820@{ */
 9821/*!
 9822@brief Optional name that may be used to lookup this object within a SimSet.
 9823*/
 9824string internalName;
 9825/*!
 9826@brief Group hierarchy parent of the object.
 9827*/
 9828SimObject parentGroup;
 9829/*!
 9830@brief Script class of object.
 9831*/
 9832string class;
 9833/*!
 9834@brief Script super-class of object.
 9835*/
 9836string superClass;
 9837/*!
 9838@brief Script class of object.
 9839*/
 9840string className;
 9841/// @}
 9842
 9843
 9844/*! @name Editing
 9845@{ */
 9846/*!
 9847@brief Whether the object is visible.
 9848*/
 9849bool hidden;
 9850/*!
 9851@brief Whether the object can be edited.
 9852*/
 9853bool locked;
 9854/// @}
 9855
 9856
 9857/*! @name Persistence
 9858@{ */
 9859/*!
 9860@brief Whether the object can be saved out. If false, the object is purely transient in nature.
 9861*/
 9862bool canSave;
 9863/*!
 9864@brief True if dynamic fields (added at runtime) should be saved. Defaults to true.
 9865*/
 9866bool canSaveDynamicFields;
 9867/*!
 9868@brief The universally unique identifier for the object.
 9869*/
 9870pid persistentId;
 9871/// @}
 9872
 9873};
 9874
 9875/*!
 9876@brief ActionMaps assign platform input events to console commands.
 9877
 9878Any platform input event can be bound in a single, generic way. In theory, the game doesn't need to know if the event came from the keyboard, mouse, joystick or some other input device. This allows users of the game to map keys and actions according to their own preferences. Game action maps are arranged in a stack for processing so individual parts of the game can define specific actions. For example, when the player jumps into a vehicle it could push a vehicle action map and pop the default player action map.
 9879
 9880@section ActionMap_creation Creating an ActionMap
 9881The input system allows for the creation of multiple ActionMaps, so long as they have unique names and do not already exist. It's a simple three step process.
 9882
 98831. Check to see if the ActionMap exists
 98842. Delete it if it exists
 98853. Instantiate the ActionMap
 9886
 9887The following is an example of how to create a new ActionMap:
 9888@tsexample
 9889if ( isObject( moveMap ) )
 9890  moveMap.delete();
 9891new ActionMap(moveMap);@endtsexample
 9892
 9893
 9894@section ActionMap_binding Binding Functions
 9895Once you have created an ActionMap, you can start binding functionality to events. Currently, Torque 3D supports the following devices out of the box
 9896
 9897* Mouse
 9898
 9899* Keyboard
 9900
 9901* Joystick/Gamepad
 9902
 9903* Xbox 360 Controller
 9904
 9905The two most commonly used binding methods are bind() and bindCmd(). Both are similar in that they will bind functionality to a device and event, but different in how the event is interpreted. With bind(), you specify a device, action to bind, then a function to be called when the event happens.
 9906
 9907@tsexample
 9908// Simple function that prints to console
 9909// %val - Sent by the device letting the user know
 9910// if an input was pressed (true) or released (false)
 9911function testInput(%val)
 9912{
 9913   if(%val)
 9914    echo("Key is down");
 9915   else
 9916    echo("Key was released");
 9917}
 9918
 9919// Bind the 'K' key to the testInput function
 9920moveMap.bind(keyboard, "k", testInput);
 9921
 9922@endtsexample
 9923
 9924
 9925bindCmd is an alternative method for binding commands. This function is similar to bind(), except two functions are set to be called when the event is processed.
 9926
 9927One will be called when the event is activated (input down), while the other is activated when the event is broken (input release). When using bindCmd(), pass the functions as strings rather than the function names.
 9928
 9929@tsexample
 9930// Print to the console when the spacebar is pressed
 9931function onSpaceDown()
 9932{
 9933   echo("Space bar down!");
 9934}
 9935
 9936// Print to the console when the spacebar is released
 9937function onSpaceUp()
 9938{
 9939   echo("Space bar up!");
 9940}
 9941
 9942// Bind the commands onSpaceDown and onSpaceUp to spacebar events
 9943moveMap.bindCmd(keyboard, "space", "onSpaceDown();", "onSpaceUp();");
 9944@endtsexample
 9945
 9946@section ActionMap_switching Switching ActionMaps
 9947Let's say you want to have different ActionMaps activated based on game play situations. A classic example would be first person shooter controls and racing controls in the same game. On foot, spacebar may cause your player to jump. In a vehicle, it may cause some kind of "turbo charge". You simply need to push/pop the ActionMaps appropriately:
 9948
 9949First, create two separate ActionMaps:
 9950
 9951@tsexample
 9952// Create the two ActionMaps
 9953if ( isObject( moveMap ) )
 9954  moveMap.delete();
 9955new ActionMap(moveMap);
 9956
 9957if ( isObject( carMap ) )
 9958  carMap.delete();
 9959new ActionMap(carMap);
 9960
 9961@endtsexample
 9962
 9963Next, create the two separate functions. Both will be bound to spacebar, but not the same ActionMap:
 9964
 9965@tsexample
 9966// Print to the console the player is jumping
 9967function playerJump(%val)
 9968{
 9969   if(%val)
 9970    echo("Player jumping!");
 9971}
 9972
 9973// Print to the console the vehicle is charging
 9974function turboCharge()
 9975{
 9976   if(%val)
 9977    echo("Vehicle turbo charging!");
 9978}
 9979@endtsexample
 9980
 9981You are now ready to bind functions to your ActionMaps' devices:
 9982
 9983@tsexample
 9984// Bind the spacebar to the playerJump function
 9985// when moveMap is the active ActionMap
 9986moveMap.bind(keyboard, "space", playerJump);
 9987
 9988// Bind the spacebar to the turboCharge function
 9989// when carMap is the active ActionMap
 9990carMap.bind(keyboard, "space", turboCharge);
 9991@endtsexample
 9992Finally, you can use the push() and pop() commands on each ActionMap to toggle activation. To activate an ActionMap, use push():
 9993
 9994@tsexample
 9995// Make moveMap the active action map
 9996// You should now be able to activate playerJump with spacebar
 9997moveMap.push();
 9998@endtsexample
 9999
10000To switch ActionMaps, first pop() the old one. Then you can push() the new one:
10001
10002@tsexample
10003// Deactivate moveMap
10004moveMap.pop();
10005
10006// Activate carMap
10007carMap.push();
10008
10009@endtsexample
10010
10011
10012@ingroup Input
10013*/
10014class ActionMap : public SimObject {
10015public:
10016/*!
10017@brief Associates a function to an input event for a specified class or object.
10018
10019You must specify a device, the action to bind, a function, and an object to be called when the event happens. The function specified must be set to receive a single boolean value passed. Modifier flags may be specified to process dead zones, input inversion, and more.
10020
10021Valid modifier flags:
10022
10023 - R - Input is Ranged.
10024 - S - Input is Scaled.
10025 - I - Input is inverted.
10026 - D - Dead zone is present.
10027 - N - Input should be re-fit to a non-linear scale.
10028
10029@param device The input device, such as mouse or keyboard.
10030@param action The input event, such as space, button0, etc.
10031@param flag Modifier flag assigned during binding, letting event know there are additional parameters to consider.
10032@param deadZone [Required only when flag is set] Restricted region in which device motion will not be acknowledged.
10033@param scale [Required only when flag is set] Modifies the deadZone region.
10034@param command The function bound to the action.
10035@param object The object or class bound to the action.
10036@return True if the binding was successful, false if the device was unknown or description failed.
10037
10038@tsexample
10039// Bind the mouse's movement along the x-axis to the testInput function of the Player class
10040// DSI is flagged, meaning input is inverted, has scale and has a deadzone
10041%this.bindObj( mouse, "xaxis", "DSI", %deadZone, %scale, "testInput", %player );
10042@endtsexample
10043
10044
10045*/
10046
10047bool bindObj( string device, string action, string flag, string deadZone, string scale, string command, SimObjectID object );
10048/*!
10049@brief Associates a function to an input event for a specified class or object.
10050
10051You must specify a device, the action to bind, a function, and an object to be called when the event happens. The function specified must be set to receive a single boolean value passed.
10052
10053@param device The input device, such as mouse or keyboard.
10054@param action The input event, such as space, button0, etc.
10055@param command The function bound to the action.
10056@param object The object or class bound to the action.
10057@return True if the binding was successful, false if the device was unknown or description failed.
10058
10059@tsexample
10060moveMap.bindObj(keyboard, "numpad1", "rangeChange", %player);@endtsexample
10061
10062*/
10063
10064bool bindObj( string device, string action, string command, SimObjectID object );
10065/*!
10066@brief Associates a function and input parameters to an input event.
10067
10068When the input event is raised, the specified function will be called. Modifier flags may be specified to process dead zones, input inversion, and more.
10069
10070Valid modifier flags:
10071
10072 - R - Input is Ranged.
10073 - S - Input is Scaled.
10074 - I - Input is inverted.
10075 - D - Dead zone is present.
10076 - N - Input should be re-fit to a non-linear scale.
10077
10078@param device The input device, such as mouse or keyboard.
10079@param action The input event, such as space, button0, etc.
10080@param flag Modifier flag assigned during binding, letting event know there are additional parameters to consider. 
10081@param deadZone Restricted region in which device motion will not be acknowledged.
10082@param scale Modifies the deadZone region.
10083@param command The function bound to the action. Must take in a single argument.
10084@return True if the binding was successful, false if the device was unknown or description failed.
10085
10086@tsexample
10087// Simple function that adjusts the pitch of the camera based on the mouse's movement along the X axis.
10088function testPitch(%val)
10089{
10090   %pitchAdj = getMouseAdjustAmount(%val);
10091   $mvPitch += %pitchAdj;
10092}
10093
10094// Bind the mouse's X axis to the testPitch function
10095// DI is flagged, meaning input is inverted and has a deadzone
10096%this.bind( mouse, "xaxis", "DI", "-0.23 0.23", testPitch );
10097@endtsexample
10098
10099
10100*/
10101
10102bool bind( string device, string action, string flag, string deadZone, string scale, string command );
10103/*!
10104@brief Associates a function to an input event.
10105
10106When the input event is raised, the specified function will be called.
10107
10108@param device The input device, such as mouse or keyboard.
10109@param action The input event, such as space, button0, etc.
10110@param command The function to bind to the action. Function must have a single boolean argument.
10111@return True if the binding was successful, false if the device was unknown or description failed.
10112
10113@tsexample
10114// Simple function that prints to console
10115// %val - Sent by the device letting the user know
10116// if an input was pressed (true) or released (false)
10117function testInput(%val)
10118{
10119   if(%val)
10120    echo("Key is down");
10121   else
10122    echo("Key was released");
10123}
10124
10125// Bind the 'K' key to the testInput function
10126moveMap.bind(keyboard, k, testInput);
10127
10128@endtsexample
10129
10130
10131*/
10132
10133bool bind( string device, string action, string command );
10134/*!
10135@brief Associates a make command and optional break command to a specified input device action.
10136
10137Must include parenthesis and semicolon in the make and break command strings.
10138
10139@param device The device to bind to. Can be a keyboard, mouse, joystick or gamepad.
10140@param action The device action to bind to. The action is dependant upon the device. Specify a key for keyboards.
10141@param makeCmd The command to execute when the device/action is made.
10142@param breakCmd [optional] The command to execute when the device or action is unmade.
10143@return True the bind was successful, false if the device was unknown or description failed.
10144@tsexample
10145// Print to the console when the spacebar is pressed
10146function onSpaceDown()
10147{
10148   echo("Space bar down!");
10149}
10150
10151// Print to the console when the spacebar is released
10152function onSpaceUp()
10153{
10154   echo("Space bar up!");
10155}
10156
10157// Bind the commands onSpaceDown() and onSpaceUp() to spacebar events
10158
10159moveMap.bindCmd(keyboard, "space", "onSpaceDown();", "onSpaceUp();");
10160@endtsexample*/
10161bool bindCmd( string device, string action, string makeCmd, string breakCmd="" );
10162/*!
10163@brief actionMap.bindCmd( device, action, holdFunction, tapFunction, holdTime)
10164
10165*/
10166void bindContext( string device="", string action="", string holdFunction="", string tapFunction="", uint holdTime=0 );
10167/*!
10168@brief actionMap.bindCmd( device, action, holdFunction, returnHoldTime)
10169
10170*/
10171void bindHold( string device="", string action="", string holdFunction="", bool returnHoldTime=false );
10172/*!
10173@brief Removes the binding on an input device and action.
10174@param device The device to unbind from. Can be a keyboard, mouse, joystick or a gamepad.
10175@param action The device action to unbind from. The action is dependant upon the device. Specify a key for keyboards.
10176@return True if the unbind was successful, false if the device was unknown or description failed.
10177
10178@tsexample
10179moveMap.unbind("keyboard", "space");
10180@endtsexample*/
10181bool unbind( string device, string action );
10182/*!
10183@brief Remove any object-binding on an input device and action.
10184@param device The device to bind to.  Can be keyboard, mouse, joystick or gamepad.
10185@param action The device action to unbind from. The action is dependant upon the device. Specify a key for keyboards.
10186@param obj The object to perform unbind against.
10187@return True if the unbind was successful, false if the device was unknown or description failed.
10188@tsexample
10189moveMap.unbindObj("keyboard", "numpad1", "rangeChange", %player);@endtsexample*/
10190bool unbindObj( string device, string action, string obj );
10191/*!
10192@brief Saves the ActionMap to a file or dumps it to the console.
10193
10194@param fileName The file path to save the ActionMap to. If a filename is not specified  the ActionMap will be dumped to the console.
10195@param append Whether to write the ActionMap at the end of the file or overwrite it.
10196@tsexample
10197// Write out the actionmap into the config.cs file
10198moveMap.save( "scripts/client/config.cs" );@endtsexample*/
10199void save( string fileName=nullAsType<const char*>(), bool append=false );
10200/*!
10201@brief Push the ActionMap onto the %ActionMap stack.
10202
10203Activates an ActionMap and placees it at the top of the ActionMap stack.
10204
10205@tsexample
10206// Make moveMap the active action map
10207moveMap.push();
10208@endtsexample
10209
10210@see ActionMap*/
10211void push();
10212/*!
10213@brief Pop the ActionMap off the %ActionMap stack.
10214
10215Deactivates an %ActionMap and removes it from the @ActionMap stack.
10216@tsexample
10217// Deactivate moveMap
10218moveMap.pop();
10219@endtsexample
10220
10221@see ActionMap*/
10222void pop();
10223/*!
10224@brief Gets the ActionMap binding for the specified command.
10225
10226Use getField() on the return value to get the device and action of the binding.
10227@param command The function to search bindings for.
10228@return The binding against the specified command. Returns an empty string("") if a binding wasn't found.
10229@tsexample
10230// Find what the function "jump()" is bound to in moveMap
10231%bind = moveMap.getBinding( "jump" );
10232
10233if ( %bind !$= "" )
10234{
10235// Find out what device is used in the binding
10236  %device = getField( %bind, 0 );
10237
10238// Find out what action (such as a key) is used in the binding
10239  %action = getField( %bind, 1 );
10240}
10241@endtsexample
10242
10243@see getField*/
10244string getBinding( string command );
10245/*!
10246@brief Gets ActionMap command for the device and action.
10247
10248@param device The device that was bound. Can be a keyboard, mouse, joystick or a gamepad.
10249@param action The device action that was bound.  The action is dependant upon the device. Specify a key for keyboards.
10250@return The command against the specified device and action.
10251@tsexample
10252// Find what function is bound to a device's action
10253// In this example, "jump()" was assigned to the space key in another script
10254%command = moveMap.getCommand("keyboard", "space");
10255
10256// Should print "jump" in the console
10257echo(%command)
10258@endtsexample*/
10259string getCommand( string device, string action );
10260/*!
10261@brief Determines if the specified device and action is inverted.
10262
10263Should only be used for scrolling devices or gamepad/joystick axes.@param device The device that was bound. Can be a keyboard, mouse, joystick or a gamepad.
10264@param action The device action that was bound.  The action is dependant upon the device. Specify a key for keyboards.
10265@return True if the specified device and action is inverted.
10266@tsexample
10267%if ( moveMap.isInverted( "mouse", "xaxis"))
10268   echo("Mouse's xAxis is inverted");@endtsexample*/
10269bool isInverted( string device, string action );
10270/*!
10271@brief Get any scaling on the specified device and action.
10272
10273@param device The device that was bound. Can be keyboard, mouse, joystick or gamepad.
10274@param action The device action that was bound. The action is dependant upon the device. Specify a key for keyboards.
10275@return Any scaling applied to the specified device and action.
10276@tsexample
10277%scale = %moveMap.getScale( "gamepad", "thumbrx");
10278@endtsexample*/
10279float getScale( string device, string action );
10280/*!
10281@brief Gets the Dead zone for the specified device and action.
10282
10283@param device The device that was bound.  Can be a keyboard, mouse, joystick or a gamepad.
10284@param action The device action that was bound. The action is dependant upon the device. Specify a key for keyboards.
10285@return The dead zone for the specified device and action. Returns "0 0" if there is no dead zone or an empty string("") if the mapping was not found.
10286@tsexample
10287%deadZone = moveMap.getDeadZone( "gamepad", "thumbrx");
10288@endtsexample*/
10289string getDeadZone( string device, string action );
10290
10291/*! @name Callbacks
10292@{ */
10293/// @}
10294
10295
10296/*! @name Ungrouped
10297@{ */
10298/// @}
10299
10300
10301/*! @name Object
10302@{ */
10303/// @}
10304
10305
10306/*! @name Editing
10307@{ */
10308/// @}
10309
10310
10311/*! @name Persistence
10312@{ */
10313/// @}
10314
10315};
10316
10317/*! UNDOCUMENTED!
10318@ingroup UNDOCUMENTED
10319 */
10320class AssetManager : public SimObject {
10321public:
10322/*!
10323@brief Compile the referenced assets determined by the specified module definition.
10324
10325@param moduleDefinition The module definition specifies the asset manifest.
10326@return Whether the compilation was successful or not.
10327*/
10328bool compileReferencedAssets( string moduleDefinition="" );
10329/*!
10330@brief Add any the declared assets specified by the module definition.
10331
10332@param moduleDefinition The module definition specifies the asset manifest.
10333@return Whether adding declared assets was successful or not.
10334*/
10335bool addModuleDeclaredAssets( string moduleDefinition="" );
10336/*!
10337@brief Add the specified asset against the specified module definition.
10338
10339@param moduleDefinition The module definition that may contain declared assets.
10340@return Whether adding declared assets was successful or not.
10341*/
10342bool addDeclaredAsset( string moduleDefinition="", string assetFilePath="" );
10343/*!
10344@brief Adds a private asset object.
10345
10346@param assetObject The asset object to add as a private asset.
10347@return The allocated private asset Id.
10348*/
10349String addPrivateAsset( string assetObject="" );
10350/*!
10351@brief Remove any the declared assets specified by the module definition.
10352
10353@param moduleDefinition The module definition that may contain declared assets.
10354@return Whether removing declared assets was successful or not.
10355*/
10356bool removeDeclaredAssets( string moduleDefinition="" );
10357/*!
10358@brief Remove the specified declared asset Id.
10359
10360@param assetId The selected asset Id.
10361@return Whether removing the declared asset was successful or not.
10362*/
10363bool removeDeclaredAsset( string assetId="" );
10364/*!
10365@brief Gets the asset name from the specified asset Id.
10366
10367@param assetId The selected asset Id.
10368@return The asset name from the specified asset Id.
10369*/
10370String getAssetName( string assetId="" );
10371/*!
10372@brief Gets the asset description from the specified asset Id.
10373
10374@param assetId The selected asset Id.
10375@return The asset description from the specified asset Id.
10376*/
10377String getAssetDescription( string assetId="" );
10378/*!
10379@brief Gets the asset category from the specified asset Id.
10380
10381@param assetId The selected asset Id.
10382@return The asset category from the specified asset Id.
10383*/
10384String getAssetCategory( string assetId="" );
10385/*!
10386@brief Gets the asset type from the specified asset Id.
10387
10388@param assetId The selected asset Id.
10389@return The asset type from the specified asset Id.
10390*/
10391String getAssetType( string assetId="" );
10392/*!
10393@brief Gets the asset file-path from the specified asset Id.
10394
10395@param assetId The selected asset Id.
10396@return The asset file - path from the specified asset Id.
10397*/
10398String getAssetFilePath( string assetId="" );
10399/*!
10400@brief Gets the asset path (not including the asset file) from the specified asset Id.
10401
10402@param assetId The selected asset Id.
10403@return The asset path(not including the asset file) from the specified asset Id.
10404*/
10405String getAssetPath( string assetId="" );
10406/*!
10407@brief Gets the module definition where the the specified asset Id is located.
10408
10409@param assetId The selected asset Id.
10410@return The module definition where the the specified asset Id is located.
10411*/
10412String getAssetModule( string assetId="" );
10413/*!
10414@brief Check whether the specified asset Id is internal or not.
10415
10416@param assetId The selected asset Id.
10417@return Whether the specified asset Id is internal or not.
10418*/
10419bool isAssetInternal( string assetId="" );
10420/*!
10421@brief Check whether the specified asset Id is private or not.
10422
10423@param assetId The selected asset Id.
10424@return Whether the specified asset Id is private or not.
10425*/
10426bool isAssetPrivate( string assetId="" );
10427/*!
10428@brief Check whether the specified asset Id is auto - unload or not.
10429
10430@param assetId The selected asset Id.
10431@return Whether the specified asset Id is auto-unload or not.
10432*/
10433bool isAssetAutoUnload( string assetId="" );
10434/*!
10435@brief Check whether the specified asset Id is loaded or not.
10436
10437@param assetId The selected asset Id.
10438@return Whether the specified asset Id is loaded or not.
10439*/
10440bool isAssetLoaded( string assetId="" );
10441/*!
10442@brief Check whether the specified asset Id is declared or not.
10443
10444@param assetId The selected asset Id.
10445@return Whether the specified asset Id is declared or not.
10446*/
10447bool isDeclaredAsset( string assetId="" );
10448/*!
10449@brief Check whether the specified asset Id is referenced or not.
10450
10451@param assetId The selected asset Id.
10452@return Whether the specified asset Id is referenced or not.
10453*/
10454bool isReferencedAsset( string assetId="" );
10455/*!
10456@brief Rename declared asset Id.
10457
10458@param assetIdFrom The selected asset Id to rename from.
10459@param assetIdFrom The selected asset Id to rename to.
10460@return Whether the rename was successful or not.
10461*/
10462bool renameDeclaredAsset( string assetIdFrom="", string assetIdTo="" );
10463/*!
10464@brief Rename referenced asset Id. 
10465
10466@param assetIdFrom The selected asset Id to rename from.
10467@param assetIdFrom The selected asset Id to rename to.
10468@return Whether the rename was successful or not.
10469*/
10470bool renameReferencedAsset( string assetIdFrom="", string assetIdTo="" );
10471/*!
10472@brief Acquire the specified asset Id.
10473
10474You must release the asset once you're finish with it using 'releaseAsset'.
10475@param assetId The selected asset Id.
10476@param asPrivate Whether to acquire the asset Id as a private asset.
10477@return The acquired asset or NULL if not acquired.
10478*/
10479String acquireAsset( string assetId="", bool asPrivate=false );
10480/*!
10481@brief Release the specified asset Id.
10482
10483The asset should have been acquired using 'acquireAsset'.
10484@param assetId The selected asset Id.
10485@return Whether the asset was released or not.
10486*/
10487bool releaseAsset( string assetId="" );
10488/*!
10489@brief Purge all assets that are not referenced even if they are set to not auto-unload.
10490
10491Assets can be in this state because they are either set to not auto-unload or the asset manager has/is disabling auto-unload.
10492@return No return value.
10493*/
10494void purgeAssets();
10495/*!
10496@brief Deletes the specified asset Id and optionally its loose files and asset dependencies.
10497
10498@param assetId The selected asset Id.
10499@param deleteLooseFiles Whether to delete an assets loose files or not.
10500@param deleteDependencies Whether to delete assets that depend on this asset or not.
10501@return Whether the asset deletion was successful or not.  A failure only indicates that the specified asset was not deleted but dependent assets and their loose files may have being deleted.
10502*/
10503bool deleteAsset( string assetId="", bool deleteLooseFiles=false, bool deleteDependencies=false );
10504/*!
10505@brief Refresh the specified asset Id.
10506
10507@param assetId The selected asset Id.
10508@return No return value.
10509*/
10510void refreshAsset( string assetId="" );
10511/*!
10512@brief Refresh all declared assets.
10513
10514@param Whether to include currently unloaded assets in the refresh or not.  Optional: Defaults to false.
10515Refreshing all assets can be an expensive (time-consuming) operation to perform.
10516@return No return value.
10517*/
10518void refreshAllAssets( bool includeUnloaded=false );
10519/*!
10520@brief Save the currently loaded asset tags manifest.
10521
10522@return Whether the save was successful or not.
10523*/
10524bool saveAssetTags();
10525/*!
10526@brief Restore the currently loaded asset tags manifest from disk (replace anything in memory).
10527
10528@return Whether the restore was successful or not.
10529*/
10530bool restoreAssetTags();
10531/*!
10532@brief Gets the currently loaded asset tags manifest.
10533
10534@return The currently loaded asset tags manifest or zero if not loaded.
10535*/
10536int getAssetTags();
10537/*!
10538@brief Performs an asset query searching for all assets optionally ignoring internal assets.
10539
10540@param assetQuery The asset query object that will be populated with the results.
10541@param ignoreInternal Whether to ignore internal assets or not.  Optional: Defaults to true.
10542@param ignorePrivate Whether to ignore private assets or not.  Optional: Defaults to true.
10543@return The number of asset Ids found or (-1) if an error occurred.
10544*/
10545int findAllAssets( string assetQuery="", bool ignoreInternal=true, bool ignorePrivate=true );
10546/*!
10547@brief Performs an asset query searching for the specified asset name.
10548
10549@param assetQuery The asset query object that will be populated with the results.
10550@param assetName The asset name to search for.  This may be a partial name if 'partialName' is true.
10551@param partialName Whether the asset name is to be used as a partial name or not.  Optional: Defaults to false.
10552@return The number of asset Ids found or (-1) if an error occurred.
10553*/
10554int findAssetName( string assetQuery="", string assetName="", bool partialName=false );
10555/*!
10556@brief Performs an asset query searching for the specified asset category.
10557
10558@param assetQuery The asset query object that will be populated with the results.
10559@param assetCategory The asset category to search for.
10560@param assetQueryAsSource Whether to use the asset query as the data-source rather than the asset managers database or not.  Doing this effectively filters the asset query.  Optional: Defaults to false.
10561@return The number of asset Ids found or (-1) if an error occurred.
10562*/
10563int findAssetCategory( string assetQuery="", string assetCategory="", bool assetQueryAsSource=false );
10564/*!
10565@brief Performs an asset query searching for the specified asset auto-unload flag.
10566
10567@param assetQuery The asset query object that will be populated with the results.
10568@param assetInternal The asset internal flag to search for.
10569@param assetQueryAsSource Whether to use the asset query as the data-source rather than the asset managers database or not.  Doing this effectively filters the asset query.  Optional: Defaults to false.
10570@return The number of asset Ids found or (-1) if an error occurred.
10571*/
10572int findAssetAutoUnload( string assetQuery="", bool assetAutoUnload=false, bool assetQueryAsSource=false );
10573/*!
10574@brief Performs an asset query searching for the specified asset internal flag.
10575
10576@param assetQuery The asset query object that will be populated with the results.
10577@param assetInternal The asset internal flag to search for.
10578@param assetQueryAsSource Whether to use the asset query as the data-source rather than the asset managers database or not.  Doing this effectively filters the asset query.  Optional: Defaults to false.
10579@return The number of asset Ids found or (-1) if an error occurred.
10580*/
10581int findAssetInternal( string assetQuery="", bool assetInternal=false, bool assetQueryAsSource=false );
10582/*!
10583@brief Performs an asset query searching for the specified asset private flag.
10584
10585@param assetQuery The asset query object that will be populated with the results.
10586@param assetPrivate The asset private flag to search for.
10587@param assetQueryAsSource Whether to use the asset query as the data-source rather than the asset managers database or not.  Doing this effectively filters the asset query.  Optional: Defaults to false.
10588@return The number of asset Ids found or (-1) if an error occurred.
10589*/
10590int findAssetPrivate( string assetQuery="", bool assetPrivate=false, bool assetQueryAsSource=false );
10591/*!
10592@brief Performs an asset query searching for the specified asset type.
10593
10594@param assetQuery The asset query object that will be populated with the results.
10595@param assetType The asset type to search for.
10596@param assetQueryAsSource Whether to use the asset query as the data-source rather than the asset managers database or not.  Doing this effectively filters the asset query.  Optional: Defaults to false.
10597@return The number of asset Ids found or (-1) if an error occurred.
10598*/
10599int findAssetType( string assetQuery="", string assetType="", bool assetQueryAsSource=false );
10600/*!
10601@brief Performs an asset query searching for asset Ids that the specified asset Id depends on.
10602
10603@param assetQuery The asset query object that will be populated with the results.
10604@param assetId The asset Id to query for any asset Ids that it depends on.
10605@return The number of asset Ids found or (-1) if an error occurred.
10606*/
10607int findAssetDependsOn( string assetQuery="", string assetId="" );
10608/*!
10609@brief Performs an asset query searching for asset Ids that depend on the specified asset Id.
10610
10611@param assetQuery The asset query object that will be populated with the results.
10612@param assetId The asset Id to query for any asset Ids that may depend on it.
10613@return The number of asset Ids found or (-1) if an error occurred.
10614*/
10615int findAssetIsDependedOn( string assetQuery="", string assetId="" );
10616/*!
10617@brief Performs an asset query searching for invalid asset references.
10618
10619@param assetQuery The asset query object that will be populated with the results.
10620@return The number of asset Ids found that are invalid or (-1) if an error occurred.
10621*/
10622int findInvalidAssetReferences( string assetQuery="" );
10623/*!
10624@brief Performs an asset query searching for the specified asset tag name(s).
10625
10626@param assetQuery The asset query object that will be populated with the results.
10627@param assetTagNames The asset tag name or names to search for.  Multiple names can be specified using comma, space, tab or newline separation.  Tags use an OR operation i.e. only assets tagged with ANY of the specified tags will be returned.
10628@param assetQueryAsSource Whether to use the asset query as the data-source rather than the asset managers database or not.  Doing this effectively filters the asset query.  Optional: Defaults to false.
10629@return The number of asset Ids found or (-1) if an error occurred.
10630*/
10631int findTaggedAssets( string assetQuery="", string assetTagNames="", bool assetQueryAsSource=false );
10632/*!
10633@brief Performs an asset query searching for the specified loose file.
10634
10635@param assetQuery The asset query object that will be populated with the results.
10636@param assetLooseFile The loose-file used by the asset to search for.
10637@param assetQueryAsSource Whether to use the asset query as the data-source rather than the asset managers database or not.  Doing this effectively filters the asset query.  Optional: Defaults to false.
10638@return The number of asset Ids found or (-1) if an error occurred.
10639*/
10640int findAssetLooseFile( string assetQuery="", string assetLooseFile="", bool assetQueryAsSource=false );
10641/*!
10642@brief Gets the number of declared assets.
10643
10644@return Returns the number of declared assets.
10645*/
10646bool getDeclaredAssetCount();
10647/*!
10648@brief Gets the number of asset referenced.
10649
10650@return Returns the number of asset references.
10651*/
10652bool getReferencedAssetCount();
10653/*!
10654@brief Gets the number of loaded internal assets.
10655
10656@return Returns the number of loaded internal assets.
10657*/
10658bool getLoadedInternalAssetCount();
10659/*!
10660@brief Gets the maximum number of loaded internal assets.
10661
10662@return Returns the maximum number of loaded internal assets.
10663*/
10664bool getMaxLoadedInternalAssetCount();
10665/*!
10666@brief Gets the number of loaded external assets.
10667
10668@return Returns the number of loaded external assets.
10669*/
10670bool getLoadedExternalAssetCount();
10671/*!
10672@brief Gets the maximum number of loaded external assets.
10673
10674@return Returns the maximum number of loaded external assets.
10675*/
10676bool getMaxLoadedExternalAssetCount();
10677/*!
10678@brief Dumps a breakdown of all declared assets.
10679
10680@return No return value.
10681*/
10682void dumpDeclaredAssets();
10683
10684/*! @name Callbacks
10685@{ */
10686/// @}
10687
10688
10689/*! @name Ungrouped
10690@{ */
10691/// @}
10692
10693
10694/*! @name Object
10695@{ */
10696/// @}
10697
10698
10699/*! @name Editing
10700@{ */
10701/// @}
10702
10703
10704/*! @name Persistence
10705@{ */
10706/// @}
10707
10708/*!
10709@brief Whether the asset manager echos extra information to the console or not.
10710*/
10711bool EchoInfo[ 552 ];
10712/*!
10713@brief Whether the asset manager should ignore unloading of auto-unload assets or not.
10714*/
10715bool IgnoreAutoUnload[ 553 ];
10716};
10717
10718/*! UNDOCUMENTED!
10719@ingroup UNDOCUMENTED
10720 */
10721class ModuleManager : public SimObject {
10722public:
10723/*!
10724@brief Set the module extension used to scan for modules.  The default is 'module'.
10725
10726@param moduleExtension The module extension used to scan for modules.Do not use a period character.
10727@return Whether setting the module extension was successful or not.
10728*/
10729bool setModuleExtension( string moduleExtension="" );
10730/*!
10731@brief Scans for modules which are sub-directories of the specified path.
10732
10733@param moduleRootPath The root directory to scan for sub - directories containing modules.
10734@param rootOnly[Optional] - Specifies whether to only scan the root path or not when searching for modules.
10735@return Whether the scan was successful or not.A successful scan can still find zero modules.
10736*/
10737bool scanModules( string pRootPath="", bool rootOnly=false );
10738/*!
10739@brief Register the specified module.
10740
10741@param moduleId The module Id to register.
10742@param versionId The version Id to register.
10743@return Whether the module was registered or not.
10744*/
10745bool registerModule( string pModulePath="", string pModuleFile="" );
10746/*!
10747@brief Unregister the specified module.
10748
10749@param moduleId The module Id to unregister.
10750@param versionId The version Id to unregister.
10751@return Whether the module was unregister or not.
10752*/
10753bool unregisterModule( string pModuleId="", bool versionId=false );
10754/*!
10755@brief Load the specified module group.
10756
10757@param moduleGroup The module group to load.
10758@return Whether the module group was loaded or not.
10759*/
10760bool loadGroup( string pModuleGroup="" );
10761/*!
10762@brief Unload the specified module group.
10763
10764@param moduleGroup The module group to unload.
10765@return Whether the module group was unloaded or not.
10766*/
10767bool unloadGroup( string pModuleGroup="" );
10768/*!
10769@brief Load the specified module explicitly.
10770
10771@param moduleId The module Id to load.
10772@param versionId The version Id to load.Optional:  Will load the latest version.
10773@return Whether the module Id was loaded or not.
10774*/
10775bool loadExplicit( string pModuleId="", int pVersionId=-1 );
10776/*!
10777@brief Unload the specified module explicitly.
10778
10779@param moduleId The module Id to unload.
10780@return Whether the module Id was unloaded or not.
10781*/
10782bool unloadExplicit( string pModuleId="" );
10783/*!
10784@brief Find the specific module Id optionally at the specified version Id.
10785
10786@param moduleId The module Id to find.
10787@param versionId The version Id to find.
10788@return The module definition object or NULL if not found.
10789*/
10790String findModule( string pModuleId="", uint pVersionId=1 );
10791/*!
10792@brief Find the specific module Id optionally at the specified version Id.
10793
10794@param moduleId The module Id to find.
10795@param versionId The version Id to find.
10796@return The module definition object or NULL if not found.
10797*/
10798String findModuleByFilePath( string filePath="" );
10799/*!
10800@brief Find all the modules registered with the specified loaded state.
10801
10802@param loadedOnly Whether to return only modules that are loaded or not.
10803@return A list of space - separated module definition object Ids.
10804*/
10805String findModules( bool loadedOnly=false );
10806/*!
10807@brief Find the modules registered with the specified module type.
10808
10809@param moduleType The module type to search for.
10810@param loadedOnly Whether to return only modules that are loaded or not.
10811@return A list of space - separated module definition object Ids.
10812*/
10813String findModuleTypes( string pModuleType="", bool loadedOnly=false );
10814/*!
10815@brief Copy the module to a new location with a new module Id.
10816
10817@param sourceModuleDefinition The module definition to copy.
10818@param targetModuleId The module Id to rename the copied module to including all references to the source module Id.It is valid to specifiy the source module Id to produce an identical copy.
10819@param targetPath The target path to copy the module to.Addition folders will be created depending on whether 'useVersionPathing' is used or not.
10820@param useVersionPathing Whether to add a '/targetModuleId/versionId' folder to the target path or not.This allows copying multiple versions of the same module Id.
10821@return The new module definition file if copy was successful or NULL if not.
10822*/
10823String copyModule( string sourceModuleDefinition="", string pTargetModuleId="", string pTargetPath="", bool useVersionPathing=false );
10824/*!
10825@brief Rename a module.
10826
10827@param sourceModuleDefinition The module definition to rename.
10828@param pNewModuleName The new name the module should have.
10829@return Weither the rename was successful or not.
10830*/
10831bool renameModule( string sourceModuleDefinition="", string pNewModuleName="" );
10832/*!
10833@brief Synchronize the module dependencies of a module definition to a target dependency folder.
10834
10835@param rootModuleDefinition The module definition used to determine dependencies.
10836@param targetDependencyPath The target dependency folder to copy dependencies to.
10837@return Whether the module dependencies were synchronized correctly or not.
10838*/
10839bool synchronizeDependencies( string rootModuleDefinition="", string pTargetDependencyFolder="" );
10840/*!
10841@brief Checks whether a module merge definition file is available or not.
10842
10843@return Whether a module merge definition file is available or not.
10844*/
10845bool isModuleMergeAvailable();
10846/*!
10847@brief Checks whether a module merge using the modules in the source path can current happen or not.
10848
10849@param mergeSourcePath The path where modules to be merged are located.
10850@return Whether a module merge using the modules in the source path can current happen or not.
10851*/
10852bool canMergeModules( string mergeSourcePath="" );
10853/*!
10854@brief Performs a module merge into the selected target path.
10855
10856@param mergeTargetPath The path where modules will be merged into.
10857@param removeMergeDefinition Whether to remove any merge definition found or not if merge is successful.
10858@param registerNewModules Whether new (not replaced or updated) modules should be registered or not.
10859@return Whether the module merge was successful or not.Failure here could result in a corrupt module state.Reinstall is recommended or at least advised to the user is recommended.
10860*/
10861bool mergeModules( string pMergeTargetPath="", bool removeMergeDefinition=false, bool registerNewModules=false );
10862/*!
10863@brief Registers the specified object as a listener for module notifications.
10864
10865@param listenerObject The object to start receiving module notifications.
10866@return No return value.
10867*/
10868void addListener( string listenerObject="" );
10869/*!
10870@brief Unregisters the specified object as a listener for module notifications.
10871
10872@param listenerObject The object to stop receiving module notifications.
10873@return No return value.
10874*/
10875void removeListener( string listenerObject="" );
10876/*!
10877@brief Sets if the Module Manager should ingore laoded groups.
10878
10879@param doIgnore Whether we should or should not ignore loaded groups.
10880@return No return value.
10881*/
10882void ignoreLoadedGroups( bool doIgnore=false );
10883
10884/*! @name Callbacks
10885@{ */
10886/// @}
10887
10888
10889/*! @name Ungrouped
10890@{ */
10891/// @}
10892
10893
10894/*! @name Object
10895@{ */
10896/// @}
10897
10898
10899/*! @name Editing
10900@{ */
10901/// @}
10902
10903
10904/*! @name Persistence
10905@{ */
10906/// @}
10907
10908/*!
10909@brief Whether the module manager enforces any dependencies on module definitions it discovers or not.
10910*/
10911bool EnforceDependencies;
10912/*!
10913@brief Whether the module manager echos extra information to the console or not.
10914*/
10915bool EchoInfo;
10916};
10917
10918/*!
10919@brief A debug helper for rendering debug primitives to the scene.
10920
10921The DebugDrawer is used to render debug primitives to the scene for testing.  It is often useful when debugging collision code or complex 3d algorithms to have them draw debug information, like culling hulls or bounding volumes, normals, simple lines, and so forth.
10922
10923A key feature of the DebugDrawer is that each primitive gets a "time to live" (TTL) which allows them to continue to render to the scene for a fixed period of time.  You can freeze or resume the system at any time to allow you to examine the output.
10924@tsexample
10925DebugDraw.drawLine( %player.getMuzzlePoint( 0 ), %hitPoint );
10926DebugDraw.setLastTTL( 5000 ); // 5 seconds.
10927@endtsexample
10928The DebugDrawer renders solely in world space and all primitives are rendered with the cull mode disabled.
10929@note This feature can easily be used to cheat in online games, so you should be sure it is disabled in your shipping game.  By default the DebugDrawer is disabled in all TORQUE_SHIPPING builds.
10930@ingroup GFX
10931
10932*/
10933class DebugDrawer : public SimObject {
10934public:
10935/*!
10936@brief Draws a line primitive between two 3d points.
10937
10938*/
10939void drawLine( Point3F a, Point3F b, LinearColorF color=LinearColorF::WHITE );
10940/*!
10941@brief Draws an axis aligned box primitive within the two 3d points.
10942
10943*/
10944void drawBox( Point3F a, Point3F b, LinearColorF color=LinearColorF::WHITE );
10945/*!
10946@brief Sets the "time to live" (TTL) for the last rendered primitive.
10947
10948*/
10949void setLastTTL( uint ms );
10950/*!
10951@brief Sets the z buffer reading state for the last rendered primitive.
10952
10953*/
10954void setLastZTest( bool enabled );
10955/*!
10956@brief Toggles freeze mode which keeps the currently rendered primitives from expiring.
10957
10958*/
10959void toggleFreeze();
10960/*!
10961@brief Toggles the rendering of DebugDrawer primitives.
10962
10963*/
10964void toggleDrawing();
10965
10966/*! @name Callbacks
10967@{ */
10968/// @}
10969
10970
10971/*! @name Ungrouped
10972@{ */
10973/// @}
10974
10975
10976/*! @name Object
10977@{ */
10978/// @}
10979
10980
10981/*! @name Editing
10982@{ */
10983/// @}
10984
10985
10986/*! @name Persistence
10987@{ */
10988/// @}
10989
10990};
10991
10992/*!
10993@brief A collection of SimObjects.
10994
10995It is often necessary to keep track of an arbitrary set of SimObjects. For instance, Torque's networking code needs to not only keep track of the set of objects which need to be ghosted, but also the set of objects which must <i>always</i> be ghosted. It does this by working with two sets. The first of these is the RootGroup (which is actually a SimGroup) and the second is the GhostAlwaysSet, which contains objects which must always be ghosted to the client.
10996
10997Some general notes on SimSets:
10998
10999- Membership is not exclusive. A SimObject may be a member of multiple SimSets.
11000
11001- A SimSet does not destroy subobjects when it is destroyed.
11002
11003- A SimSet may hold an arbitrary number of objects.
11004
11005@ingroup Console
11006@ingroup Scripting
11007*/
11008class SimSet : public SimObject {
11009public:
11010/*!
11011@brief Dump a list of all objects contained in the set to the console.
11012
11013*/
11014void listObjects();
11015/*!
11016@brief Add the given objects to the set.
11017
11018@param objects The objects to add to the set.*/
11019void add( SimObject objects... );
11020/*!
11021@brief Remove the given objects from the set.
11022
11023@param objects The objects to remove from the set.*/
11024void remove( SimObject objects... );
11025/*!
11026@brief Remove all objects from the set.
11027
11028*/
11029void clear();
11030/*!
11031@brief Delete all objects in the set.
11032
11033*/
11034void deleteAllObjects();
11035/*!
11036@brief Return a random object from the set.
11037
11038@return A randomly selected object from the set or -1 if the set is empty.*/
11039SimObject getRandom();
11040/*!
11041@brief Call a method on all objects contained in the set.
11042
11043
11044@param method The name of the method to call.
11045@param args The arguments to the method.
11046
11047@note This method recurses into all SimSets that are children to the set.
11048
11049@see callOnChildrenNoRecurse*/
11050void callOnChildren( string method, string args... );
11051/*!
11052@brief Call a method on all objects contained in the set.
11053
11054
11055@param method The name of the method to call.
11056@param args The arguments to the method.
11057
11058@note This method does not recurse into child SimSets.
11059
11060@see callOnChildren*/
11061void callOnChildrenNoRecurse( string method, string args... );
11062/*!
11063@brief Make sure child1 is ordered right before child2 in the set.
11064
11065@param child1 The first child.  The object must already be contained in the set.
11066@param child2 The second child.  The object must already be contained in the set.*/
11067void reorderChild( SimObject child1, SimObject child2 );
11068/*!
11069@brief Get the number of objects contained in the set.
11070
11071@return The number of objects contained in the set.*/
11072int getCount();
11073/*!
11074@brief Get the number of direct and indirect child objects contained in the set.
11075
11076@return The number of objects contained in the set as well as in other sets contained directly or indirectly in the set.*/
11077int getFullCount();
11078/*!
11079@brief Get the object at the given index.
11080
11081@param index The object index.
11082@return The object at the given index or -1 if index is out of range.*/
11083SimObject getObject( uint index );
11084/*!
11085@brief Return the index of the given object in this set.
11086
11087@param obj The object for which to return the index.  Must be contained in the set.
11088@return The index of the object or -1 if the object is not contained in the set.*/
11089int getObjectIndex( SimObject obj );
11090/*!
11091@brief Test whether the given object belongs to the set.
11092
11093@param obj The object.
11094@return True if the object is contained in the set; false otherwise.*/
11095bool isMember( SimObject obj );
11096/*!
11097@brief Find an object in the set by its internal name.
11098
11099@param internalName The internal name of the object to look for.
11100@param searchChildren If true, SimSets contained in the set will be recursively searched for the object.
11101@return The object with the given internal name or 0 if no match was found.
11102*/
11103SimObject findObjectByInternalName( string internalName, bool searchChildren=false );
11104/*!
11105@brief Make the given object the first object in the set.
11106
11107@param obj The object to bring to the frontmost position.  Must be contained in the set.*/
11108void bringToFront( SimObject obj );
11109/*!
11110@brief Make the given object the last object in the set.
11111
11112@param obj The object to bring to the last position.  Must be contained in the set.*/
11113void pushToBack( SimObject obj );
11114/*!
11115@brief Sort the objects in the set using the given comparison function.
11116
11117@param callbackFunction Name of a function that takes two object arguments A and B and returns -1 if A is less, 1 if B is less, and 0 if both are equal.*/
11118void sort( string callbackFunction );
11119/*!
11120@brief Test whether the given object may be added to the set.
11121
11122@param obj The object to test for potential membership.
11123@return True if the object may be added to the set, false otherwise.*/
11124bool acceptsAsChild( SimObject obj );
11125
11126/*! @name Callbacks
11127@{ */
11128/*!
11129@brief Called when an object is added to the set.
11130
11131@param object The object that was added.*/
11132void onObjectAdded( SimObject object );
11133/*!
11134@brief Called when an object is removed from the set.
11135
11136@param object The object that was removed.*/
11137void onObjectRemoved( SimObject object );
11138/// @}
11139
11140
11141/*! @name Ungrouped
11142@{ */
11143/// @}
11144
11145
11146/*! @name Object
11147@{ */
11148/// @}
11149
11150
11151/*! @name Editing
11152@{ */
11153/// @}
11154
11155
11156/*! @name Persistence
11157@{ */
11158/// @}
11159
11160};
11161
11162/*!
11163@brief A collection of SimObjects that are owned by the group.
11164
11165A SimGroup is a stricter form of SimSet. SimObjects may only be a member of a single SimGroup at a time. The SimGroup will automatically enforce the single-group-membership rule (ie. adding an object to a SimGroup will cause it to be removed from its current SimGroup, if any).
11166
11167Deleting a SimGroup will also delete all SimObjects in the SimGroup.
11168
11169@tsexample
11170// Create a SimGroup for particle emitters
11171new SimGroup(Emitters)
11172{
11173   canSaveDynamicFields = "1";
11174
11175   new ParticleEmitterNode(CrystalEmmiter) {
11176      active = "1";
11177      emitter = "dustEmitter";
11178      velocity = "1";
11179      dataBlock = "GenericSmokeEmitterNode";
11180      position = "-61.6276 2.1142 4.45027";
11181      rotation = "1 0 0 0";
11182      scale = "1 1 1";
11183      canSaveDynamicFields = "1";
11184   };
11185
11186   new ParticleEmitterNode(Steam1) {
11187      active = "1";
11188      emitter = "SlowSteamEmitter";
11189      velocity = "1";
11190      dataBlock = "GenericSmokeEmitterNode";
11191      position = "-25.0458 1.55289 2.51308";
11192      rotation = "1 0 0 0";
11193      scale = "1 1 1";
11194      canSaveDynamicFields = "1";
11195   };
11196};
11197
11198@endtsexample
11199
11200@ingroup Console
11201@ingroup Scripting
11202*/
11203class SimGroup : public SimSet {
11204public:
11205
11206/*! @name Callbacks
11207@{ */
11208/// @}
11209
11210
11211/*! @name Ungrouped
11212@{ */
11213/// @}
11214
11215
11216/*! @name Object
11217@{ */
11218/// @}
11219
11220
11221/*! @name Editing
11222@{ */
11223/// @}
11224
11225
11226/*! @name Persistence
11227@{ */
11228/// @}
11229
11230};
11231
11232/*!
11233@brief 
11234@ingroup 
11235@section Datablock_Networking Datablocks and Networking
11236@section Datablock_ClientSide Client-Side Datablocks
11237
11238*/
11239class SimDataBlock : public SimObject {
11240public:
11241/*!
11242@brief Reload the datablock.  This can only be used with a local client configuration.
11243
11244*/
11245void reloadOnLocalClient();
11246
11247/*! @name Callbacks
11248@{ */
11249/// @}
11250
11251
11252/*! @name Ungrouped
11253@{ */
11254/// @}
11255
11256
11257/*! @name Object
11258@{ */
11259/// @}
11260
11261
11262/*! @name Editing
11263@{ */
11264/// @}
11265
11266
11267/*! @name Persistence
11268@{ */
11269/// @}
11270
11271};
11272
11273/*!
11274@brief A datablock that describes an ambient sound space.
11275
11276Each ambience datablock captures the properties of a unique ambient sound space.  A sound space is comprised of:
11277- an ambient audio track that is played when the listener is inside the space,
11278- a reverb environment that is active inside the space, and
11279- a number of SFXStates that are activated when entering the space and deactivated when exiting it.
11280
11281Each of these properties is optional.
11282
11283An important characteristic of ambient audio spaces is that their unique nature is not determined by their location in space but rather by their SFXAmbience datablock.  This means that the same SFXAmbience datablock assigned to multiple locations in a level represents the same unique audio space to the sound system.
11284
11285This is an important distinction for the ambient sound mixer which will activate a given ambient audio space only once at any one time regardless of how many intersecting audio spaces with the same SFXAmbience datablock assigned the listener may currently be in.
11286
11287All SFXAmbience instances are automatically added to the global @c SFXAmbienceSet.
11288
11289At the moment, transitions between reverb environments are not blended and different reverb environments from multiple active SFXAmbiences will not be blended together.  This will be added in a future version.
11290
11291@tsexample
11292singleton SFXAmbience( Underwater )
11293{
11294   environment = AudioEnvUnderwater;
11295   soundTrack = ScubaSoundList;
11296   states[ 0 ] = AudioLocationUnderwater;
11297};
11298@endtsexample
11299
11300@see SFXEnvironment
11301@see SFXTrack
11302@see SFXState
11303@see LevelInfo::soundAmbience
11304@see Zone::soundAmbience
11305
11306@ref Datablock_Networking
11307@ingroup SFX
11308@ingroup Datablocks
11309
11310*/
11311class SFXAmbience : public SimDataBlock {
11312public:
11313
11314/*! @name Callbacks
11315@{ */
11316/// @}
11317
11318
11319/*! @name Sound
11320@{ */
11321/*!
11322@brief Reverb environment active in the ambience zone.
11323
11324@ref SFX_reverb
11325*/
11326SFXEnvironment environment;
11327/*!
11328@brief Sound track to play in the ambience zone.
11329*/
11330SFXTrack soundTrack;
11331/*!
11332@brief The rolloff factor to apply to distance-based volume attenuation in this space.
11333
11334Defaults to 1.0.
11335
11336@note This applies to the logarithmic distance model only.
11337
11338@ref SFXSource_volume
11339*/
11340float rolloffFactor;
11341/*!
11342@brief The factor to apply to the doppler affect in this space.
11343
11344Defaults to 0.5.
11345
11346@ref SFXSource_doppler
11347*/
11348float dopplerFactor;
11349/*!
11350@brief States to activate when the ambient zone is entered.
11351
11352When the ambient sound state is entered, all states associated with the state will be activated (given that they are not disabled) and deactivated when the space is exited again.
11353*/
11354SFXState states[ 4 ];
11355/// @}
11356
11357
11358/*! @name Ungrouped
11359@{ */
11360/// @}
11361
11362
11363/*! @name Object
11364@{ */
11365/// @}
11366
11367
11368/*! @name Editing
11369@{ */
11370/// @}
11371
11372
11373/*! @name Persistence
11374@{ */
11375/// @}
11376
11377};
11378
11379/*!
11380@brief A description for how a sound should be played.
11381
11382SFXDescriptions are used by the sound system to collect all parameters needed to set up a given sound for playback.  This includes information like its volume level, its pitch shift, etc. as well as more complex information like its fade behavior, 3D properties, and per-sound reverb properties.
11383
11384Any sound playback will require a valid SFXDescription.
11385
11386As datablocks, SFXDescriptions can be set up as either networked datablocks or non-networked datablocks, though it generally makes sense to keep all descriptions non-networked since they will be used exclusively by clients.
11387
11388@tsexample
11389// A description for a 3D sound with a reasonable default range setting.
11390// The description is set up to assign sounds to the AudioChannelEffects source group
11391// (defined in the core scripts).  An alternative means to achieve this is to use the
11392// AudioEffects description as a copy source (": AudioEffects").
11393
11394singleton SFXDescription( Audio3DSound )
11395{
11396  sourceGroup       = AudioChannelEffects;
11397  is3D              = true;
11398  referenceDistance = 20.0;
11399  maxDistance       = 100.0;
11400};
11401@endtsexample
11402
11403@ingroup SFX
11404@ingroup Datablocks
11405
11406*/
11407class SFXDescription : public SimDataBlock {
11408public:
11409
11410/*! @name Callbacks
11411@{ */
11412/// @}
11413
11414/*!
11415@brief Automatic setting of SFXDescription::reverbDirect due to distance to listener.
11416
11417@see SFXDescription::flags
11418
11419@ingroup SFXDescription*/
11420static const int REVERB_DIRECTHFAUTO;
11421/*!
11422@brief Automatic setting of SFXDescription::reverbRoom due to distance to listener.
11423
11424@see SFXDescription::flags
11425
11426@ingroup SFXDescription*/
11427static const int REVERB_ROOMAUTO;
11428/*!
11429@brief Automatic setting of SFXDescription::reverbRoomHF due to distance to listener.
11430
11431@see SFXDescription::flags
11432
11433@ingroup SFXDescription*/
11434static const int REVERB_ROOMHFAUTO;
11435/*!
11436@brief EAX4/SFX/GameCube/Wii: Specify channel to target reverb instance 0. Default target.
11437
11438@see SFXDescription::flags
11439
11440@ingroup SFXDescription*/
11441static const int REVERB_INSTANCE0;
11442/*!
11443@brief EAX4/SFX/GameCube/Wii: Specify channel to target reverb instance 1.
11444
11445@see SFXDescription::flags
11446
11447@ingroup SFXDescription*/
11448static const int REVERB_INSTANCE1;
11449/*!
11450@brief EAX4/SFX/GameCube/Wii: Specify channel to target reverb instance 2.
11451
11452@see SFXDescription::flags
11453
11454@ingroup SFXDescription*/
11455static const int REVERB_INSTANCE2;
11456/*!
11457@brief EAX4/SFX/GameCube/Wii: Specify channel to target reverb instance 3.
11458
11459@see SFXDescription::flags
11460
11461@ingroup SFXDescription*/
11462static const int REVERB_INSTANCE3;
11463
11464/*! @name Playback
11465@{ */
11466/*!
11467@brief Group that sources playing with this description should be put into.
11468
11469
11470When a sound source is allocated, it will be made a child of the source group that is listed in its 
11471description.  This group will then modulate several properties of the sound as it is played.
11472
11473For example, one use of groups is to segregate sounds so that volume levels of different sound groups such as interface audio and game audio can be controlled independently.
11474
11475@ref SFXSource_hierarchies
11476*/
11477SFXSource sourceGroup;
11478/*!
11479@brief Base volume level for the sound.
11480
11481
11482This will be the starting point for volume attenuation on the sound.  The final effective volume of a sound will be dependent on a number of parameters.
11483
11484Must be between 0 (mute) and 1 (full volume).  Default is 1.
11485
11486@ref SFXSource_volume
11487*/
11488float volume;
11489/*!
11490@brief Pitch shift to apply to playback.
11491
11492
11493The pitch assigned to a sound determines the speed at which it is played back.  A pitch shift of 1 plays the sound at its default speed.  A greater shift factor speeds up playback and a smaller shift factor slows it down.
11494
11495Must be >0.  Default is 1.
11496*/
11497float pitch;
11498/*!
11499@brief If true, the sound will be played in an endless loop.
11500
11501
11502Default is false.
11503*/
11504bool isLooping;
11505/*!
11506@brief Priority level for virtualization of sounds (1 = base level).
11507
11508When there are more concurrently active sounds than supported by the audio mixer, some of the sounds need to be culled.  Which sounds are culled first depends primarily on total audibility of individual sounds. However, the priority of invidual sounds may be decreased or decreased through this field.
11509
11510@ref SFXSound_virtualization
11511*/
11512float priority;
11513/*!
11514@brief Whether the sound is allowed to be mixed in hardware.
11515
11516If true, the sound system will try to allocate the voice for the sound directly on the sound hardware for mixing by the hardware mixer.  Be aware that a hardware mixer may not provide all features available to sounds mixed in software.
11517
11518@note This flag currently only takes effect when using FMOD.
11519
11520@note Generally, it is preferable to let sounds be mixed in software.
11521
11522
11523*/
11524bool useHardware;
11525/*!
11526@brief Names of the parameters to which sources using this description will automatically be linked.
11527
11528
11529Individual parameters are identified by their #internalName.
11530
11531@ref SFX_interactive
11532*/
11533string parameters[ 8 ];
11534/// @}
11535
11536
11537/*! @name Fading
11538@{ */
11539/*!
11540@brief Number of seconds to gradually fade in volume from zero when playback starts.
11541
11542Must be >= 0.
11543
11544@ref SFXSource_fades
11545*/
11546float fadeInTime;
11547/*!
11548@brief Number of seconds to gradually fade out volume down to zero when playback is stopped or paused.
11549
11550Must be >=0.
11551
11552@ref SFXSource_fades
11553*/
11554float fadeOutTime;
11555/*!
11556@brief Easing curve for fade-in transition.
11557
11558Volume fade-ins will interpolate volume along this curve.
11559
11560@ref SFXSource_fades
11561*/
11562EaseF fadeInEase;
11563/*!
11564@brief Easing curve for fade-out transition.
11565
11566Volume fade-outs will interpolate volume along this curve.
11567
11568@ref SFXSource_fades
11569*/
11570EaseF fadeOutEase;
11571/*!
11572@brief Fade each cycle of a loop in and/or out; otherwise only fade-in first cycle.
11573
11574By default, volume fading is applied to the beginning and end of the playback range, i.e. a fade-in segment is placed at the beginning of the sound and a fade-out segment is paced at the end of a sound.  However, when looping playback, this may be undesirable as each iteration of the sound will then have a fade-in and fade-out effect.
11575
11576To set up looping sounds such that a fade-in is applied only when the sound is first started (or playback resumed) and a fade-out is only applied when the sound is explicitly paused or stopped, set this field to true.
11577
11578Default is false.
11579
11580@ref SFXSource_fades
11581*/
11582bool fadeLoops;
11583/// @}
11584
11585
11586/*! @name 3D
11587@{ */
11588/*!
11589@brief If true, sounds played with this description will have a position and orientation in space.
11590
11591Unlike a non-positional sound, a 3D sound will have its volume attenuated depending on the distance to the listener in space.  The farther the sound moves away from the listener, the less audible it will be.
11592
11593Non-positional sounds, in contrast, will remain at their original volume regardless of where the listener is.
11594
11595@note Whether a sound is positional or non-positional cannot be changed once the sound was created so this field determines up front which is the case for a given sound.
11596
11597@ref SFX_3d
11598@ref SFXSource_volume
11599*/
11600bool is3D;
11601/*!
11602@brief Distance at which volume attenuation begins.
11603
11604Up to this distance, the sound retains its base volume.
11605
11606In the linear distance model, the volume will linearly from this distance onwards up to maxDistance where it reaches zero.
11607
11608In the logarithmic distance model, the reference distance determine how fast the sound volume decreases with distance.  Each referenceDistance steps (scaled by the rolloff factor), the volume halves.
11609
11610A rule of thumb is that for sounds that require you to be close to hear them in the real world, set the reference distance to small values whereas for sounds that are widely audible set it to larger values.
11611
11612Only applies to 3D sounds.
11613@see LevelInfo::soundDistanceModel
11614
11615@ref SFX_3d
11616@ref SFXSource_volume
11617*/
11618float referenceDistance;
11619/*!
11620@brief The distance at which attenuation stops.
11621
11622In the linear distance model, the attenuated volume will be zero at this distance.
11623
11624In the logarithmic model, attenuation will simply stop at this distance and the sound will keep its attenuated volume from there on out.  As such, it primarily functions as a cutoff factor to exponential distance attentuation to limit the number of voices relevant to updates.
11625
11626Only applies to 3D sounds.
11627@see LevelInfo::soundDistanceModel
11628
11629@ref SFX_3d
11630@ref SFXSource_volume
11631*/
11632float maxDistance;
11633/*!
11634@brief Bounds on random displacement of 3D sound positions.
11635
11636When a 3D sound is created and given its initial position in space, this field is used to determine the amount of randomization applied to the actual position given to the sound system.
11637
11638The randomization uses the following scheme:@verbatim
11639x += rand( - scatterDistance[ 0 ], scatterDistance[ 0 ] );
11640y += rand( - scatterDistance[ 1 ], scatterDistance[ 1 ] );
11641z += rand( - scatterDistance[ 2 ], scatterDistance[ 2 ] );
11642@endverbatim
11643
11644*/
11645Point3F scatterDistance;
11646/*!
11647@brief Inner sound cone angle in degrees.
11648
11649This value determines the angle of the inner volume cone that protrudes out in the direction of a sound.  Within this cone, the sound source retains full volume that is unaffected by sound cone settings (though still affected by distance attenuation.)
11650
11651Valid values are from 0 to 360. Must be less than coneOutsideAngle. Default is 360. Only for 3D sounds.
11652
11653@ref SFXSource_cones
11654*/
11655int coneInsideAngle;
11656/*!
11657@brief Outer sound cone angle in degrees.
11658
11659This value determines the angle of the outer volume cone that protrudes out in the direction of a sound and surrounds the inner volume cone.  Within this cone, volume will linearly interpolate from the outer cone hull inwards to the inner coner hull starting with the base volume scaled by coneOutsideVolume and ramping up/down to the full base volume.
11660
11661Valid values are from 0 to 360.  Must be >= coneInsideAngle.  Default is 360.  Only for 3D sounds.
11662
11663@ref SFXSource_cones
11664*/
11665int coneOutsideAngle;
11666/*!
11667@brief Determines the volume scale factor applied the a source's base volume level outside of the outer cone.
11668
11669In the outer cone, starting from outside the inner cone, the scale factor smoothly interpolates from 1.0 (within the inner cone) to this value.  At the moment, the allowed range is 0.0 (silence) to 1.0 (no attenuation) as amplification is only supported on XAudio2 but not on the other devices.
11670
11671Only for 3D sound.
11672
11673@ref SFXSource_cones
11674*/
11675float coneOutsideVolume;
11676/*!
11677@brief Scale factor to apply to logarithmic distance attenuation curve.  If -1, the global rolloff setting is used.
11678
11679
11680@note Per-sound rolloff is only supported on OpenAL and FMOD at the moment.  With other divices, the global rolloff setting is used for all sounds.
11681@see LevelInfo::soundDistanceModel
11682*/
11683float rolloffFactor;
11684/// @}
11685
11686
11687/*! @name Streaming
11688@{ */
11689/*!
11690@brief If true, incrementally stream sounds; otherwise sounds are loaded in full.
11691
11692
11693@ref SFX_streaming
11694*/
11695bool isStreaming;
11696/*!
11697@brief Number of seconds of sample data per single streaming packet.
11698
11699This field allows to fine-tune streaming for individual sounds.  The streaming system processes streamed sounds in batches called packets.  Each packet will contain a set amount of sample data determined by this field.  The greater its value, the more sample data each packet contains, the more work is done per packet.
11700
11701@note This field only takes effect when Torque's own sound system performs the streaming. When FMOD is used, this field is ignored and streaming is performed by FMOD.
11702
11703@ref SFX_streaming
11704*/
11705int streamPacketSize;
11706/*!
11707@brief Number of sample packets to read and buffer in advance.
11708
11709This field determines the number of packets that the streaming system will try to keep buffered in advance.  As such it determines the number of packets that can be consumed by the sound device before the playback queue is running dry.  Greater values thus allow for more lag in the streaming pipeline.
11710
11711@note This field only takes effect when Torque's own sound system performs the streaming. When FMOD is used, this field is ignored and streaming is performed by FMOD.
11712
11713@ref SFX_streaming
11714*/
11715int streamReadAhead;
11716/// @}
11717
11718
11719/*! @name Reverb
11720@{ */
11721/*!
11722@brief If true, use the reverb properties defined here on sounds.
11723
11724By default, sounds will be assigned a generic reverb profile.  By setting this flag to true, a custom reverb setup can be defined using the "Reverb" properties that will then be assigned to sounds playing with the description.
11725
11726@ref SFX_reverb
11727*/
11728bool useCustomReverb;
11729/*!
11730@brief Density of reverb environment.
11731*/
11732float reverbDensity;
11733/*!
11734@brief Environment diffusion.
11735*/
11736float reverbDiffusion;
11737/*!
11738@brief Reverb Gain Level.
11739*/
11740float reverbGain;
11741/*!
11742@brief Reverb Gain to high frequencies
11743*/
11744float reverbGainHF;
11745/*!
11746@brief Reverb Gain to high frequencies
11747*/
11748float reverbGainLF;
11749/*!
11750@brief Decay time for the reverb.
11751*/
11752float reverbDecayTime;
11753/*!
11754@brief High frequency decay time ratio.
11755*/
11756float reverbDecayHFRatio;
11757/*!
11758@brief High frequency decay time ratio.
11759*/
11760float reverbDecayLFRatio;
11761/*!
11762@brief Reflection Gain.
11763*/
11764float reflectionsGain;
11765/*!
11766@brief How long to delay reflections.
11767*/
11768float reflectionDelay;
11769/*!
11770@brief Late reverb gain amount.
11771*/
11772float lateReverbGain;
11773/*!
11774@brief Late reverb delay time.
11775*/
11776float lateReverbDelay;
11777/*!
11778@brief Reverb echo time.
11779*/
11780float reverbEchoTime;
11781/*!
11782@brief Reverb echo depth.
11783*/
11784float reverbEchoDepth;
11785/*!
11786@brief Reverb Modulation time.
11787*/
11788float reverbModTime;
11789/*!
11790@brief Reverb Modulation Depth.
11791*/
11792float reverbModDepth;
11793/*!
11794@brief High Frequency air absorbtion
11795*/
11796float airAbsorbtionGainHF;
11797/*!
11798@brief Reverb High Frequency Reference.
11799*/
11800float reverbHFRef;
11801/*!
11802@brief Reverb Low Frequency Reference.
11803*/
11804float reverbLFRef;
11805/*!
11806@brief Rolloff factor for reverb.
11807*/
11808float roomRolloffFactor;
11809/*!
11810@brief High Frequency decay limit.
11811*/
11812int decayHFLimit;
11813/// @}
11814
11815
11816/*! @name Ungrouped
11817@{ */
11818/// @}
11819
11820
11821/*! @name Object
11822@{ */
11823/// @}
11824
11825
11826/*! @name Editing
11827@{ */
11828/// @}
11829
11830
11831/*! @name Persistence
11832@{ */
11833/// @}
11834
11835};
11836
11837/*!
11838@brief Allows legacy AudioDescription datablocks to be treated as SFXDescription datablocks.
11839
11840@ingroup afxMisc
11841@ingroup AFX
11842@ingroup Datablocks
11843
11844*/
11845class AudioDescription : public SFXDescription {
11846public:
11847
11848/*! @name Callbacks
11849@{ */
11850/// @}
11851
11852
11853/*! @name Playback
11854@{ */
11855/// @}
11856
11857
11858/*! @name Fading
11859@{ */
11860/// @}
11861
11862
11863/*! @name 3D
11864@{ */
11865/// @}
11866
11867
11868/*! @name Streaming
11869@{ */
11870/// @}
11871
11872
11873/*! @name Reverb
11874@{ */
11875/// @}
11876
11877
11878/*! @name Ungrouped
11879@{ */
11880/// @}
11881
11882
11883/*! @name Object
11884@{ */
11885/// @}
11886
11887
11888/*! @name Editing
11889@{ */
11890/// @}
11891
11892
11893/*! @name Persistence
11894@{ */
11895/// @}
11896
11897};
11898
11899/*!
11900@brief Description of a reverb environment.
11901
11902A reverb environment specifies how the audio mixer should render advanced environmental audio effects.  
11903
11904To use reverb environments in your level, set up one or more ambient audio spaces, assign reverb environments appropriately, and then attach the SFXAmbiences to your LevelInfo (taking effect globally) or Zone objects (taking effect locally).
11905
11906To define your own custom reverb environments, it is usually easiest to adapt one of the pre-existing reverb definitions:
11907@tsexample_nopar
11908singleton SFXEnvironment( AudioEnvCustomUnderwater : AudioEnvUnderwater )
11909{
11910   // Override select properties from AudioEnvUnderwater here.
11911};
11912@endtsexample
11913
11914In the Datablock Editor, this can be done by selecting an existing environment to copy from when creating the SFXEnvironment datablock.
11915
11916For a precise description of reverb audio and the properties of this class, please consult the EAX documentation.
11917
11918All SFXEnvironment instances are automatically added to the global @c SFXEnvironmentSet.
11919
11920@see http://www.atc.creative.com/algorithms/eax20.pdf
11921@see http://connect.creativelabs.com/developer/Gaming/Forms/AllItems.aspx
11922@see SFXAmbience::environment
11923
11924@ref SFX_reverb
11925@ingroup SFX
11926
11927*/
11928class SFXEnvironment : public SimDataBlock {
11929public:
11930
11931/*! @name Callbacks
11932@{ */
11933/// @}
11934
11935/*!
11936@brief SFXEnvironment::envSize affects reverberation decay time.
11937
11938@see SFXEnvironment::flags
11939
11940@ingroup SFXEnvironment*/
11941static const int REVERB_DECAYTIMESCALE;
11942/*!
11943@brief SFXEnvironment::envSize affects reflection level.
11944
11945@see SFXEnvironment::flags
11946
11947@ingroup SFXEnvironment*/
11948static const int REVERB_REFLECTIONSSCALE;
11949/*!
11950@brief SFXEnvironment::envSize affects initial reflection delay time.
11951
11952@see SFXEnvironment::flags
11953
11954@ingroup SFXEnvironment*/
11955static const int REVERB_REFLECTIONSDELAYSCALE;
11956/*!
11957@brief SFXEnvironment::envSize affects reflections level.
11958
11959@see SFXEnvironment::flags
11960
11961@ingroup SFXEnvironment*/
11962static const int REVERB_REVERBSCALE;
11963/*!
11964@brief SFXEnvironment::envSize affects late reverberation delay time.
11965
11966@see SFXEnvironment::flags
11967
11968@ingroup SFXEnvironment*/
11969static const int REVERB_REVERBDELAYSCALE;
11970/*!
11971@brief SFXEnvironment::airAbsorptionHF affects SFXEnvironment::decayHFRatio.
11972
11973@see SFXEnvironment::flags
11974
11975@ingroup SFXEnvironment*/
11976static const int REVERB_DECAYHFLIMIT;
11977/*!
11978@brief SFXEnvironment::envSize affects echo time.
11979
11980@see SFXEnvironment::flags
11981
11982@ingroup SFXEnvironment*/
11983static const int REVERB_ECHOTIMESCALE;
11984/*!
11985@brief SFXEnvironment::envSize affects modulation time.
11986
11987@see SFXEnvironment::flags
11988
11989@ingroup SFXEnvironment*/
11990static const int REVERB_MODULATIONTIMESCALE;
11991/*!
11992@brief PS2 Only - Reverb is applied to CORE0 (hw voices 0-23).
11993
11994@see SFXEnvironment::flags
11995
11996@ingroup SFXEnvironment*/
11997static const int REVERB_CORE0;
11998/*!
11999@brief PS2 Only - Reverb is applied to CORE1 (hw voices 24-47).
12000
12001@see SFXEnvironment::flags
12002
12003@ingroup SFXEnvironment*/
12004static const int REVERB_CORE1;
12005/*!
12006@brief GameCube/Wii Only - Use high-quality reverb.
12007
12008@see SFXEnvironment::flags
12009
12010@ingroup SFXEnvironment*/
12011static const int REVERB_HIGHQUALITYREVERB;
12012/*!
12013@brief GameCube/Wii Only - Use high-quality DPL2 reverb.
12014
12015@see SFXEnvironment::flags
12016
12017@ingroup SFXEnvironment*/
12018static const int REVERB_HIGHQUALITYDPL2REVERB;
12019
12020/*! @name Reverb
12021@{ */
12022/*!
12023@brief Density of reverb environment.
12024*/
12025float reverbDensity;
12026/*!
12027@brief Environment diffusion.
12028*/
12029float reverbDiffusion;
12030/*!
12031@brief Reverb Gain Level.
12032*/
12033float reverbGain;
12034/*!
12035@brief Reverb Gain to high frequencies
12036*/
12037float reverbGainHF;
12038/*!
12039@brief Reverb Gain to high frequencies
12040*/
12041float reverbGainLF;
12042/*!
12043@brief Decay time for the reverb.
12044*/
12045float reverbDecayTime;
12046/*!
12047@brief High frequency decay time ratio.
12048*/
12049float reverbDecayHFRatio;
12050/*!
12051@brief High frequency decay time ratio.
12052*/
12053float reverbDecayLFRatio;
12054/*!
12055@brief Reflection Gain.
12056*/
12057float reflectionsGain;
12058/*!
12059@brief How long to delay reflections.
12060*/
12061float reflectionDelay;
12062/*!
12063@brief Reflection reverberation panning vector.
12064*/
12065float reflectionsPan[ 3 ];
12066/*!
12067@brief Late reverb gain amount.
12068*/
12069float lateReverbGain;
12070/*!
12071@brief Late reverb delay time.
12072*/
12073float lateReverbDelay;
12074/*!
12075@brief Late reverberation panning vector.
12076*/
12077float lateReverbPan[ 3 ];
12078/*!
12079@brief Reverb echo time.
12080*/
12081float reverbEchoTime;
12082/*!
12083@brief Reverb echo depth.
12084*/
12085float reverbEchoDepth;
12086/*!
12087@brief Reverb Modulation time.
12088*/
12089float reverbModTime;
12090/*!
12091@brief Reverb Modulation time.
12092*/
12093float reverbModDepth;
12094/*!
12095@brief High Frequency air absorbtion
12096*/
12097float airAbsorbtionGainHF;
12098/*!
12099@brief Reverb High Frequency Reference.
12100*/
12101float reverbHFRef;
12102/*!
12103@brief Reverb Low Frequency Reference.
12104*/
12105float reverbLFRef;
12106/*!
12107@brief Rolloff factor for reverb.
12108*/
12109float roomRolloffFactor;
12110/*!
12111@brief High Frequency decay limit.
12112*/
12113int decayHFLimit;
12114/// @}
12115
12116
12117/*! @name Ungrouped
12118@{ */
12119/// @}
12120
12121
12122/*! @name Object
12123@{ */
12124/// @}
12125
12126
12127/*! @name Editing
12128@{ */
12129/// @}
12130
12131
12132/*! @name Persistence
12133@{ */
12134/// @}
12135
12136};
12137
12138/*!
12139@brief Abstract base class for sound data that can be played back by the sound system.
12140
12141The term "track" is used in the sound system to refer to any entity that can be played back as a sound source.  These can be individual files (SFXProfile), patterns of other tracks (SFXPlayList), or special sound data defined by a device layer (SFXFMODEvent).
12142
12143Any track must be paired with a SFXDescription that tells the sound system how to set up playback for the track.
12144
12145All objects that are of type SFXTrack will automatically be added to @c SFXTrackSet.
12146
12147@note This class cannot be instantiated directly.
12148
12149@ingroup SFX
12150@ingroup Datablocks
12151
12152*/
12153class SFXTrack : public SimDataBlock {
12154public:
12155
12156/*! @name Callbacks
12157@{ */
12158/// @}
12159
12160
12161/*! @name Sound
12162@{ */
12163/*!
12164@brief Playback setup description for this track.
12165
12166
12167If unassigned, the description named "AudioEffects" will automatically be assigned to the track.  If this description is not defined, track creation will fail.
12168*/
12169SFXDescription description;
12170/*!
12171@brief Parameters to automatically attach to SFXSources created from this track.
12172
12173Individual parameters are identified by their #internalName.
12174*/
12175string parameters[ 8 ];
12176/// @}
12177
12178
12179/*! @name Ungrouped
12180@{ */
12181/// @}
12182
12183
12184/*! @name Object
12185@{ */
12186/// @}
12187
12188
12189/*! @name Editing
12190@{ */
12191/// @}
12192
12193
12194/*! @name Persistence
12195@{ */
12196/// @}
12197
12198};
12199
12200/*!
12201@brief A datablock describing a playback pattern of sounds.
12202
12203Playlists allow to define intricate playback patterns of invidual tracks and thus allow the sound system to be easily used for playing multiple sounds in single operations.
12204
12205As playlists are %SFXTracks, they can thus be used anywhere in the engine where sound data can be assigned.
12206
12207Each playlist can hold a maximum of 16 tracks.  Longer playlists may be constructed by cascading lists, i.e. by creating a playlist that references other playlists.
12208
12209Processing of a single playlist slot progresses in a fixed set of steps that are invariably iterated through for each slot (except the slot is assigned a state and its state is deactivated; in this case, the controller will exit out of the slot directly):
12210
12211<ol>
12212<li><b>delayIn:</b><p>Waits a set amount of time before processing the slot. This is 0 by default and is determined by the #delayTimeIn (seconds to wait) and #delayTimeInVariance (bounds on randomization) properties.</p></li>
12213<li><b>#transitionIn:</b><p>Decides what to do @b before playing the slot.  Defaults to @c None which makes this stage a no-operation.  Alternatively, the slot can be configured to wait for playback of other slots to finish (@c Wait and @c WaitAll) or to stop playback of other slots (@c Stop and @c StopAll). Note that @c Wait and @c Stop always refer to the source that was last started by the list.</p></li>
12214<li><b>play:</b><p><p>Finally, the #track attached to the slot is played. However, this will only @b start playback of the track and then immediately move on to the next stage.  It will @b not wait for the track to finish playing.  Note also that depending on the @c replay setting for the slot, this stage may pick up a source that is already playing on the slot rather than starting a new one.</p> <p>Several slot properties (fade times, min/max distance, and volume/pitch scale) are used in this stage.</p></li>
12215<li><b>delayOut:</b><p>Waits a set amount of time before transitioning out of the slot. This works the same as @c delayIn and is set to 0 by default (i.e. no delay).</p></li>
12216<li><b>#transitionOut:</b><p>Decides what to do @b after playing the slot. This works like #transitionIn.</p></li>
12217</ol>
12218
12219This is a key difference to playlists in normal music players where upon reaching a certain slot, the slot will immediately play and the player then wait for playback to finish before moving on to the next slot.
12220
12221@note Be aware that time limits set on slot delays are soft limits.  The sound system updates sound sources in discrete (and equally system update frequency dependent) intervals which thus determines the granularity at which time-outs can be handled.
12222
12223@section SFXPlayList_randomization Value Randomization
12224
12225For greater variety, many of the values for individual slots may be given a randomization limit that will trigger a dynamic variance of the specified base value.
12226
12227Any given field @c xyz that may be randomized has a corresponding field @c xyzVariance which is a two-dimensional vector.  The first number specifies the greatest value that may be subtracted from the given base value (i.e. the @c xyz field) whereas the second number specifies the greatest value that may be added to the base value.  Between these two limits, a random number is generated.
12228
12229The default variance settings of "0 0" will thus not allow to add or subtract anything from the base value and effectively disable randomization.
12230
12231Randomization is re-evaluated on each cycle through a list.
12232
12233@section SFXPlayList_states Playlists and States
12234
12235A unique aspect of playlists is that they allow their playback to be tied to the changing set of active sound states. This feature enables playlists to basically connect to an extensible state machine that can be leveraged by the game code to signal a multitude of different gameplay states with the audio system then automatically reacting to state transitions.
12236
12237Playlists react to states in three ways:
12238- Before a controller starts processing a slot it checks whether the slot is assigned a #state.  If this is the case, the controller checks whether the particular state is active.  If it is not, the entire slot is skipped.  If it is, the controller goes on to process the slot.
12239- If a controller is in one of the delay stages for a slot that has a #state assigned and the state is deactivated, the controller will stop the delay and skip any of the remaining processing stages for the slot.
12240- Once the play stage has been processed for a slot that has a #state assigned, the slot's #stateMode will determine what happens with the playing sound source if the slot's state is deactivated while the sound is still playing.
12241
12242A simple example of how to make use of states in combination with playlists would be to set up a playlist for background music that reacts to the mood of the current gameplay situation.  For example, during combat, tenser music could play than during normal exploration.  To set this up, different %SFXStates would represent different moods in the game and the background music playlist would have one slot set up for each such mood.  By making use of volume fades and the @c PauseWhenDeactivated #stateMode, smooth transitions between the various audio tracks can be produced.
12243
12244@tsexample
12245// Create a play list from two SFXProfiles.
12246%playList = new SFXPlayList()
12247{
12248   // Use a looped description so the list playback will loop.
12249   description = AudioMusicLoop2D;
12250
12251   track[ 0 ] = Profile1;
12252   track[ 1 ] = Profile2;
12253};
12254
12255// Play the list.
12256sfxPlayOnce( %playList );
12257@endtsexample
12258
12259@ref SFX_interactive
12260
12261@ingroup SFX
12262*/
12263class SFXPlayList : public SFXTrack {
12264public:
12265
12266/*! @name Callbacks
12267@{ */
12268/// @}
12269
12270
12271/*! @name Sound
12272@{ */
12273/*!
12274@brief Slot playback order randomization pattern.
12275
12276By setting this field to something other than "NotRandom" to order in which slots of the playlist are processed can be changed from sequential to a random pattern.  This allows to to create more varied playback patterns.
12277Defaults to "NotRandom".
12278*/
12279SFXPlayListRandomMode random;
12280/*!
12281@brief Behavior when description has looping enabled.
12282
12283The loop mode determines whether the list will loop over a single slot or loop over all the entire list of slots being played.
12284
12285@see SFXDescription::isLooping
12286*/
12287SFXPlayListLoopMode loopMode;
12288/*!
12289@brief Number of slots to play.
12290
12291Up to a maximum of 16, this field determines the number of slots that are taken from the list for playback.  Only slots that have a valid #track assigned will be considered for this.
12292*/
12293int numSlotsToPlay;
12294/*!
12295@brief Track to play in this slot.
12296
12297This must be set for the slot to be considered for playback.  Other settings for a slot will not take effect except this field is set.
12298*/
12299SFXTrack track[ 12 ];
12300/*!
12301@brief Behavior when an already playing sound is encountered on this slot from a previous cycle.
12302
12303Each slot can have an arbitrary number of sounds playing on it from previous cycles.  This field determines how SFXController will handle these sources.
12304*/
12305SFXPlayListReplayMode replay[ 12 ];
12306/*!
12307@brief Behavior when moving into this slot.
12308
12309After the delayIn time has expired (if any), this slot determines what the controller will do before actually playing the slot.
12310*/
12311SFXPlayListTransitionMode transitionIn[ 12 ];
12312/*!
12313@brief Behavior when moving out of this slot.
12314
12315After the #detailTimeOut has expired (if any), this slot determines what the controller will do before moving on to the next slot.
12316*/
12317SFXPlayListTransitionMode transitionOut[ 12 ];
12318/*!
12319@brief Seconds to wait after moving into slot before #transitionIn.
12320*/
12321float delayTimeIn[ 12 ];
12322/*!
12323@brief Bounds on randomization of #delayTimeIn.
12324
12325
12326@ref SFXPlayList_randomization
12327
12328*/
12329Point2F delayTimeInVariance[ 12 ];
12330/*!
12331@brief Seconds to wait before moving out of slot after #transitionOut.
12332*/
12333float delayTimeOut[ 12 ];
12334/*!
12335@brief Bounds on randomization of #delayTimeOut.
12336
12337
12338@ref SFXPlayList_randomization
12339
12340*/
12341Point2F delayTimeOutVariance[ 12 ];
12342/*!
12343@brief Seconds to fade sound in (-1 to use the track's own fadeInTime.)
12344
12345@see SFXDescription::fadeTimeIn
12346*/
12347float fadeTimeIn[ 12 ];
12348/*!
12349@brief Bounds on randomization of #fadeInTime.
12350
12351
12352@ref SFXPlayList_randomization
12353
12354*/
12355Point2F fadeTimeInVariance[ 12 ];
12356/*!
12357@brief Seconds to fade sound out (-1 to use the track's own fadeOutTime.)
12358
12359@see SFXDescription::fadeTimeOut
12360*/
12361float fadeTimeOut[ 12 ];
12362/*!
12363@brief Bounds on randomization of #fadeOutTime
12364
12365
12366@ref SFXPlayList_randomization
12367
12368*/
12369Point2F fadeTimeOutVariance[ 12 ];
12370/*!
12371@brief @c referenceDistance to set for 3D sounds in this slot (<1 to use @c referenceDistance of track's own description).
12372
12373@see SFXDescription::referenceDistance
12374*/
12375float referenceDistance[ 12 ];
12376/*!
12377@brief Bounds on randomization of #referenceDistance.
12378
12379
12380@ref SFXPlayList_randomization
12381
12382*/
12383Point2F referenceDistanceVariance[ 12 ];
12384/*!
12385@brief @c maxDistance to apply to 3D sounds in this slot (<1 to use @c maxDistance of track's own description).
12386
12387@see SFXDescription::maxDistance
12388*/
12389float maxDistance[ 12 ];
12390/*!
12391@brief Bounds on randomization of #maxDistance.
12392
12393
12394@ref SFXPlayList_randomization
12395
12396*/
12397Point2F maxDistanceVariance[ 12 ];
12398/*!
12399@brief Scale factor to apply to volume of sounds played on this list slot.
12400
12401This value will scale the actual volume level set on the track assigned to the slot, i.e. a value of 0.5 will cause the track to play at half-volume.
12402*/
12403float volumeScale[ 12 ];
12404/*!
12405@brief Bounds on randomization of #volumeScale.
12406
12407
12408@ref SFXPlayList_randomization
12409
12410*/
12411Point2F volumeScaleVariance[ 12 ];
12412/*!
12413@brief Scale factor to apply to pitch of sounds played on this list slot.
12414
12415This value will scale the actual pitch set on the track assigned to the slot, i.e. a value of 0.5 will cause the track to play at half its assigned speed.
12416*/
12417float pitchScale[ 12 ];
12418/*!
12419@brief Bounds on randomization of #pitchScale.
12420
12421
12422@ref SFXPlayList_randomization
12423
12424*/
12425Point2F pitchScaleVariance[ 12 ];
12426/*!
12427@brief Number of times to loop this slot.
12428*/
12429int repeatCount[ 12 ];
12430/*!
12431@brief State that must be active for this slot to play.
12432
12433
12434@ref SFXPlayList_states
12435*/
12436SFXState state[ 12 ];
12437/*!
12438@brief Behavior when assigned state is deactivated while slot is playing.
12439
12440
12441@ref SFXPlayList_states
12442*/
12443SFXPlayListStateMode stateMode[ 12 ];
12444/// @}
12445
12446
12447/*! @name Debug
12448@{ */
12449/*!
12450@brief Enable/disable execution tracing for this playlist (local only).
12451
12452If this is true, SFXControllers attached to the list will automatically run in trace mode.
12453*/
12454bool trace;
12455/// @}
12456
12457
12458/*! @name Sound
12459@{ */
12460/// @}
12461
12462
12463/*! @name Ungrouped
12464@{ */
12465/// @}
12466
12467
12468/*! @name Object
12469@{ */
12470/// @}
12471
12472
12473/*! @name Editing
12474@{ */
12475/// @}
12476
12477
12478/*! @name Persistence
12479@{ */
12480/// @}
12481
12482};
12483
12484/*!
12485@brief Encapsulates a single sound file for playback by the sound system.
12486
12487SFXProfile combines a sound description (SFXDescription) with a sound file such that it can be played by the sound system.  To be able to play a sound file, the sound system will always require a profile for it to be created.  However, several of the SFX functions (sfxPlayOnce(), sfxCreateSource()) perform this creation internally for convenience using temporary profile objects.
12488
12489Sound files can be in either OGG or WAV format.  However, extended format support is available when using FMOD. See @ref SFX_formats.
12490
12491@section SFXProfile_loading Profile Loading
12492
12493By default, the sound data referenced by a profile will be loaded when the profile is first played and the data then kept until either the profile is deleted or until the sound device on which the sound data is held is deleted.
12494
12495This initial loading my incur a small delay when the sound is first played.  To avoid this, a profile may be expicitly set to load its sound data immediately when the profile is added to the system.  This is done by setting the #preload property to true.
12496
12497@note Sounds using streamed playback (SFXDescription::isStreaming) cannot be preloaded and will thus ignore the #preload flag.
12498
12499@tsexample
12500datablock SFXProfile( Shore01Snd )
12501{
12502   fileName     = "art/sound/Lakeshore_mono_01";
12503   description  = Shore01Looping3d;
12504   preload      = true;
12505};
12506@endtsexample
12507
12508@ingroup SFX
12509@ingroup Datablocks
12510
12511*/
12512class SFXProfile : public SFXTrack {
12513public:
12514/*!
12515@brief Return the length of the sound data in seconds.
12516
12517
12518@return The length of the sound data in seconds or 0 if the sound referenced by the profile could not be found.*/
12519float getSoundDuration();
12520
12521/*! @name Callbacks
12522@{ */
12523/// @}
12524
12525
12526/*! @name Sound
12527@{ */
12528/*!
12529@brief %Path to the sound file.
12530
12531If the extension is left out, it will be inferred by the sound system.  This allows to easily switch the sound format without having to go through the profiles and change the filenames there, too.
12532
12533*/
12534filename fileName;
12535/*!
12536@brief Whether to preload sound data when the profile is added to system.
12537
12538@note This flag is ignored by streamed sounds.
12539
12540@ref SFXProfile_loading
12541*/
12542bool preload;
12543/// @}
12544
12545
12546/*! @name Sound
12547@{ */
12548/// @}
12549
12550
12551/*! @name Ungrouped
12552@{ */
12553/// @}
12554
12555
12556/*! @name Object
12557@{ */
12558/// @}
12559
12560
12561/*! @name Editing
12562@{ */
12563/// @}
12564
12565
12566/*! @name Persistence
12567@{ */
12568/// @}
12569
12570};
12571
12572/*!
12573@brief Allows legacy AudioProfile datablocks to be treated as SFXProfile datablocks.
12574
12575@ingroup afxMisc
12576@ingroup AFX
12577@ingroup Datablocks
12578
12579*/
12580class AudioProfile : public SFXProfile {
12581public:
12582
12583/*! @name Callbacks
12584@{ */
12585/// @}
12586
12587
12588/*! @name Sound
12589@{ */
12590/// @}
12591
12592
12593/*! @name Sound
12594@{ */
12595/// @}
12596
12597
12598/*! @name Ungrouped
12599@{ */
12600/// @}
12601
12602
12603/*! @name Object
12604@{ */
12605/// @}
12606
12607
12608/*! @name Editing
12609@{ */
12610/// @}
12611
12612
12613/*! @name Persistence
12614@{ */
12615/// @}
12616
12617};
12618
12619/*!
12620@brief Base class responsible for displaying an OS file browser.
12621
12622FileDialog is a platform agnostic dialog interface for querying the user for file locations. It is designed to be used through the exposed scripting interface.
12623
12624FileDialog is the base class for Native File Dialog controls in Torque. It provides these basic areas of functionality:
12625
12626   - Inherits from SimObject and is exposed to the scripting interface
12627   - Provides blocking interface to allow instant return to script execution
12628   - Simple object configuration makes practical use easy and effective
12629
12630FileDialog is *NOT* intended to be used directly in script and is only exposed to script to expose generic file dialog attributes.
12631
12632This base class is usable in TorqueScript, but is does not specify what functionality is intended (open or save?). Its children, OpenFileDialog and SaveFileDialog, do make use of DialogStyle flags and do make use of specific funcationality. These are the preferred classes to use
12633
12634However, the FileDialog base class does contain the key properties and important method for file browing. The most important function is Execute(). This is used by both SaveFileDialog and OpenFileDialog to initiate the browser.
12635
12636@tsexample
12637// NOTE: This is not he preferred class to use, but this still works
12638
12639// Create the file dialog
12640%baseFileDialog = new FileDialog()
12641{
12642   // Allow browsing of all file types
12643   filters = "*.*";
12644
12645   // No default file
12646   defaultFile = ;
12647
12648   // Set default path relative to project
12649   defaultPath = "./";
12650
12651   // Set the title
12652   title = "Durpa";
12653
12654   // Allow changing of path you are browsing
12655   changePath = true;
12656};
12657
12658 // Launch the file dialog
12659 %baseFileDialog.Execute();
12660 
12661 // Don't forget to cleanup
12662 %baseFileDialog.delete();
12663
12664
12665@endtsexample
12666
12667@note FileDialog and its related classes are only availble in a Tools build of Torque.
12668
12669@see OpenFileDialog for a practical example on opening a file
12670@see SaveFileDialog for a practical example of saving a file
12671@ingroup FileSystem
12672
12673*/
12674class FileDialog : public SimObject {
12675public:
12676/*!
12677@brief Launches the OS file browser
12678
12679After an Execute() call, the chosen file name and path is available in one of two areas.  If only a single file selection is permitted, the results will be stored in the @a fileName attribute.
12680
12681If multiple file selection is permitted, the results will be stored in the @a files array.  The total number of files in the array will be stored in the @a fileCount attribute.
12682
12683@tsexample
12684// NOTE: This is not he preferred class to use, but this still works
12685
12686// Create the file dialog
12687%baseFileDialog = new FileDialog()
12688{
12689   // Allow browsing of all file types
12690   filters = "*.*";
12691
12692   // No default file
12693   defaultFile = ;
12694
12695   // Set default path relative to project
12696   defaultPath = "./";
12697
12698   // Set the title
12699   title = "Durpa";
12700
12701   // Allow changing of path you are browsing
12702   changePath = true;
12703};
12704
12705 // Launch the file dialog
12706 %baseFileDialog.Execute();
12707 
12708 // Don't forget to cleanup
12709 %baseFileDialog.delete();
12710
12711
12712 // A better alternative is to use the 
12713 // derived classes which are specific to file open and save
12714
12715 // Create a dialog dedicated to opening files
12716 %openFileDlg = new OpenFileDialog()
12717 {
12718    // Look for jpg image files
12719    // First part is the descriptor|second part is the extension
12720    Filters = "Jepg Files|*.jpg";
12721    // Allow browsing through other folders
12722    ChangePath = true;
12723
12724    // Only allow opening of one file at a time
12725    MultipleFiles = false;
12726 };
12727
12728 // Launch the open file dialog
12729 %result = %openFileDlg.Execute();
12730
12731 // Obtain the chosen file name and path
12732 if ( %result )
12733 {
12734    %seletedFile = %openFileDlg.file;
12735 }
12736 else
12737 {
12738    %selectedFile = "";
12739 }
12740 // Cleanup
12741 %openFileDlg.delete();
12742
12743
12744 // Create a dialog dedicated to saving a file
12745 %saveFileDlg = new SaveFileDialog()
12746 {
12747    // Only allow for saving of COLLADA files
12748    Filters = "COLLADA Files (*.dae)|*.dae|";
12749
12750    // Default save path to where the WorldEditor last saved
12751    DefaultPath = $pref::WorldEditor::LastPath;
12752
12753    // No default file specified
12754    DefaultFile = "";
12755
12756    // Do not allow the user to change to a new directory
12757    ChangePath = false;
12758
12759    // Prompt the user if they are going to overwrite an existing file
12760    OverwritePrompt = true;
12761 };
12762
12763 // Launch the save file dialog
12764 %result = %saveFileDlg.Execute();
12765
12766 // Obtain the file name
12767 %selectedFile = "";
12768 if ( %result )
12769    %selectedFile = %saveFileDlg.file;
12770
12771 // Cleanup
12772 %saveFileDlg.delete();
12773@endtsexample
12774
12775@return True if the file was selected was successfully found (opened) or declared (saved).*/
12776bool Execute();
12777
12778/*! @name Callbacks
12779@{ */
12780/// @}
12781
12782/*!
12783@brief The default directory path when the dialog is shown.
12784*/
12785string defaultPath;
12786/*!
12787@brief The default file path when the dialog is shown.
12788*/
12789string defaultFile;
12790/*!
12791@brief The default file name when the dialog is shown.
12792*/
12793string fileName;
12794/*!
12795@brief The filter string for limiting the types of files visible in the dialog.  It makes use of the pipe symbol '|' as a delimiter.  For example:
12796
12797
12798'All Files|*.*'
12799
12800'Image Files|*.png;*.jpg|Png Files|*.png|Jepg Files|*.jpg'
12801*/
12802string filters;
12803/*!
12804@brief The title for the dialog.
12805*/
12806string title;
12807/*!
12808@brief True/False whether to set the working directory to the directory returned by the dialog.
12809*/
12810bool changePath;
12811/*!
12812@brief True/False whether to the path returned is always made to be relative.
12813*/
12814bool forceRelativePath;
12815
12816/*! @name Ungrouped
12817@{ */
12818/// @}
12819
12820
12821/*! @name Object
12822@{ */
12823/// @}
12824
12825
12826/*! @name Editing
12827@{ */
12828/// @}
12829
12830
12831/*! @name Persistence
12832@{ */
12833/// @}
12834
12835};
12836
12837/*!
12838@brief Derived from FileDialog, this class is responsible for opening a file browser with the intention of opening a file.
12839
12840The core usage of this dialog is to locate a file in the OS and return the path and name. This does not handle the actual file parsing or data manipulation. That functionality is left up to the FileObject class.
12841
12842@tsexample
12843 // Create a dialog dedicated to opening files
12844 %openFileDlg = new OpenFileDialog()
12845 {
12846    // Look for jpg image files
12847    // First part is the descriptor|second part is the extension
12848    Filters = "Jepg Files|*.jpg";
12849    // Allow browsing through other folders
12850    ChangePath = true;
12851
12852    // Only allow opening of one file at a time
12853    MultipleFiles = false;
12854 };
12855
12856 // Launch the open file dialog
12857 %result = %openFileDlg.Execute();
12858
12859 // Obtain the chosen file name and path
12860 if ( %result )
12861 {
12862    %seletedFile = %openFileDlg.file;
12863 }
12864 else
12865 {
12866    %selectedFile = "";
12867 }
12868
12869 // Cleanup
12870 %openFileDlg.delete();
12871
12872
12873@endtsexample
12874
12875@note FileDialog and its related classes are only availble in a Tools build of Torque.
12876
12877@see FileDialog
12878@see SaveFileDialog
12879@see FileObject
12880@ingroup FileSystem
12881
12882*/
12883class OpenFileDialog : public FileDialog {
12884public:
12885
12886/*! @name Callbacks
12887@{ */
12888/// @}
12889
12890/*!
12891@brief True/False whether the file returned must exist or not
12892*/
12893bool MustExist;
12894/*!
12895@brief True/False whether multiple files may be selected and returned or not
12896*/
12897bool MultipleFiles;
12898
12899/*! @name Ungrouped
12900@{ */
12901/// @}
12902
12903
12904/*! @name Object
12905@{ */
12906/// @}
12907
12908
12909/*! @name Editing
12910@{ */
12911/// @}
12912
12913
12914/*! @name Persistence
12915@{ */
12916/// @}
12917
12918};
12919
12920/*!
12921@brief Derived from FileDialog, this class is responsible for opening a file browser with the intention of saving a file.
12922
12923The core usage of this dialog is to locate a file in the OS and return the path and name. This does not handle the actual file writing or data manipulation. That functionality is left up to the FileObject class.
12924
12925@tsexample
12926 // Create a dialog dedicated to opening file
12927 %saveFileDlg = new SaveFileDialog()
12928 {
12929    // Only allow for saving of COLLADA files
12930    Filters        = "COLLADA Files (*.dae)|*.dae|";
12931
12932    // Default save path to where the WorldEditor last saved
12933    DefaultPath    = $pref::WorldEditor::LastPath;
12934
12935    // No default file specified
12936    DefaultFile    = "";
12937
12938    // Do not allow the user to change to a new directory
12939    ChangePath     = false;
12940
12941    // Prompt the user if they are going to overwrite an existing file
12942    OverwritePrompt   = true;
12943 };
12944
12945 // Launch the save file dialog
12946 %saveFileDlg.Execute();
12947
12948 if ( %result )
12949 {
12950    %seletedFile = %openFileDlg.file;
12951 }
12952 else
12953 {
12954    %selectedFile = "";
12955 }
12956
12957 // Cleanup
12958 %saveFileDlg.delete();
12959@endtsexample
12960
12961@note FileDialog and its related classes are only availble in a Tools build of Torque.
12962
12963@see FileDialog
12964@see OpenFileDialog
12965@see FileObject
12966@ingroup FileSystem
12967
12968*/
12969class SaveFileDialog : public FileDialog {
12970public:
12971
12972/*! @name Callbacks
12973@{ */
12974/// @}
12975
12976/*!
12977@brief True/False whether the dialog should prompt before accepting an existing file name
12978*/
12979bool OverwritePrompt;
12980
12981/*! @name Ungrouped
12982@{ */
12983/// @}
12984
12985
12986/*! @name Object
12987@{ */
12988/// @}
12989
12990
12991/*! @name Editing
12992@{ */
12993/// @}
12994
12995
12996/*! @name Persistence
12997@{ */
12998/// @}
12999
13000};
13001
13002/*!
13003@brief OS level dialog used for browsing folder structures.
13004
13005This is essentially an OpenFileDialog, but only used for returning directory paths, not files.
13006
13007@note FileDialog and its related classes are only availble in a Tools build of Torque.
13008
13009@see OpenFileDialog for more details on functionality.
13010
13011@ingroup FileSystem
13012
13013*/
13014class OpenFolderDialog : public OpenFileDialog {
13015public:
13016
13017/*! @name Callbacks
13018@{ */
13019/// @}
13020
13021/*!
13022@brief File that must be in selected folder for it to be valid
13023*/
13024filename fileMustExist;
13025
13026/*! @name Ungrouped
13027@{ */
13028/// @}
13029
13030
13031/*! @name Object
13032@{ */
13033/// @}
13034
13035
13036/*! @name Editing
13037@{ */
13038/// @}
13039
13040
13041/*! @name Persistence
13042@{ */
13043/// @}
13044
13045};
13046
13047class ScriptMsgListener : public SimObject {
13048public:
13049
13050/*! @name Callbacks
13051@{ */
13052/*!
13053@brief Script callback when a listener is first created and registered.
13054
13055
13056@tsexample
13057function ScriptMsgListener::onAdd(%this)
13058{
13059   // Perform on add code here
13060}
13061@endtsexample
13062
13063*/
13064void onAdd();
13065/*!
13066@brief Script callback when a listener is deleted.
13067
13068
13069@tsexample
13070function ScriptMsgListener::onRemove(%this)
13071{
13072   // Perform on remove code here
13073}
13074@endtsexample
13075
13076*/
13077void onRemove();
13078/*!
13079@brief Called when the listener has received a message.
13080
13081@param queue The name of the queue the message was dispatched to
13082@param event The name of the event (function) that was triggered
13083@param data The data (parameters) for the message
13084
13085@return false to prevent other listeners receiving this message, true otherwise
13086*/
13087bool onMessageReceived( string queue, string event, string data );
13088/*!
13089@brief Called when a message object (not just the message data) is passed to a listener.
13090
13091@param queue The name of the queue the message was dispatched to
13092@param msg The message object
13093@return false to prevent other listeners receiving this message, true otherwise
13094@see Message
13095@see onMessageReceived*/
13096bool onMessageObjectReceived( string queue, Message  msg );
13097/*!
13098@brief Callback for when the listener is added to a queue
13099
13100The default implementation of onAddToQueue() and onRemoveFromQueue() provide tracking of the queues this listener is added to through the mQueues member. Overrides of onAddToQueue() or onRemoveFromQueue() should ensure they call the parent implementation in any overrides.
13101@param queue The name of the queue that the listener added to
13102@see onRemoveFromQueue()*/
13103void onAddToQueue( string queue );
13104/*!
13105@brief Callback for when the listener is removed from a queue
13106
13107The default implementation of onAddToQueue() and onRemoveFromQueue() provide tracking of the queues this listener is added to through the mQueues member. Overrides of onAddToQueue() or onRemoveFromQueue() should ensure they call the parent implementation in any overrides.
13108@param queue The name of the queue that the listener was removed from
13109@see onAddToQueue()*/
13110void onRemoveFromQueue( string queue );
13111/// @}
13112
13113
13114/*! @name Ungrouped
13115@{ */
13116/// @}
13117
13118
13119/*! @name Object
13120@{ */
13121/// @}
13122
13123
13124/*! @name Editing
13125@{ */
13126/// @}
13127
13128
13129/*! @name Persistence
13130@{ */
13131/// @}
13132
13133};
13134
13135/*!
13136@brief Forward messages from one queue to another
13137
13138MessageForwarder is a script class that can be used to forward messages from one queue to another.
13139
13140@tsexample
13141%fwd = new MessageForwarder()
13142{
13143   toQueue = "QueueToSendTo";
13144};
13145
13146registerMessageListener("FromQueue", %fwd);
13147@endtsexample
13148
13149Where "QueueToSendTo" is the queue you want to forward to, and "FromQueue" is the queue you want to forward from.
13150
13151@ingroup Messaging
13152
13153*/
13154class MessageForwarder : public ScriptMsgListener {
13155public:
13156
13157/*! @name Callbacks
13158@{ */
13159/// @}
13160
13161/*!
13162@brief Name of queue to forward to
13163*/
13164caseString toQueue;
13165
13166/*! @name Ungrouped
13167@{ */
13168/// @}
13169
13170
13171/*! @name Object
13172@{ */
13173/// @}
13174
13175
13176/*! @name Editing
13177@{ */
13178/// @}
13179
13180
13181/*! @name Persistence
13182@{ */
13183/// @}
13184
13185};
13186
13187/*!
13188@brief A state block description for rendering.
13189
13190This object is used with ShaderData in CustomMaterial and PostEffect to define the render state.
13191@tsexample
13192singleton GFXStateBlockData( PFX_DOFDownSampleStateBlock )
13193{
13194   zDefined = true;
13195   zEnable = false;
13196   zWriteEnable = false;
13197
13198   samplersDefined = true;
13199   samplerStates[0] = SamplerClampLinear;
13200   samplerStates[1] = SamplerClampPoint;
13201
13202   // Copy the clamped linear sampler, but change
13203   // the u coord to wrap for this special case.
13204   samplerStates[2] = new GFXSamplerStateData( : SamplerClampLinear )
13205   {
13206      addressModeU = GFXAddressWrap;
13207   };
13208};
13209@endtsexample
13210@note The 'xxxxDefined' fields are used to know what groups of fields are modified when combining multiple state blocks in material processing.  You should take care to enable the right ones when setting values.
13211@ingroup GFX
13212
13213*/
13214class GFXStateBlockData : public SimObject {
13215public:
13216
13217/*! @name Callbacks
13218@{ */
13219/// @}
13220
13221
13222/*! @name Alpha Blending
13223@{ */
13224/*!
13225@brief Set to true if the alpha blend state is not all defaults.
13226*/
13227bool blendDefined;
13228/*!
13229@brief Enables alpha blending.  The default is false.
13230*/
13231bool blendEnable;
13232/*!
13233@brief The source blend state.  The default is GFXBlendOne.
13234*/
13235GFXBlend blendSrc;
13236/*!
13237@brief The destination blend state.  The default is GFXBlendZero.
13238*/
13239GFXBlend blendDest;
13240/*!
13241@brief The arithmetic operation applied to alpha blending.  The default is GFXBlendOpAdd.
13242*/
13243GFXBlendOp blendOp;
13244/// @}
13245
13246
13247/*! @name Separate Alpha Blending
13248@{ */
13249/*!
13250@brief Set to true if the seperate alpha blend state is not all defaults.
13251*/
13252bool separateAlphaBlendDefined;
13253/*!
13254@brief Enables the separate blend mode for the alpha channel.  The default is false.
13255*/
13256bool separateAlphaBlendEnable;
13257/*!
13258@brief The source blend state.  The default is GFXBlendOne.
13259*/
13260GFXBlend separateAlphaBlendSrc;
13261/*!
13262@brief The destination blend state.  The default is GFXBlendZero.
13263*/
13264GFXBlend separateAlphaBlendDest;
13265/*!
13266@brief The arithmetic operation applied to separate alpha blending.  The default is GFXBlendOpAdd.
13267*/
13268GFXBlendOp separateAlphaBlendOp;
13269/// @}
13270
13271
13272/*! @name Alpha Test
13273@{ */
13274/*!
13275@brief Set to true if the alpha test state is not all defaults.
13276*/
13277bool alphaDefined;
13278/*!
13279@brief Enables per-pixel alpha testing.  The default is false.
13280*/
13281bool alphaTestEnable;
13282/*!
13283@brief The test function used to accept or reject a pixel based on its alpha value.  The default is GFXCmpGreaterEqual.
13284*/
13285GFXCmpFunc alphaTestFunc;
13286/*!
13287@brief The reference alpha value against which pixels are tested.  The default is zero.
13288*/
13289int alphaTestRef;
13290/// @}
13291
13292
13293/*! @name Color Write
13294@{ */
13295/*!
13296@brief Set to true if the color write state is not all defaults.
13297*/
13298bool colorWriteDefined;
13299/*!
13300@brief Enables red channel writes.  The default is true.
13301*/
13302bool colorWriteRed;
13303/*!
13304@brief Enables blue channel writes.  The default is true.
13305*/
13306bool colorWriteBlue;
13307/*!
13308@brief Enables green channel writes.  The default is true.
13309*/
13310bool colorWriteGreen;
13311/*!
13312@brief Enables alpha channel writes.  The default is true.
13313*/
13314bool colorWriteAlpha;
13315/// @}
13316
13317
13318/*! @name Culling
13319@{ */
13320/*!
13321@brief Set to true if the culling state is not all defaults.
13322*/
13323bool cullDefined;
13324/*!
13325@brief Defines how back facing triangles are culled if at all.  The default is GFXCullCCW.
13326*/
13327GFXCullMode cullMode;
13328/// @}
13329
13330
13331/*! @name Depth
13332@{ */
13333/*!
13334@brief Set to true if the depth state is not all defaults.
13335*/
13336bool zDefined;
13337/*!
13338@brief Enables z-buffer reads.  The default is true.
13339*/
13340bool zEnable;
13341/*!
13342@brief Enables z-buffer writes.  The default is true.
13343*/
13344bool zWriteEnable;
13345/*!
13346@brief The depth comparision function which a pixel must pass to be written to the z-buffer.  The default is GFXCmpLessEqual.
13347*/
13348GFXCmpFunc zFunc;
13349/*!
13350@brief A floating-point bias used when comparing depth values.  The default is zero.
13351*/
13352float zBias;
13353/*!
13354@brief An additional floating-point bias based on the maximum depth slop of the triangle being rendered.  The default is zero.
13355*/
13356float zSlopeBias;
13357/// @}
13358
13359
13360/*! @name Stencil
13361@{ */
13362/*!
13363@brief Set to true if the stencil state is not all defaults.
13364*/
13365bool stencilDefined;
13366/*!
13367@brief Enables stenciling.  The default is false.
13368*/
13369bool stencilEnable;
13370/*!
13371@brief The stencil operation to perform if the stencil test fails.  The default is GFXStencilOpKeep.
13372*/
13373GFXStencilOp stencilFailOp;
13374/*!
13375@brief The stencil operation to perform if the stencil test passes and the depth test fails.  The default is GFXStencilOpKeep.
13376*/
13377GFXStencilOp stencilZFailOp;
13378/*!
13379@brief The stencil operation to perform if both the stencil and the depth tests pass.  The default is GFXStencilOpKeep.
13380*/
13381GFXStencilOp stencilPassOp;
13382/*!
13383@brief The comparison function to test the reference value to a stencil buffer entry.  The default is GFXCmpNever.
13384*/
13385GFXCmpFunc stencilFunc;
13386/*!
13387@brief The reference value for the stencil test.  The default is zero.
13388*/
13389int stencilRef;
13390/*!
13391@brief The mask applied to the reference value and each stencil buffer entry to determine the significant bits for the stencil test. The default is 0xFFFFFFFF.
13392*/
13393int stencilMask;
13394/*!
13395@brief The write mask applied to values written into the stencil buffer. The default is 0xFFFFFFFF.
13396*/
13397int stencilWriteMask;
13398/// @}
13399
13400
13401/*! @name Fixed Function
13402@{ */
13403/*!
13404@brief Enables fixed function vertex coloring when rendering without a shader.  The default is false.
13405*/
13406bool vertexColorEnable;
13407/// @}
13408
13409
13410/*! @name Sampler States
13411@{ */
13412/*!
13413@brief Set to true if the sampler states are not all defaults.
13414*/
13415bool samplersDefined;
13416/*!
13417@brief The array of texture sampler states.
13418
13419@note Not all graphics devices support 16 samplers.  In general all systems support 4 samplers with most modern cards doing 8.
13420*/
13421GFXSamplerStateData samplerStates[ 16 ];
13422/*!
13423@brief The color used for multiple-texture blending with the GFXTATFactor texture-blending argument or the GFXTOPBlendFactorAlpha texture-blending operation.  The default is opaque white (255, 255, 255, 255).
13424*/
13425ColorI textureFactor;
13426/// @}
13427
13428
13429/*! @name Ungrouped
13430@{ */
13431/// @}
13432
13433
13434/*! @name Object
13435@{ */
13436/// @}
13437
13438
13439/*! @name Editing
13440@{ */
13441/// @}
13442
13443
13444/*! @name Persistence
13445@{ */
13446/// @}
13447
13448};
13449
13450/*!
13451@brief A sampler state used by GFXStateBlockData.
13452
13453The samplers define how a texture will be sampled when used from the shader or fixed function device
13454@tsexample
13455singleton GFXSamplerStateData(SamplerClampLinear)
13456{
13457   textureColorOp = GFXTOPModulate;
13458   addressModeU = GFXAddressClamp;
13459   addressModeV = GFXAddressClamp;
13460   addressModeW = GFXAddressClamp;
13461   magFilter = GFXTextureFilterLinear;
13462   minFilter = GFXTextureFilterLinear;
13463   mipFilter = GFXTextureFilterLinear;
13464};
13465@endtsexample
13466There are a few predefined samplers in the core scripts which you can use with GFXStateBlockData for the most common rendering cases:
13467  - SamplerClampLinear
13468  - SamplerClampPoint
13469  - SamplerWrapLinear
13470  - SamplerWrapPoint
13471
13472@see GFXStateBlockData
13473@ingroup GFX
13474
13475*/
13476class GFXSamplerStateData : public SimObject {
13477public:
13478
13479/*! @name Callbacks
13480@{ */
13481/// @}
13482
13483
13484/*! @name Ungrouped
13485@{ */
13486/// @}
13487
13488
13489/*! @name Object
13490@{ */
13491/// @}
13492
13493
13494/*! @name Editing
13495@{ */
13496/// @}
13497
13498
13499/*! @name Persistence
13500@{ */
13501/// @}
13502
13503
13504/*! @name Address Mode
13505@{ */
13506/*!
13507@brief The texture address mode for the u coordinate.  The default is GFXAddressWrap.
13508*/
13509GFXTextureAddressMode addressModeU;
13510/*!
13511@brief The texture address mode for the v coordinate.  The default is GFXAddressWrap.
13512*/
13513GFXTextureAddressMode addressModeV;
13514/*!
13515@brief The texture address mode for the w coordinate.  The default is GFXAddressWrap.
13516*/
13517GFXTextureAddressMode addressModeW;
13518/// @}
13519
13520
13521/*! @name Filter State
13522@{ */
13523/*!
13524@brief The texture magnification filter.  The default is GFXTextureFilterLinear.
13525*/
13526GFXTextureFilterType magFilter;
13527/*!
13528@brief The texture minification filter.  The default is GFXTextureFilterLinear.
13529*/
13530GFXTextureFilterType minFilter;
13531/*!
13532@brief The texture mipmap filter used during minification.  The default is GFXTextureFilterLinear.
13533*/
13534GFXTextureFilterType mipFilter;
13535/*!
13536@brief The mipmap level of detail bias.  The default value is zero.
13537*/
13538float mipLODBias;
13539/*!
13540@brief The maximum texture anisotropy.  The default value is 1.
13541*/
13542int maxAnisotropy;
13543/// @}
13544
13545/*!
13546@brief Compares sampled data against existing sampled data.  The default is GFXCmpNever.
13547*/
13548GFXCmpFunc samplerFunc;
13549};
13550
13551/*!
13552@brief Base class for all Gui control objects.
13553
13554GuiControl is the basis for the Gui system.  It represents an individual control that can be placed on the canvas and with which the mouse and keyboard can potentially interact with.
13555
13556@section GuiControl_Hierarchy Control Hierarchies
13557GuiControls are arranged in a hierarchy.  All children of a control are placed in their parent's coordinate space, i.e. their coordinates are relative to the upper left corner of their immediate parent.  When a control is moved, all its child controls are moved along with it.
13558
13559Since GuiControl's are SimGroups, hierarchy also implies ownership.  This means that if a control is destroyed, all its children are destroyed along with it.  It also means that a given control can only be part of a single GuiControl hierarchy.  When adding a control to another control, it will automatically be reparented from another control it may have previously been parented to.
13560
13561@section GuiControl_Layout Layout System
13562GuiControls have a two-dimensional position and are rectangular in shape.
13563
13564@section GuiControl_Events Event System
13565@section GuiControl_Profiles Control Profiles
13566Common data accessed by GuiControls is stored in so-called "Control Profiles."  This includes font, color, and texture information. By pooling this data in shared objects, the appearance of any number of controls can be changed quickly and easily by modifying only the shared profile object.
13567
13568If not explicitly assigned a profile, a control will by default look for a profile object that matches its class name.  This means that the class GuiMyCtrl, for example, will look for a profile called 'GuiMyProfile'.  If this profile cannot be found, the control will fall back to GuiDefaultProfile which must be defined in any case for the Gui system to work.
13569
13570In addition to its primary profile, a control may be assigned a second profile called 'tooltipProfile' that will be used to render tooltip popups for the control.
13571
13572@section GuiControl_Actions Triggered Actions
13573@section GuiControl_FirstResponders First Responders
13574At any time, a single control can be what is called the "first responder" on the GuiCanvas is placed on.  This control will be the first control to receive keyboard events not bound in the global ActionMap.  If the first responder choses to handle a particular keyboard event, 
13575
13576@section GuiControl_Waking Waking and Sleeping
13577@section GuiControl_VisibleActive Visibility and Activeness
13578By default, a GuiControl is active which means that it
13579
13580@see GuiCanvas
13581@see GuiControlProfile
13582@ingroup GuiCore
13583
13584*/
13585class GuiControl : public SimGroup {
13586public:
13587/*!
13588@brief Resize the control to the given dimensions.
13589
13590Child controls with resize according to their layout settings.
13591@param p The new ( width, height ) extents of the control.*/
13592
13593void setExtent( Point2I p );
13594/*!
13595@brief Resize the control to the given dimensions.
13596
13597Child controls will resize according to their layout settings.
13598@param width The new width of the control in pixels.
13599@param height The new height of the control in pixels.*/
13600
13601void setExtent( S32 width, S32 height );
13602/*!
13603@brief Find the topmost child control located at the given coordinates.
13604
13605@note Only children that are both visible and have the 'modal' flag set in their profile will be considered in the search.@param x The X coordinate in the control's own coordinate space.
13606@param y The Y coordinate in the control's own coordinate space.
13607@return The topmost child control at the given coordintes or the control on which the method was called if no matching child could be found.
13608@see GuiControlProfile::modal
13609@see findHitControls*/
13610GuiControl findHitControl( int x, int y );
13611/*!
13612@brief Find all visible child controls that intersect with the given rectangle.
13613
13614@note Invisible child controls will not be included in the search.
13615@param x The X coordinate of the rectangle's upper left corner in the control's own coordinate space.
13616@param y The Y coordinate of the rectangle's upper left corner in the control's own coordinate space.
13617@param width The width of the search rectangle in pixels.
13618@param height The height of the search rectangle in pixels.
13619@return A space-separated list of the IDs of all visible control objects intersecting the given rectangle.
13620
13621@tsexample
13622// Lock all controls in the rectangle at x=10 and y=10 and the extent width=100 and height=100.
13623foreach$( %ctrl in %this.findHitControls( 10, 10, 100, 100 ) )
13624   %ctrl.setLocked( true );
13625@endtsexample
13626@see findHitControl*/
13627string findHitControls( int x, int y, int width, int height );
13628/*!
13629@brief Test whether the given control is a direct or indirect child to this control.
13630
13631@param control The potential child control.
13632@return True if the given control is a direct or indirect child to this control.*/
13633bool controlIsChild( GuiControl control );
13634/*!
13635@brief Test whether the control is the current first responder.
13636
13637@return True if the control is the current first responder.
13638@see makeFirstResponder
13639@see setFirstResponder
13640@ref GuiControl_FirstResponders*/
13641bool isFirstResponder();
13642/*!
13643@brief Make this control the current first responder.
13644
13645@note Only controls with a profile that has canKeyFocus enabled are able to become first responders.
13646@see GuiControlProfile::canKeyFocus
13647@see isFirstResponder
13648@ref GuiControl_FirstResponders*/
13649void setFirstResponder();
13650/*!
13651@brief Get the first responder set on this GuiControl tree.
13652
13653@return The first responder set on the control's subtree.
13654@see isFirstResponder
13655@see makeFirstResponder
13656@see setFirstResponder
13657@ref GuiControl_FirstResponders*/
13658GuiControl getFirstResponder();
13659/*!
13660@brief Clear this control from being the first responder in its hierarchy chain.
13661
13662@param ignored Ignored.  Supported for backwards-compatibility.
13663*/
13664void clearFirstResponder( bool ignored=false );
13665/*!
13666@brief Test whether the given point lies within the rectangle of the control.
13667
13668@param x X coordinate of the point in parent-relative coordinates.
13669@param y Y coordinate of the point in parent-relative coordinates.
13670@return True if the point is within the control, false if not.
13671@see getExtent
13672@see getPosition
13673*/
13674bool pointInControl( int x, int y );
13675/*!
13676@brief Add the given control as a child to this control.
13677
13678This is synonymous to calling SimGroup::addObject.
13679@param control The control to add as a child.
13680@note The control will retain its current position and size.
13681@see SimGroup::addObject
13682@ref GuiControl_Hierarchy
13683*/
13684void addGuiControl( GuiControl control );
13685/*!
13686@brief Get the canvas on which the control is placed.
13687
13688@return The canvas on which the control's hierarchy is currently placed or 0 if the control is not currently placed on a GuiCanvas.
13689@see GuiControl_Hierarchy
13690*/
13691GuiCanvas getRoot();
13692/*!
13693@brief Get the immediate parent control of the control.
13694
13695@return The immediate parent GuiControl or 0 if the control is not parented to a GuiControl.
13696*/
13697GuiControl getParent();
13698/*!
13699@brief Indicates if the mouse is locked in this control.
13700
13701@return True if the mouse is currently locked.
13702*/
13703bool isMouseLocked();
13704/*!
13705@brief Set the value associated with the control.
13706
13707@param value The new value for the control.
13708*/
13709void setValue( string value );
13710/*!
13711@brief Get the value associated with the control.
13712
13713@return value for the control.
13714*/
13715string getValue();
13716/*!
13717@brief Make this control the first responder.
13718
13719@param isFirst True to make first responder, false to not.
13720*/
13721void makeFirstResponder( bool isFirst );
13722/*!
13723@brief Check if this control is active or not.
13724
13725@return True if it's active, false if not.
13726*/
13727bool isActive();
13728/*!
13729@brief Set the control as active or inactive.@param state True to set the control as active, false to set it as inactive.
13730
13731*/
13732void setActive( bool state=true );
13733/*!
13734@brief Test whether the control is currently set to be visible.
13735
13736@return True if the control is currently set to be visible.@note This method does not tell anything about whether the control is actually visible to the user at the moment.
13737
13738@ref GuiControl_VisibleActive*/
13739bool isVisible();
13740/*!
13741@brief Set whether the control is visible or not.
13742
13743@param state The new visiblity flag state for the control.
13744@ref GuiControl_VisibleActive*/
13745void setVisible( bool state=true );
13746/*!
13747@brief Test whether the control is currently awake.
13748
13749If a control is awake it means that it is part of the GuiControl hierarchy of a GuiCanvas.
13750@return True if the control is awake.@ref GuiControl_Waking*/
13751bool isAwake();
13752/*!
13753@brief Set the control profile for the control to use.
13754
13755The profile used by a control determines a great part of its behavior and appearance.
13756@param profile The new profile the control should use.
13757@ref GuiControl_Profiles*/
13758void setProfile( GuiControlProfile profile );
13759/*!
13760@brief Resize and reposition the control using the give coordinates and dimensions.  Child controls will resize according to their layout behaviors.
13761
13762@param x The new X coordinate of the control in its parent's coordinate space.
13763@param y The new Y coordinate of the control in its parent's coordinate space.
13764@param width The new width to which the control should be resized.
13765@param height The new height to which the control should be resized.*/
13766void resize( int x, int y, int width, int height );
13767/*!
13768@brief Get the control's current position relative to its parent.
13769
13770@return The coordinate of the control in its parent's coordinate space.*/
13771Point2I getPosition();
13772/*!
13773@brief Get the coordinate of the control's center point relative to its parent.
13774
13775@return The coordinate of the control's center point in parent-relative coordinates.*/
13776Point2I getCenter();
13777/*!
13778@brief Set the control's position by its center point.
13779
13780@param x The X coordinate of the new center point of the control relative to the control's parent.
13781@param y The Y coordinate of the new center point of the control relative to the control's parent.*/
13782void setCenter( int x, int y );
13783/*!
13784@brief Get the coordinate of the control's center point in coordinates relative to the root control in its control hierarchy.
13785
13786@Return the center coordinate of the control in root-relative coordinates.
13787*/
13788Point2I getGlobalCenter();
13789/*!
13790@brief Get the position of the control relative to the root of the GuiControl hierarchy it is contained in.
13791
13792@return The control's current position in root-relative coordinates.*/
13793Point2I getGlobalPosition();
13794/*!
13795@brief Set position of the control relative to the root of the GuiControl hierarchy it is contained in.
13796
13797@param x The new X coordinate of the control relative to the root's upper left corner.
13798@param y The new Y coordinate of the control relative to the root's upper left corner.*/
13799void setPositionGlobal( int x, int y );
13800/*!
13801@brief Position the control in the local space of the parent control.
13802
13803@param x The new X coordinate of the control relative to its parent's upper left corner.
13804@param y The new Y coordinate of the control relative to its parent's upper left corner.*/
13805void setPosition( int x, int y );
13806/*!
13807@brief Get the width and height of the control.
13808
13809@return A point structure containing the width of the control in x and the height in y.*/
13810Point2I getExtent();
13811/*!
13812@brief Get the minimum allowed size of the control.
13813
13814@return The minimum size to which the control can be shrunk.
13815@see minExtent*/
13816Point2I getMinExtent();
13817/*!
13818@brief Get the aspect ratio of the control's extents.
13819
13820@return The width of the control divided by its height.
13821@see getExtent*/
13822float getAspect();
13823
13824/*! @name Callbacks
13825@{ */
13826/*!
13827@brief Called when the control object is registered with the system after the control has been created.
13828
13829*/
13830void onAdd();
13831/*!
13832@brief Called when the control object is removed from the system before it is deleted.
13833
13834*/
13835void onRemove();
13836/*!
13837@brief Called when the control is woken up.
13838
13839@ref GuiControl_Waking*/
13840void onWake();
13841/*!
13842@brief Called when the control is put to sleep.
13843
13844@ref GuiControl_Waking*/
13845void onSleep();
13846/*!
13847@brief Called when the control gains first responder status on the GuiCanvas.
13848
13849@see setFirstResponder
13850@see makeFirstResponder
13851@see isFirstResponder
13852@ref GuiControl_FirstResponders*/
13853void onGainFirstResponder();
13854/*!
13855@brief Called when the control loses first responder status on the GuiCanvas.
13856
13857@see setFirstResponder
13858@see makeFirstResponder
13859@see isFirstResponder
13860@ref GuiControl_FirstResponders*/
13861void onLoseFirstResponder();
13862/*!
13863@brief Called when the control's associated action is triggered and no 'command' is defined for the control.
13864
13865@ref GuiControl_Actions*/
13866void onAction();
13867/*!
13868@brief Called when the control changes its visibility state, i.e. when going from visible to invisible or vice versa.
13869
13870@param state The new visibility state.
13871@see isVisible
13872@see setVisible
13873@ref GuiControl_VisibleActive*/
13874void onVisible( bool state );
13875/*!
13876@brief Called when the control changes its activeness state, i.e. when going from active to inactive or vice versa.
13877
13878@param stat The new activeness state.
13879@see isActive
13880@see setActive
13881@ref GuiControl_VisibleActive*/
13882void onActive( bool state );
13883/*!
13884@brief Called when the control is pushed as a dialog onto the canvas.
13885
13886@see GuiCanvas::pushDialog*/
13887void onDialogPush();
13888/*!
13889@brief Called when the control is removed as a dialog from the canvas.
13890
13891@see GuiCanvas::popDialog*/
13892void onDialogPop();
13893/*!
13894@brief Called when a drag&drop operation through GuiDragAndDropControl has entered the control.  This is only called for topmost visible controls as the GuiDragAndDropControl moves over them.
13895
13896
13897@param control The payload of the drag operation.
13898@param dropPoint The point at which the payload would be dropped if it were released now.  Relative to the canvas.*/
13899void onControlDragEnter( GuiControl control, Point2I dropPoint );
13900/*!
13901@brief Called when a drag&drop operation through GuiDragAndDropControl has exited the control and moved over a different control.  This is only called for topmost visible controls as the GuiDragAndDropControl moves off of them.
13902
13903
13904@param control The payload of the drag operation.
13905@param dropPoint The point at which the payload would be dropped if it were released now.  Relative to the canvas.*/
13906void onControlDragExit( GuiControl control, Point2I dropPoint );
13907/*!
13908@brief Called when a drag&drop operation through GuiDragAndDropControl is moving across the control after it has entered it.  This is only called for topmost visible controls as the GuiDragAndDropControl moves across them.
13909
13910
13911@param control The payload of the drag operation.
13912@param dropPoint The point at which the payload would be dropped if it were released now.  Relative to the canvas.*/
13913void onControlDragged( GuiControl control, Point2I dropPoint );
13914/*!
13915@brief Called when a drag&drop operation through GuiDragAndDropControl has completed and is dropping its payload onto the control.  This is only called for topmost visible controls as the GuiDragAndDropControl drops its payload on them.
13916
13917
13918@param control The control that is being dropped onto this control.
13919@param dropPoint The point at which the control is being dropped.  Relative to the canvas.*/
13920void onControlDropped( GuiControl control, Point2I dropPoint );
13921/// @}
13922
13923
13924/*! @name Layout
13925@{ */
13926/*!
13927@brief The position relative to the parent control.
13928*/
13929Point2I position;
13930/*!
13931@brief The width and height of the control.
13932*/
13933Point2I extent;
13934/*!
13935@brief The minimum width and height of the control. The control will not be resized smaller than this.
13936*/
13937Point2I minExtent;
13938/*!
13939@brief The horizontal resizing behavior.
13940*/
13941GuiHorizontalSizing horizSizing;
13942/*!
13943@brief The vertical resizing behavior.
13944*/
13945GuiVerticalSizing vertSizing;
13946/// @}
13947
13948
13949/*! @name Control
13950@{ */
13951/*!
13952@brief The control profile that determines fill styles, font settings, etc.
13953*/
13954GuiControlProfile profile;
13955/*!
13956@brief Whether the control is visible or hidden.
13957*/
13958bool visible;
13959/*!
13960@brief Whether the control is enabled for user interaction.
13961*/
13962bool active;
13963/*!
13964@deprecated This member is deprecated and its value is always undefined.
13965*/
13966deprecated modal;
13967/*!
13968@deprecated This member is deprecated and its value is always undefined.
13969*/
13970deprecated setFirstResponder;
13971/*!
13972@brief Name of the variable to which the value of this control will be synchronized.
13973*/
13974string variable;
13975/*!
13976@brief Command to execute on the primary action of the control.
13977
13978
13979@note Within this script snippet, the control on which the #command is being executed is bound to the global variable $ThisControl.
13980*/
13981string command;
13982/*!
13983@brief Command to execute on the secondary action of the control.
13984
13985
13986@note Within this script snippet, the control on which the #altCommand is being executed is bound to the global variable $ThisControl.
13987*/
13988string altCommand;
13989/*!
13990@brief Key combination that triggers the control's primary action when the control is on the canvas.
13991*/
13992string accelerator;
13993/// @}
13994
13995
13996/*! @name ToolTip
13997@{ */
13998/*!
13999@brief Control profile to use when rendering tooltips for this control.
14000*/
14001GuiControlProfile tooltipProfile;
14002/*!
14003@brief String to show in tooltip for this control.
14004*/
14005string tooltip;
14006/*!
14007@brief Time for mouse to hover over control until tooltip is shown (in milliseconds).
14008*/
14009int hovertime;
14010/// @}
14011
14012
14013/*! @name Editing
14014@{ */
14015/*!
14016@brief If true, the control may contain child controls.
14017*/
14018bool isContainer;
14019/// @}
14020
14021
14022/*! @name Localization
14023@{ */
14024/*!
14025@brief Name of string table to use for lookup of internationalized text.
14026*/
14027string langTableMod;
14028/// @}
14029
14030
14031/*! @name Ungrouped
14032@{ */
14033/// @}
14034
14035
14036/*! @name Object
14037@{ */
14038/// @}
14039
14040
14041/*! @name Editing
14042@{ */
14043/// @}
14044
14045
14046/*! @name Persistence
14047@{ */
14048/// @}
14049
14050};
14051
14052/*!
14053@brief The base class for the various button controls.
14054
14055This is the base class for the various types of button controls.  If no more specific functionality is required than offered by this class, then it can be instantiated and used directly.  Otherwise, its subclasses should be used:
14056- GuiRadioCtrl (radio buttons)
14057- GuiCheckBoxCtrl (checkboxes)
14058- GuiButtonCtrl (push buttons with text labels)
14059- GuiBitmapButtonCtrl (bitmapped buttons)
14060- GuiBitmapButtonTextCtrl (bitmapped buttons with a text label)
14061- GuiToggleButtonCtrl (toggle buttons, i.e. push buttons with "sticky" behavior)
14062- GuiSwatchButtonCtrl (color swatch buttons)
14063- GuiBorderButtonCtrl (push buttons for surrounding child controls)
14064
14065@ingroup GuiButtons
14066*/
14067class GuiButtonBaseCtrl : public GuiControl {
14068public:
14069/*!
14070@brief Simulate a click on the button.
14071
14072This method will trigger the button's action just as if the button had been pressed by the user.
14073
14074*/
14075void performClick();
14076/*!
14077@brief Set the text displayed on the button's label.
14078
14079@param text The text to display as the button's text label.
14080@note Not all buttons render text labels.
14081
14082@see getText
14083@see setTextID
14084*/
14085void setText( string text );
14086/*!
14087@brief Set the text displayed on the button's label using a string from the string table assigned to the control.
14088
14089
14090@param id Name of the variable that contains the integer string ID.  Used to look up string in table.
14091
14092@note Not all buttons render text labels.
14093
14094@see setText
14095@see getText
14096@see GuiControl::langTableMod
14097@see LangTable
14098
14099@ref Gui_i18n*/
14100void setTextID( string id );
14101/*!
14102@brief Get the text display on the button's label (if any).
14103
14104
14105@return The button's label.*/
14106string getText();
14107/*!
14108@brief For toggle or radio buttons, set whether the button is currently activated or not.  For radio buttons, toggling a button on will toggle all other radio buttons in its group to off.
14109
14110
14111@param isOn If true, the button will be toggled on (if not already); if false, it will be toggled off.
14112
14113@note Toggling the state of a button with this method will <em>not</em> not trigger the action associated with the button.  To do that, use performClick().*/
14114void setStateOn( bool isOn=true );
14115/*!
14116@brief Reset the mousing state of the button.
14117
14118
14119This method should not generally be called.*/
14120void resetState();
14121
14122/*! @name Callbacks
14123@{ */
14124/*!
14125@brief If #useMouseEvents is true, this is called when the left mouse button is pressed on an (active) button.
14126
14127*/
14128void onMouseDown();
14129/*!
14130@brief If #useMouseEvents is true, this is called when the left mouse button is release over an (active) button.
14131
14132
14133@note To trigger actions, better use onClick() since onMouseUp() will also be called when the mouse was not originally pressed on the button.*/
14134void onMouseUp();
14135/*!
14136@brief Called when the primary action of the button is triggered (e.g. by a left mouse click).
14137
14138*/
14139void onClick();
14140/*!
14141@brief Called when the left mouse button is double-clicked on the button.
14142
14143*/
14144void onDoubleClick();
14145/*!
14146@brief Called when the right mouse button is clicked on the button.
14147
14148*/
14149void onRightClick();
14150/*!
14151@brief If #useMouseEvents is true, this is called when the mouse cursor moves over the button (only if the button is the front-most visible control, though).
14152
14153*/
14154void onMouseEnter();
14155/*!
14156@brief If #useMouseEvents is true, this is called when the mouse cursor moves off the button (only if the button had previously received an onMouseEvent() event).
14157
14158*/
14159void onMouseLeave();
14160/*!
14161@brief If #useMouseEvents is true, this is called when a left mouse button drag is detected, i.e. when the user pressed the left mouse button on the control and then moves the mouse over a certain distance threshold with the mouse button still pressed.
14162
14163*/
14164void onMouseDragged();
14165/// @}
14166
14167
14168/*! @name Button
14169@{ */
14170/*!
14171@brief Text label to display on button (if button class supports text labels).
14172*/
14173caseString text;
14174/*!
14175@brief ID of string in string table to use for text label on button.
14176
14177
14178@see setTextID
14179@see GuiControl::langTableMod
14180@see LangTable
14181
14182
14183*/
14184string textID;
14185/*!
14186@brief Radio button toggle group number.  All radio buttons that are assigned the same #groupNum and that are parented to the same control will synchronize their toggle state, i.e. if one radio button is toggled on all other radio buttons in its group will be toggled off.
14187
14188
14189The default group is -1.
14190*/
14191int groupNum;
14192/*!
14193@brief Button behavior type.
14194
14195
14196*/
14197GuiButtonType buttonType;
14198/*!
14199@brief If true, mouse events will be passed on to script.  Default is false.
14200
14201
14202*/
14203bool useMouseEvents;
14204/// @}
14205
14206
14207/*! @name Layout
14208@{ */
14209/// @}
14210
14211
14212/*! @name Control
14213@{ */
14214/// @}
14215
14216
14217/*! @name ToolTip
14218@{ */
14219/// @}
14220
14221
14222/*! @name Editing
14223@{ */
14224/// @}
14225
14226
14227/*! @name Localization
14228@{ */
14229/// @}
14230
14231
14232/*! @name Ungrouped
14233@{ */
14234/// @}
14235
14236
14237/*! @name Object
14238@{ */
14239/// @}
14240
14241
14242/*! @name Editing
14243@{ */
14244/// @}
14245
14246
14247/*! @name Persistence
14248@{ */
14249/// @}
14250
14251};
14252
14253/*!
14254@brief The most widely used button class.
14255
14256GuiButtonCtrl renders seperately of, but utilizes all of the functionality of GuiBaseButtonCtrl.
14257This grants GuiButtonCtrl the versatility to be either of the 3 button types.
14258
14259@tsexample
14260// Create a PushButton GuiButtonCtrl that calls randomFunction when clicked
14261%button = new GuiButtonCtrl()
14262{
14263   profile    = "GuiButtonProfile";
14264   buttonType = "PushButton";
14265   command    = "randomFunction();";
14266};
14267@endtsexample
14268
14269@ingroup GuiButtons
14270*/
14271class GuiButtonCtrl : public GuiButtonBaseCtrl {
14272public:
14273
14274/*! @name Callbacks
14275@{ */
14276/// @}
14277
14278
14279/*! @name Button
14280@{ */
14281/// @}
14282
14283
14284/*! @name Layout
14285@{ */
14286/// @}
14287
14288
14289/*! @name Control
14290@{ */
14291/// @}
14292
14293
14294/*! @name ToolTip
14295@{ */
14296/// @}
14297
14298
14299/*! @name Editing
14300@{ */
14301/// @}
14302
14303
14304/*! @name Localization
14305@{ */
14306/// @}
14307
14308
14309/*! @name Ungrouped
14310@{ */
14311/// @}
14312
14313
14314/*! @name Object
14315@{ */
14316/// @}
14317
14318
14319/*! @name Editing
14320@{ */
14321/// @}
14322
14323
14324/*! @name Persistence
14325@{ */
14326/// @}
14327
14328};
14329
14330/*!
14331@brief A button that renders its various states (mouse over, pushed, etc.) from separate bitmaps.
14332
14333A bitmapped button is a push button that uses one or more texture images for rendering its individual states.
14334
14335To find the individual textures associated with the button, a naming scheme is used.  For each state a suffix is appended to the texture file name given in the GuiBitmapButtonCtrl::bitmap field:
14336- "_n": Normal state.  This one will be active when no other state applies.
14337- "_h": Highlighted state.  This applies when the mouse is hovering over the button.
14338- "_d": Depressed state.  This applies when the left mouse button has been clicked on the button but not yet released.
14339- "_i": Inactive state.  This applies when the button control has been deactivated (GuiControl::setActive())
14340
14341If a bitmap for a particular state cannot be found, the default bitmap will be used.  To disable all state-based bitmap functionality, set useStates to false which will make the control solely render from the bitmap specified in the bitmap field.
14342
14343@section guibitmapbutton_modifiers Per-Modifier Button Actions
14344If GuiBitmapButtonCtrl::useModifiers is set to true, per-modifier button actions and textures are enabled.  This functionality allows to associate different images and different actions with a button depending on which modifiers are pressed on the keyboard by the user.
14345
14346When enabled, this functionality alters the texture lookup above by prepending the following strings to the suffixes listed above:
14347- "": Default.  No modifier is pressed.
14348- "_ctrl": Image to use when CTRL/CMD is down.
14349- "_alt": Image to use when ALT is down.
14350- "_shift": Image to use when SHIFT is down
14351
14352When this functionality is enabled, a new set of callbacks is used:
14353- onDefaultClick: Button was clicked without a modifier being presssed.
14354- onCtrlClick: Button was clicked with the CTRL/CMD key down.
14355- onAltClick: Button was clicked with the ALT key down.
14356- onShiftClick: Button was clicked with the SHIFT key down.
14357
14358GuiControl::command or GuiControl::onAction() still work as before when per-modifier functionality is enabled.
14359
14360Note that modifiers cannot be mixed.  If two or more modifiers are pressed, a single one will take precedence over the remaining modifiers.  The order of precedence corresponds to the order listed above.
14361
14362@tsexample
14363// Create an OK button that will trigger an onOk() call on its parent when clicked:
14364%okButton = new GuiBitmapButtonCtrl()
14365{
14366   bitmap = "art/gui/okButton";
14367   autoFitExtents = true;
14368   command = "$ThisControl.getParent().onOk();";
14369};
14370@endtsexample
14371
14372@ingroup GuiButtons
14373*/
14374class GuiBitmapButtonCtrl : public GuiButtonCtrl {
14375public:
14376/*!
14377@brief Set the bitmap to show on the button.
14378
14379@param path Path to the texture file in any of the supported formats.
14380*/
14381void setBitmap( string path );
14382
14383/*! @name Callbacks
14384@{ */
14385/*!
14386@brief Called when per-modifier functionality is enabled and the user clicks on the button without any modifier pressed.
14387
14388@ref guibitmapbutton_modifiers*/
14389void onDefaultClick();
14390/*!
14391@brief Called when per-modifier functionality is enabled and the user clicks on the button with the CTRL key pressed.
14392
14393@ref guibitmapbutton_modifiers*/
14394void onCtrlClick();
14395/*!
14396@brief Called when per-modifier functionality is enabled and the user clicks on the button with the ALT key pressed.
14397
14398@ref guibitmapbutton_modifiers*/
14399void onAltClick();
14400/*!
14401@brief Called when per-modifier functionality is enabled and the user clicks on the button with the SHIFT key pressed.
14402
14403@ref guibitmapbutton_modifiers*/
14404void onShiftClick();
14405/// @}
14406
14407
14408/*! @name Bitmap
14409@{ */
14410/*!
14411@brief Texture file to display on this button.
14412
14413If useStates is false, this will be the file that renders on the control.  Otherwise, this will specify the default texture name to which the various state and modifier suffixes are appended to find the per-state and per-modifier (if enabled) textures.
14414*/
14415filename bitmap;
14416/*!
14417@brief Behavior for fitting the bitmap to the control extents.
14418
14419If set to 'Stretched', the bitmap will be stretched both verticall and horizontally to fit inside the control's extents.
14420
14421If set to 'Centered', the bitmap will stay at its original resolution centered in the control's rectangle (getting clipped if the control is smaller than the texture).
14422*/
14423GuiBitmapMode bitmapMode;
14424/*!
14425@brief If true, the control's extents will be set to match the bitmap's extents when setting the bitmap.
14426
14427The bitmap extents will always be taken from the default/normal bitmap (in case the extents of the various bitmaps do not match up.)
14428*/
14429bool autoFitExtents;
14430/*!
14431@brief If true, per-modifier button functionality is enabled.
14432
14433@ref guibitmapbutton_modifiers
14434*/
14435bool useModifiers;
14436/*!
14437@brief If true, per-mouse state button functionality is enabled.
14438
14439Defaults to true.
14440
14441If you do not use per-state images on this button set this to false to speed up the loading process by inhibiting searches for the individual images.
14442*/
14443bool useStates;
14444/*!
14445@brief Use alpha masking for interaction.
14446*/
14447bool masked;
14448/// @}
14449
14450
14451/*! @name Button
14452@{ */
14453/// @}
14454
14455
14456/*! @name Layout
14457@{ */
14458/// @}
14459
14460
14461/*! @name Control
14462@{ */
14463/// @}
14464
14465
14466/*! @name ToolTip
14467@{ */
14468/// @}
14469
14470
14471/*! @name Editing
14472@{ */
14473/// @}
14474
14475
14476/*! @name Localization
14477@{ */
14478/// @}
14479
14480
14481/*! @name Ungrouped
14482@{ */
14483/// @}
14484
14485
14486/*! @name Object
14487@{ */
14488/// @}
14489
14490
14491/*! @name Editing
14492@{ */
14493/// @}
14494
14495
14496/*! @name Persistence
14497@{ */
14498/// @}
14499
14500};
14501
14502/*!
14503@brief An extension of GuiBitmapButtonCtrl that additionally renders a text label on the bitmapped button.
14504
14505The text for the label is taken from the GuiButtonBaseCtrl::text property.
14506
14507For rendering, the label is placed, relative to the control's upper left corner, at the text offset specified in the control's profile (GuiControlProfile::textOffset) and justified according to the profile's setting (GuiControlProfile::justify).
14508
14509@see GuiControlProfile::textOffset
14510@see GuiControlProfile::justify
14511@ingroup GuiButtons
14512*/
14513class GuiBitmapButtonTextCtrl : public GuiBitmapButtonCtrl {
14514public:
14515
14516/*! @name Callbacks
14517@{ */
14518/// @}
14519
14520
14521/*! @name Bitmap
14522@{ */
14523/// @}
14524
14525
14526/*! @name Button
14527@{ */
14528/// @}
14529
14530
14531/*! @name Layout
14532@{ */
14533/// @}
14534
14535
14536/*! @name Control
14537@{ */
14538/// @}
14539
14540
14541/*! @name ToolTip
14542@{ */
14543/// @}
14544
14545
14546/*! @name Editing
14547@{ */
14548/// @}
14549
14550
14551/*! @name Localization
14552@{ */
14553/// @}
14554
14555
14556/*! @name Ungrouped
14557@{ */
14558/// @}
14559
14560
14561/*! @name Object
14562@{ */
14563/// @}
14564
14565
14566/*! @name Editing
14567@{ */
14568/// @}
14569
14570
14571/*! @name Persistence
14572@{ */
14573/// @}
14574
14575};
14576
14577/*!
14578@brief A push button that renders only a border.
14579
14580A border button consists of a border rendered along its extents according to the border thickness defined in its profile (GuiControlProfile::border).  For the border color, a color is selected from the profile according to current button state:
14581- Default state: GuiControlProfile::borderColor
14582- Highlighted (mouse is over the button): GuiControlProfile::fontColorHL
14583- Depressed (mouse button down but not yet released): GuiControlProfile::fontColorSEL
14584@ingroup GuiButtons
14585
14586*/
14587class GuiBorderButtonCtrl : public GuiButtonBaseCtrl {
14588public:
14589
14590/*! @name Callbacks
14591@{ */
14592/// @}
14593
14594
14595/*! @name Button
14596@{ */
14597/// @}
14598
14599
14600/*! @name Layout
14601@{ */
14602/// @}
14603
14604
14605/*! @name Control
14606@{ */
14607/// @}
14608
14609
14610/*! @name ToolTip
14611@{ */
14612/// @}
14613
14614
14615/*! @name Editing
14616@{ */
14617/// @}
14618
14619
14620/*! @name Localization
14621@{ */
14622/// @}
14623
14624
14625/*! @name Ungrouped
14626@{ */
14627/// @}
14628
14629
14630/*! @name Object
14631@{ */
14632/// @}
14633
14634
14635/*! @name Editing
14636@{ */
14637/// @}
14638
14639
14640/*! @name Persistence
14641@{ */
14642/// @}
14643
14644};
14645
14646/*!
14647@brief A named checkbox that can be toggled on and off.
14648
14649A GuiCheckBoxCtrl displays a text label next to a checkbox that can be toggled on and off by the user. Checkboxes are usually used to present boolean choices like, for example, a switch to toggle fullscreen video on and off.
14650
14651@tsexample
14652// Create a checkbox that allows to toggle fullscreen on and off.
14653new GuiCheckBoxCtrl( FullscreenToggle )
14654{
14655   text = "Fullscreen";
14656};
14657
14658// Set the initial state to match the current fullscreen setting.
14659FullscreenToggle.setStateOn( Canvas.isFullscreen() );
14660
14661// Define function to be called when checkbox state is toggled.
14662function FullscreenToggle::onClick( %this )
14663{
14664   Canvas.toggleFullscreen();
14665}
14666@endtsexample
14667
14668@ingroup GuiButtons
14669*/
14670class GuiCheckBoxCtrl : public GuiButtonBaseCtrl {
14671public:
14672/*!
14673@brief Set whether the checkbox is ticked or not.
14674
14675@param newState If true the box will be checked, if false, it will be unchecked.
14676
14677@note This method will @b not trigger the command associated with the control.  To toggle the checkbox state as if the user had clicked the control, use performClick().*/
14678void setStateOn( bool newState );
14679/*!
14680@brief Test whether the checkbox is currently checked.
14681
14682@return True if the checkbox is currently ticked, false otherwise.
14683*/
14684bool isStateOn();
14685
14686/*! @name Callbacks
14687@{ */
14688/// @}
14689
14690
14691/*! @name Button
14692@{ */
14693/// @}
14694
14695
14696/*! @name Layout
14697@{ */
14698/// @}
14699
14700
14701/*! @name Control
14702@{ */
14703/// @}
14704
14705
14706/*! @name ToolTip
14707@{ */
14708/// @}
14709
14710
14711/*! @name Editing
14712@{ */
14713/// @}
14714
14715
14716/*! @name Localization
14717@{ */
14718/// @}
14719
14720
14721/*! @name Ungrouped
14722@{ */
14723/// @}
14724
14725
14726/*! @name Object
14727@{ */
14728/// @}
14729
14730
14731/*! @name Editing
14732@{ */
14733/// @}
14734
14735
14736/*! @name Persistence
14737@{ */
14738/// @}
14739
14740};
14741
14742/*!
14743@brief A button based around the radio concept.
14744
14745GuiRadioCtrl's functionality is based around GuiButtonBaseCtrl's ButtonTypeRadio type.
14746
14747A button control with a radio box and a text label.
14748This control is used in groups where multiple radio buttons
14749present a range of options out of which one can be chosen.
14750A radio button automatically signals its siblings when it is
14751toggled on.
14752
14753@tsexample
14754// Create a GuiCheckBoxCtrl that calls randomFunction with its current value when clicked.
14755%radio = new GuiRadioCtrl()
14756{
14757   profile = "GuiRadioProfile";
14758};
14759@endtsexample
14760
14761@ingroup GuiButtons
14762*/
14763class GuiRadioCtrl : public GuiCheckBoxCtrl {
14764public:
14765
14766/*! @name Callbacks
14767@{ */
14768/// @}
14769
14770
14771/*! @name Button
14772@{ */
14773/// @}
14774
14775
14776/*! @name Layout
14777@{ */
14778/// @}
14779
14780
14781/*! @name Control
14782@{ */
14783/// @}
14784
14785
14786/*! @name ToolTip
14787@{ */
14788/// @}
14789
14790
14791/*! @name Editing
14792@{ */
14793/// @}
14794
14795
14796/*! @name Localization
14797@{ */
14798/// @}
14799
14800
14801/*! @name Ungrouped
14802@{ */
14803/// @}
14804
14805
14806/*! @name Object
14807@{ */
14808/// @}
14809
14810
14811/*! @name Editing
14812@{ */
14813/// @}
14814
14815
14816/*! @name Persistence
14817@{ */
14818/// @}
14819
14820};
14821
14822/*!
14823@brief Deprecated gui control.
14824
14825@deprecated GuiToggleButtonCtrl's functionality is solely based on GuiButtonBaseCtrl's ButtonTypeCheck type.
14826
14827@see GuiButtonCtrl
14828@see GuiCheckBoxCtrl
14829@ingroup GuiButtons
14830*/
14831class GuiToggleButtonCtrl : public GuiButtonCtrl {
14832public:
14833
14834/*! @name Callbacks
14835@{ */
14836/// @}
14837
14838
14839/*! @name Button
14840@{ */
14841/// @}
14842
14843
14844/*! @name Layout
14845@{ */
14846/// @}
14847
14848
14849/*! @name Control
14850@{ */
14851/// @}
14852
14853
14854/*! @name ToolTip
14855@{ */
14856/// @}
14857
14858
14859/*! @name Editing
14860@{ */
14861/// @}
14862
14863
14864/*! @name Localization
14865@{ */
14866/// @}
14867
14868
14869/*! @name Ungrouped
14870@{ */
14871/// @}
14872
14873
14874/*! @name Object
14875@{ */
14876/// @}
14877
14878
14879/*! @name Editing
14880@{ */
14881/// @}
14882
14883
14884/*! @name Persistence
14885@{ */
14886/// @}
14887
14888};
14889
14890/*!
14891@brief Brief Desc.
14892
14893@tsexample
14894// Comment:
14895%okButton = new ClassObject()
14896instantiation
14897@endtsexample
14898
14899@ingroup GuiContainers
14900*/
14901class GuiContainer : public GuiControl {
14902public:
14903
14904/*! @name Callbacks
14905@{ */
14906/// @}
14907
14908
14909/*! @name Layout
14910@{ */
14911/*!
14912*/
14913GuiDockingType docking;
14914/*!
14915*/
14916RectSpacingI margin;
14917/*!
14918*/
14919RectSpacingI padding;
14920/*!
14921*/
14922bool anchorTop;
14923/*!
14924*/
14925bool anchorBottom;
14926/*!
14927*/
14928bool anchorLeft;
14929/*!
14930*/
14931bool anchorRight;
14932/// @}
14933
14934
14935/*! @name Layout
14936@{ */
14937/// @}
14938
14939
14940/*! @name Control
14941@{ */
14942/// @}
14943
14944
14945/*! @name ToolTip
14946@{ */
14947/// @}
14948
14949
14950/*! @name Editing
14951@{ */
14952/// @}
14953
14954
14955/*! @name Localization
14956@{ */
14957/// @}
14958
14959
14960/*! @name Ungrouped
14961@{ */
14962/// @}
14963
14964
14965/*! @name Object
14966@{ */
14967/// @}
14968
14969
14970/*! @name Editing
14971@{ */
14972/// @}
14973
14974
14975/*! @name Persistence
14976@{ */
14977/// @}
14978
14979};
14980
14981/*!
14982@brief Brief Desc.
14983
14984@tsexample
14985// Comment:
14986%okButton = new ClassObject()
14987instantiation
14988@endtsexample
14989
14990@ingroup GuiContainers
14991*/
14992class GuiControlArrayControl : public GuiControl {
14993public:
14994
14995/*! @name Callbacks
14996@{ */
14997/// @}
14998
14999
15000/*! @name Array
15001@{ */
15002/*!
15003@brief Number of colums in the array.
15004*/
15005int colCount;
15006/*!
15007@brief Size of each individual column.
15008*/
15009intList colSizes;
15010/*!
15011@brief Heigth of a row in the array.
15012*/
15013int rowSize;
15014/*!
15015@brief Padding to put between rows.
15016*/
15017int rowSpacing;
15018/*!
15019@brief Padding to put between columns.
15020*/
15021int colSpacing;
15022/// @}
15023
15024
15025/*! @name Layout
15026@{ */
15027/// @}
15028
15029
15030/*! @name Control
15031@{ */
15032/// @}
15033
15034
15035/*! @name ToolTip
15036@{ */
15037/// @}
15038
15039
15040/*! @name Editing
15041@{ */
15042/// @}
15043
15044
15045/*! @name Localization
15046@{ */
15047/// @}
15048
15049
15050/*! @name Ungrouped
15051@{ */
15052/// @}
15053
15054
15055/*! @name Object
15056@{ */
15057/// @}
15058
15059
15060/*! @name Editing
15061@{ */
15062/// @}
15063
15064
15065/*! @name Persistence
15066@{ */
15067/// @}
15068
15069};
15070
15071/*!
15072@brief The GuiPanel panel is a container that when opaque will draw a left to right gradient using its profile fill and fill highlight colors.
15073
15074@tsexample
15075// Mandatory GuiDefaultProfile
15076// Contains the fill color information required by a GuiPanel
15077// Some values left out for sake of this example
15078new GuiControlProfile (GuiDefaultProfile)
15079{
15080   // fill color
15081   opaque = false;
15082   fillColor = "242 241 240";
15083   fillColorHL ="228 228 235";
15084   fillColorSEL = "98 100 137";
15085   fillColorNA = "255 255 255 ";
15086};
15087
15088new GuiPanel(TestPanel)
15089{
15090   position = "45 33";
15091   extent = "342 379";
15092   minExtent = "16 16";
15093   horizSizing = "right";
15094   vertSizing = "bottom";
15095   profile = "GuiDefaultProfile"; // Color fill info is in this profile
15096   isContainer = "1";
15097};
15098@endtsexample
15099
15100@see GuiControlProfile
15101@ingroup GuiContainers
15102
15103*/
15104class GuiPanel : public GuiContainer {
15105public:
15106
15107/*! @name Callbacks
15108@{ */
15109/// @}
15110
15111
15112/*! @name Layout
15113@{ */
15114/// @}
15115
15116
15117/*! @name Layout
15118@{ */
15119/// @}
15120
15121
15122/*! @name Control
15123@{ */
15124/// @}
15125
15126
15127/*! @name ToolTip
15128@{ */
15129/// @}
15130
15131
15132/*! @name Editing
15133@{ */
15134/// @}
15135
15136
15137/*! @name Localization
15138@{ */
15139/// @}
15140
15141
15142/*! @name Ungrouped
15143@{ */
15144/// @}
15145
15146
15147/*! @name Object
15148@{ */
15149/// @}
15150
15151
15152/*! @name Editing
15153@{ */
15154/// @}
15155
15156
15157/*! @name Persistence
15158@{ */
15159/// @}
15160
15161};
15162
15163/*!
15164@brief A window with a title bar and an optional set of buttons.
15165
15166The GuiWindowCtrl class implements windows that can be freely placed within the render window.  Additionally, the windows can be resized and maximized/minimized.
15167
15168@tsexample
15169new GuiWindowCtrl( MyWindow )
15170{
15171   text = "My Window"; // The text that is displayed on the title bar.
15172   resizeWidth = true; // Allow horizontal resizing by user via mouse.
15173   resizeHeight = true; // Allow vertical resizing by user via mouse.
15174   canClose = true; // Display a close button in the title bar.
15175   canMinimize = true; // Display a minimize button in the title bar.
15176   canMaximize = true; // Display a maximize button in the title bar.
15177};
15178@endtsexample
15179
15180@ingroup GuiContainers
15181*/
15182class GuiWindowCtrl : public GuiContainer {
15183public:
15184/*!
15185@brief Bring the window to the front.
15186
15187*/
15188void selectWindow();
15189/*!
15190@brief Set the window's collapsing state.
15191
15192*/
15193void setCollapseGroup( bool state );
15194/*!
15195@brief Toggle the window collapsing.
15196
15197*/
15198void toggleCollapseGroup();
15199void attachTo( GuiWindowCtrl window );
15200/*!
15201@brief Attach @a bottomWindow to @topWindow so that @a bottomWindow moves along with @a topWindow when it is dragged.
15202
15203
15204@param bottomWindow 
15205@param topWindow */
15206static void attach( GuiWindowCtrl bottomWindow, GuiWindowCtrl topWindow );
15207
15208/*! @name Callbacks
15209@{ */
15210/*!
15211@brief Called when the close button has been pressed.
15212
15213*/
15214void onClose();
15215/*!
15216@brief Called when the window has been minimized.
15217
15218*/
15219void onMinimize();
15220/*!
15221@brief Called when the window has been maximized.
15222
15223*/
15224void onMaximize();
15225/*!
15226@brief Called when the window is collapsed by clicking its title bar.
15227
15228*/
15229void onCollapse();
15230/*!
15231@brief Called when the window is restored from minimized, maximized, or collapsed state.
15232
15233*/
15234void onRestore();
15235/// @}
15236
15237
15238/*! @name Window
15239@{ */
15240/*!
15241@brief Text label to display in titlebar.
15242*/
15243string text;
15244/*!
15245@brief Whether the window can be resized horizontally.
15246*/
15247bool resizeWidth;
15248/*!
15249@brief Whether the window can be resized vertically.
15250*/
15251bool resizeHeight;
15252/*!
15253@brief Whether the window can be moved by dragging its titlebar.
15254*/
15255bool canMove;
15256/*!
15257@brief Whether the window has a close button.
15258*/
15259bool canClose;
15260/*!
15261@brief Whether the window has a minimize button.
15262*/
15263bool canMinimize;
15264/*!
15265@brief Whether the window has a maximize button.
15266*/
15267bool canMaximize;
15268/*!
15269@brief Whether the window can be collapsed by clicking its title bar.
15270*/
15271bool canCollapse;
15272/*!
15273@brief Script code to execute when the window is closed.
15274*/
15275string closeCommand;
15276/*!
15277@brief If true, the window will snap to the edges of other windows when moved close to them.
15278*/
15279bool edgeSnap;
15280/// @}
15281
15282
15283/*! @name Layout
15284@{ */
15285/// @}
15286
15287
15288/*! @name Layout
15289@{ */
15290/// @}
15291
15292
15293/*! @name Control
15294@{ */
15295/// @}
15296
15297
15298/*! @name ToolTip
15299@{ */
15300/// @}
15301
15302
15303/*! @name Editing
15304@{ */
15305/// @}
15306
15307
15308/*! @name Localization
15309@{ */
15310/// @}
15311
15312
15313/*! @name Ungrouped
15314@{ */
15315/// @}
15316
15317
15318/*! @name Object
15319@{ */
15320/// @}
15321
15322
15323/*! @name Editing
15324@{ */
15325/// @}
15326
15327
15328/*! @name Persistence
15329@{ */
15330/// @}
15331
15332};
15333
15334/*!
15335@brief A gui control that is used to display an image.
15336
15337The image is stretched to the constraints of the control by default. However, the control can also
15338tile the image as well.
15339
15340The image itself is stored inside the GuiBitmapCtrl::bitmap field. The boolean value that decides
15341whether the image is stretched or tiled is stored inside the GuiBitmapCtrl::wrap field.
15342@tsexample
15343// Create a tiling GuiBitmapCtrl that displays "myImage.png"
15344%bitmapCtrl = new GuiBitmapCtrl()
15345{
15346   bitmap = "myImage.png";
15347   wrap = "true";
15348};
15349@endtsexample
15350
15351@ingroup GuiControls
15352*/
15353class GuiBitmapCtrl : public GuiControl {
15354public:
15355/*!
15356@brief Assign an image to the control.
15357
15358Child controls will resize according to their layout settings.
15359@param filename The filename of the image.
15360@param resize A boolean value that decides whether the ctrl refreshes or not.*/
15361
15362void setBitmap( String filename );
15363/*!
15364@brief Assign an image to the control.
15365
15366Child controls with resize according to their layout settings.
15367@param filename The filename of the image.
15368@param resize Optional parameter. If true, the GUI will resize to fit the image.*/
15369
15370void setBitmap( String filename, bool resize );
15371/*!
15372@brief Set the offset of the bitmap within the control.
15373
15374@param x The x-axis offset of the image.
15375@param y The y-axis offset of the image.
15376*/
15377void setValue( int x, int y );
15378/*!
15379@brief Set a texture as the image.
15380
15381@param namedtexture The name of the texture (NamedTexTarget).
15382@return true if the texture exists.*/
15383bool setNamedTexture( String namedtexture );
15384
15385/*! @name Callbacks
15386@{ */
15387/// @}
15388
15389
15390/*! @name Bitmap
15391@{ */
15392/*!
15393@brief The bitmap file to display in the control.
15394*/
15395filename bitmap;
15396/*!
15397@brief color mul
15398*/
15399ColorI color;
15400/*!
15401@brief If true, the bitmap is tiled inside the control rather than stretched to fit.
15402*/
15403bool wrap;
15404/// @}
15405
15406
15407/*! @name Layout
15408@{ */
15409/// @}
15410
15411
15412/*! @name Control
15413@{ */
15414/// @}
15415
15416
15417/*! @name ToolTip
15418@{ */
15419/// @}
15420
15421
15422/*! @name Editing
15423@{ */
15424/// @}
15425
15426
15427/*! @name Localization
15428@{ */
15429/// @}
15430
15431
15432/*! @name Ungrouped
15433@{ */
15434/// @}
15435
15436
15437/*! @name Object
15438@{ */
15439/// @}
15440
15441
15442/*! @name Editing
15443@{ */
15444/// @}
15445
15446
15447/*! @name Persistence
15448@{ */
15449/// @}
15450
15451};
15452
15453/*! UNDOCUMENTED!
15454@ingroup UNDOCUMENTED
15455 */
15456class GuiBitmapBarCtrl : public GuiBitmapCtrl {
15457public:
15458
15459/*! @name Callbacks
15460@{ */
15461/// @}
15462
15463/*!
15464@brief % shown
15465*/
15466float percent;
15467/*!
15468@brief If true, the bitmap is clipped vertically.
15469*/
15470bool vertical;
15471/*!
15472@brief If true, the bitmap is clipped in the oposite direction.
15473*/
15474bool flipClip;
15475
15476/*! @name Bitmap
15477@{ */
15478/// @}
15479
15480
15481/*! @name Layout
15482@{ */
15483/// @}
15484
15485
15486/*! @name Control
15487@{ */
15488/// @}
15489
15490
15491/*! @name ToolTip
15492@{ */
15493/// @}
15494
15495
15496/*! @name Editing
15497@{ */
15498/// @}
15499
15500
15501/*! @name Localization
15502@{ */
15503/// @}
15504
15505
15506/*! @name Ungrouped
15507@{ */
15508/// @}
15509
15510
15511/*! @name Object
15512@{ */
15513/// @}
15514
15515
15516/*! @name Editing
15517@{ */
15518/// @}
15519
15520
15521/*! @name Persistence
15522@{ */
15523/// @}
15524
15525};
15526
15527/*!
15528@brief A control that renders a skinned border specified in its profile.
15529
15530This control uses the bitmap specified in it's profile (GuiControlProfile::bitmapName).  It takes this image and breaks up aspects of it to skin the border of this control with.  It is also important to set GuiControlProfile::hasBitmapArray to true on the profile as well.
15531
15532The bitmap referenced should be broken up into a 3 x 3 grid (using the top left color pixel as a border color between each of the images) in which it will map to the following places:
155331 = Top Left Corner
155342 = Top Right Corner
155353 = Top Center
155364 = Left Center
155375 = Right Center
155386 = Bottom Left Corner
155397 = Bottom Center
155408 = Bottom Right Corner
155410 = Nothing
15542
155431 2 3
155444 5 0
155456 7 8
15546
15547@tsexample
15548singleton GuiControlProfile (BorderGUIProfile)
15549{
15550   bitmap = "core/art/gui/images/borderArray";
15551   hasBitmapArray = true;
15552   opaque = false;
15553};
15554
15555new GuiBitmapBorderCtrl(BitmapBorderGUI)
15556{
15557   profile = "BorderGUIProfile";
15558   position = "0 0";
15559   extent = "400 40";
15560   visible = "1";
15561};@endtsexample
15562
15563@see GuiControlProfile::bitmapName
15564@see GuiControlProfile::hasBitmapArray
15565
15566@ingroup GuiImages
15567*/
15568class GuiBitmapBorderCtrl : public GuiControl {
15569public:
15570
15571/*! @name Callbacks
15572@{ */
15573/// @}
15574
15575
15576/*! @name Layout
15577@{ */
15578/// @}
15579
15580
15581/*! @name Control
15582@{ */
15583/// @}
15584
15585
15586/*! @name ToolTip
15587@{ */
15588/// @}
15589
15590
15591/*! @name Editing
15592@{ */
15593/// @}
15594
15595
15596/*! @name Localization
15597@{ */
15598/// @}
15599
15600
15601/*! @name Ungrouped
15602@{ */
15603/// @}
15604
15605
15606/*! @name Object
15607@{ */
15608/// @}
15609
15610
15611/*! @name Editing
15612@{ */
15613/// @}
15614
15615
15616/*! @name Persistence
15617@{ */
15618/// @}
15619
15620};
15621
15622/*!
15623@brief GUI control object this displays a single line of text, without TorqueML.
15624
15625@tsexample
15626  new GuiTextCtrl()
15627  {
15628     text = "Hello World";
15629     textID = ""STR_HELLO"";
15630     maxlength = "1024";
15631      //Properties not specific to this control have been omitted from this example.
15632  };
15633@endtsexample
15634
15635@see GuiControl
15636@see Localization
15637
15638@ingroup GuiCore
15639
15640*/
15641class GuiTextCtrl : public GuiContainer {
15642public:
15643/*!
15644@brief Sets the text in the control.
15645
15646@param text Text to display in the control.
15647@tsexample
15648// Set the text to show in the control
15649%text = "Gideon - Destroyer of World";
15650
15651// Inform the GuiTextCtrl control to change its text to the defined value
15652%thisGuiTextCtrl.setText(%text);
15653@endtsexample
15654
15655@see GuiControl*/
15656void setText( string text );
15657/*!
15658@brief Maps the text ctrl to a variable used in localization, rather than raw text.
15659
15660@param textID Name of variable text should be mapped to
15661@tsexample
15662// Inform the GuiTextCtrl control of the textID to use
15663%thisGuiTextCtrl.setTextID("STR_QUIT");
15664@endtsexample
15665
15666@see GuiControl@see Localization*/
15667void setTextID( string textID );
15668
15669/*! @name Callbacks
15670@{ */
15671/// @}
15672
15673/*!
15674@brief The text to show on the control.
15675*/
15676caseString text;
15677/*!
15678@brief Maps the text of this control to a variable used in localization, rather than raw text.
15679*/
15680string textID;
15681/*!
15682@brief Defines the maximum length of the text.  The default is 1024.
15683*/
15684int maxLength;
15685
15686/*! @name Layout
15687@{ */
15688/// @}
15689
15690
15691/*! @name Layout
15692@{ */
15693/// @}
15694
15695
15696/*! @name Control
15697@{ */
15698/// @}
15699
15700
15701/*! @name ToolTip
15702@{ */
15703/// @}
15704
15705
15706/*! @name Editing
15707@{ */
15708/// @}
15709
15710
15711/*! @name Localization
15712@{ */
15713/// @}
15714
15715
15716/*! @name Ungrouped
15717@{ */
15718/// @}
15719
15720
15721/*! @name Object
15722@{ */
15723/// @}
15724
15725
15726/*! @name Editing
15727@{ */
15728/// @}
15729
15730
15731/*! @name Persistence
15732@{ */
15733/// @}
15734
15735};
15736
15737/*!
15738@brief A component that places a text entry box on the screen.
15739
15740Fonts and sizes are changed using profiles. The text value can be set or entered by a user.
15741
15742@tsexample
15743   new GuiTextEditCtrl(MessageHud_Edit)
15744  {
15745      text = "Hello World";
15746      validate = "validateCommand();"
15747      escapeCommand = "escapeCommand();";
15748      historySize = "5";
15749      tabComplete = "true";
15750      deniedSound = "DeniedSoundProfile";
15751      sinkAllKeyEvents = "true";
15752      password = "true";
15753      passwordMask = "*";
15754       //Properties not specific to this control have been omitted from this example.
15755   };
15756@endtsexample
15757
15758@see GuiTextCtrl
15759@see GuiControl
15760
15761@ingroup GuiControls
15762
15763*/
15764class GuiTextEditCtrl : public GuiTextCtrl {
15765public:
15766/*!
15767@brief Acquires the current text displayed in this control.
15768
15769@tsexample
15770// Acquire the value of the text control.
15771%text = %thisGuiTextEditCtrl.getText();
15772@endtsexample
15773
15774@return The current text within the control.
15775
15776@see GuiControl*/
15777string getText();
15778/*!
15779@brief Sets the text in the control.
15780
15781@param text Text to place in the control.
15782@tsexample
15783// Define the text to display
15784%text = "Text!"
15785
15786// Inform the GuiTextEditCtrl to display the defined text
15787%thisGuiTextEditCtrl.setText(%text);
15788@endtsexample
15789
15790@see GuiControl*/
15791void setText( string text );
15792/*!
15793@brief Returns the current position of the text cursor in the control.
15794
15795@tsexample
15796// Acquire the cursor position in the control
15797%position = %thisGuiTextEditCtrl.getCursorPost();
15798@endtsexample
15799
15800@return Text cursor position within the control.
15801
15802@see GuiControl*/
15803int getCursorPos();
15804/*!
15805@brief Sets the text cursor at the defined position within the control.
15806
15807@param position Text position to set the text cursor.
15808@tsexample
15809// Define the cursor position
15810%position = "12";
15811
15812// Inform the GuiTextEditCtrl control to place the text cursor at the defined position
15813%thisGuiTextEditCtrl.setCursorPos(%position);
15814@endtsexample
15815
15816@see GuiControl*/
15817void setCursorPos( int position );
15818/*!
15819@brief Checks to see if all text in the control has been selected.
15820
15821@tsexample
15822// Check to see if all text has been selected or not.
15823%allSelected = %thisGuiTextEditCtrl.isAllTextSelected();
15824@endtsexample
15825
15826@return True if all text in the control is selected, otherwise false.
15827
15828@see GuiControl*/
15829bool isAllTextSelected();
15830/*!
15831@brief Selects all text within the control.
15832
15833@tsexample
15834// Inform the control to select all of its text.
15835%thisGuiTextEditCtrl.selectAllText();
15836@endtsexample
15837
15838@see GuiControl*/
15839void selectAllText();
15840/*!
15841@brief Unselects all selected text in the control.
15842
15843@tsexample
15844// Inform the control to unselect all of its selected text
15845%thisGuiTextEditCtrl.clearSelectedText();
15846@endtsexample
15847
15848@see GuiControl*/
15849void clearSelectedText();
15850/*!
15851@brief Force a validation to occur.
15852
15853@tsexample
15854// Inform the control to force a validation of its text.
15855%thisGuiTextEditCtrl.forceValidateText();
15856@endtsexample
15857
15858@see GuiControl*/
15859void forceValidateText();
15860/*!
15861@brief Trigger the invalid sound and make the box red.nn@param playSound Play the invalid text sound or not.n*/
15862void invalidText( bool playSound=true );
15863/*!
15864@brief Restores the box to normal color.nn*/
15865void validText();
15866/*!
15867@brief Returns if the text is set to valid or not.n@Return true if text is set to valid, false if not.nn*/
15868bool isValidText();
15869
15870/*! @name Callbacks
15871@{ */
15872/*!
15873@brief Called if tabComplete is true, and the 'tab' key is pressed.
15874
15875@param val Input to mimick the '1' sent by the actual tab key button press.
15876@tsexample
15877// Tab key has been pressed, causing the callback to occur.
15878GuiTextEditCtrl::onTabComplete(%this,%val)
15879  {
15880     //Code to run when the onTabComplete callback occurs
15881  }
15882@endtsexample
15883
15884@see GuiTextCtrl
15885@see GuiControl*/
15886void onTabComplete( string val );
15887/*!
15888@brief Called when the 'Return' or 'Enter' key is pressed.
15889
15890@tsexample
15891// Return or Enter key was pressed, causing the callback to occur.
15892GuiTextEditCtrl::onReturn(%this)
15893  {
15894     // Code to run when the onReturn callback occurs
15895  }
15896@endtsexample
15897
15898@see GuiTextCtrl
15899@see GuiControl*/
15900void onReturn();
15901/*!
15902@brief Called whenever the control is validated.
15903
15904@tsexample
15905// The control gets validated, causing the callback to occur
15906GuiTextEditCtrl::onValidated(%this)
15907  {
15908     // Code to run when the control is validated
15909  }
15910@endtsexample
15911
15912@see GuiTextCtrl
15913@see GuiControl*/
15914void onValidate();
15915/// @}
15916
15917/*!
15918@brief The text to show on the control.
15919*/
15920caseString placeholderText;
15921
15922/*! @name Text Input
15923@{ */
15924/*!
15925@brief Script command to be called when the first validater is lost.
15926
15927
15928*/
15929string validate;
15930/*!
15931@brief Script command to be called when the Escape key is pressed.
15932
15933
15934*/
15935string escapeCommand;
15936/*!
15937@brief How large of a history buffer to maintain.
15938
15939
15940*/
15941int historySize;
15942/*!
15943@brief If true, when the 'tab' key is pressed, it will act as if the Enter key was pressed on the control.
15944
15945
15946*/
15947bool tabComplete;
15948/*!
15949@brief If the attempted text cannot be entered, this sound effect will be played.
15950
15951
15952*/
15953SFXTrack deniedSound;
15954/*!
15955@brief If true, every key event will act as if the Enter key was pressed.
15956
15957
15958*/
15959bool sinkAllKeyEvents;
15960/*!
15961@brief If true, all characters entered will be stored in the control, however will display as the character stored in passwordMask.
15962
15963
15964*/
15965bool password;
15966/*!
15967@brief If 'password' is true, this is the character that will be used to mask the characters in the control.
15968
15969
15970*/
15971string passwordMask;
15972/// @}
15973
15974
15975/*! @name Layout
15976@{ */
15977/// @}
15978
15979
15980/*! @name Layout
15981@{ */
15982/// @}
15983
15984
15985/*! @name Control
15986@{ */
15987/// @}
15988
15989
15990/*! @name ToolTip
15991@{ */
15992/// @}
15993
15994
15995/*! @name Editing
15996@{ */
15997/// @}
15998
15999
16000/*! @name Localization
16001@{ */
16002/// @}
16003
16004
16005/*! @name Ungrouped
16006@{ */
16007/// @}
16008
16009
16010/*! @name Object
16011@{ */
16012/// @}
16013
16014
16015/*! @name Editing
16016@{ */
16017/// @}
16018
16019
16020/*! @name Persistence
16021@{ */
16022/// @}
16023
16024};
16025
16026/*!
16027@brief Text entry element of a GuiConsole.
16028
16029@tsexample
16030new GuiConsoleEditCtrl(ConsoleEntry)
16031{
16032   profile = "ConsoleTextEditProfile";
16033   horizSizing = "width";
16034   vertSizing = "top";
16035   position = "0 462";
16036   extent = "640 18";
16037   minExtent = "8 8";
16038   visible = "1";
16039   altCommand = "ConsoleEntry::eval();";
16040   helpTag = "0";
16041   maxLength = "255";
16042   historySize = "40";
16043   password = "0";
16044   tabComplete = "0";
16045   sinkAllKeyEvents = "1";
16046   useSiblingScroller = "1";
16047};
16048@endtsexample
16049
16050@ingroup GuiCore
16051*/
16052class GuiConsoleEditCtrl : public GuiTextEditCtrl {
16053public:
16054
16055/*! @name Callbacks
16056@{ */
16057/// @}
16058
16059
16060/*! @name GuiConsoleEditCtrl
16061@{ */
16062/*!
16063*/
16064bool useSiblingScroller;
16065/// @}
16066
16067
16068/*! @name Text Input
16069@{ */
16070/// @}
16071
16072
16073/*! @name Layout
16074@{ */
16075/// @}
16076
16077
16078/*! @name Layout
16079@{ */
16080/// @}
16081
16082
16083/*! @name Control
16084@{ */
16085/// @}
16086
16087
16088/*! @name ToolTip
16089@{ */
16090/// @}
16091
16092
16093/*! @name Editing
16094@{ */
16095/// @}
16096
16097
16098/*! @name Localization
16099@{ */
16100/// @}
16101
16102
16103/*! @name Ungrouped
16104@{ */
16105/// @}
16106
16107
16108/*! @name Object
16109@{ */
16110/// @}
16111
16112
16113/*! @name Editing
16114@{ */
16115/// @}
16116
16117
16118/*! @name Persistence
16119@{ */
16120/// @}
16121
16122};
16123
16124/*!
16125@brief A collection of properties that determine control behavior and rendering.
16126@ingroup GuiCore
16127
16128*/
16129class GuiControlProfile : public SimObject {
16130public:
16131/*!
16132@brief Get the width of the string in pixels.
16133
16134@param string String to get the width of.@return width of the string in pixels.*/
16135int getStringWidth( string string );
16136
16137/*! @name Callbacks
16138@{ */
16139/// @}
16140
16141
16142/*! @name Behavior
16143@{ */
16144/*!
16145*/
16146bool tab;
16147/*!
16148@brief Whether the control can have the keyboard focus.
16149*/
16150bool canKeyFocus;
16151/*!
16152*/
16153bool mouseOverSelected;
16154/*!
16155*/
16156bool modal;
16157/// @}
16158
16159
16160/*! @name Appearance
16161@{ */
16162/*!
16163*/
16164bool opaque;
16165/*!
16166*/
16167ColorI fillColor;
16168/*!
16169*/
16170ColorI fillColorHL;
16171/*!
16172*/
16173ColorI fillColorNA;
16174/*!
16175*/
16176ColorI fillColorERR;
16177/*!
16178*/
16179ColorI fillColorSEL;
16180/*!
16181@brief Border type (0=no border).
16182*/
16183int border;
16184/*!
16185@brief Thickness of border in pixels.
16186*/
16187int borderThickness;
16188/*!
16189@brief Color to draw border with.
16190*/
16191ColorI borderColor;
16192/*!
16193*/
16194ColorI borderColorHL;
16195/*!
16196*/
16197ColorI borderColorNA;
16198/*!
16199*/
16200ColorI bevelColorHL;
16201/*!
16202*/
16203ColorI bevelColorLL;
16204/// @}
16205
16206
16207/*! @name Text
16208@{ */
16209/*!
16210@brief Name of font family and typeface (e.g. "Arial Bold").
16211*/
16212string fontType;
16213/*!
16214@brief Font size in points.
16215*/
16216int fontSize;
16217/*!
16218*/
16219GuiFontCharset fontCharset;
16220/*!
16221@brief Font colors to use for different text types/states.
16222*/
16223ColorI fontColors[ 10 ];
16224/*!
16225@brief Font color for normal text (same as fontColors[0]).
16226*/
16227ColorI fontColor;
16228/*!
16229@brief Font color for highlighted text (same as fontColors[1]).
16230*/
16231ColorI fontColorHL;
16232/*!
16233@brief Font color when control is not active/disabled (same as fontColors[2]).
16234*/
16235ColorI fontColorNA;
16236/*!
16237@brief Font color for selected text (same as fontColors[3]).
16238*/
16239ColorI fontColorSEL;
16240/*!
16241@brief Font color for links in text (same as fontColors[4]).
16242*/
16243ColorI fontColorLink;
16244/*!
16245@brief Font color for highlighted links in text (same as fontColors[5]).
16246*/
16247ColorI fontColorLinkHL;
16248/*!
16249@brief Horizontal alignment for text.
16250*/
16251GuiAlignmentType justify;
16252/*!
16253*/
16254Point2I textOffset;
16255/*!
16256@brief Automatically adjust width of control to fit contents.
16257*/
16258bool autoSizeWidth;
16259/*!
16260@brief Automatically adjust height of control to fit contents.
16261*/
16262bool autoSizeHeight;
16263/*!
16264@brief Whether to add automatic tab event when return is pressed so focus moves on to next control (GuiTextEditCtrl).
16265*/
16266bool returnTab;
16267/*!
16268@brief Whether control should only accept numerical data (GuiTextEditCtrl).
16269*/
16270bool numbersOnly;
16271/*!
16272@brief Color to use for the text cursor.
16273*/
16274ColorI cursorColor;
16275/// @}
16276
16277
16278/*! @name Misc
16279@{ */
16280/*!
16281@brief Texture to use for rendering control.
16282*/
16283filename bitmap;
16284/*!
16285@brief If true, 'bitmap' is an array of images.
16286*/
16287bool hasBitmapArray;
16288/*!
16289@brief Sound to play when mouse has been pressed on control.
16290*/
16291SFXTrack soundButtonDown;
16292/*!
16293@brief Sound to play when mouse is hovering over control.
16294*/
16295SFXTrack soundButtonOver;
16296/*!
16297*/
16298string profileForChildren;
16299/// @}
16300
16301/*!
16302@brief Category under which the profile will appear in the editor.
16303*/
16304string category;
16305
16306/*! @name Ungrouped
16307@{ */
16308/// @}
16309
16310
16311/*! @name Object
16312@{ */
16313/// @}
16314
16315
16316/*! @name Editing
16317@{ */
16318/// @}
16319
16320
16321/*! @name Persistence
16322@{ */
16323/// @}
16324
16325};
16326
16327/*!
16328@brief A GuiControlProfile with additional fields specific to GuiGameListMenuCtrl.
16329
16330@tsexample
16331new GuiGameListMenuProfile()
16332{
16333   hitAreaUpperLeft = "10 2";
16334   hitAreaLowerRight = "190 18";
16335   iconOffset = "10 2";
16336   rowSize = "200 20";
16337   columnSplit = "100";
16338   rightPad = "4";
16339   //Properties not specific to this control have been omitted from this example.
16340};
16341@endtsexample
16342
16343@ingroup GuiGame
16344*/
16345class GuiGameListMenuProfile : public GuiControlProfile {
16346public:
16347
16348/*! @name Callbacks
16349@{ */
16350/// @}
16351
16352/*!
16353@brief Position of the upper left corner of the row hit area (relative to row's top left corner)
16354*/
16355Point2I hitAreaUpperLeft;
16356/*!
16357@brief Position of the lower right corner of the row hit area (relative to row's top left corner)
16358*/
16359Point2I hitAreaLowerRight;
16360/*!
16361@brief Offset from the row's top left corner at which to render the row icon
16362*/
16363Point2I iconOffset;
16364/*!
16365@brief The base size ("width height") of a row
16366*/
16367Point2I rowSize;
16368/*!
16369@brief Padding between the leftmost edge of the control, and the row's left arrow.
16370*/
16371int columnSplit;
16372/*!
16373@brief Padding between the rightmost edge of the control and the row's right arrow.
16374*/
16375int rightPad;
16376
16377/*! @name Behavior
16378@{ */
16379/// @}
16380
16381
16382/*! @name Appearance
16383@{ */
16384/// @}
16385
16386
16387/*! @name Text
16388@{ */
16389/// @}
16390
16391
16392/*! @name Misc
16393@{ */
16394/// @}
16395
16396
16397/*! @name Ungrouped
16398@{ */
16399/// @}
16400
16401
16402/*! @name Object
16403@{ */
16404/// @}
16405
16406
16407/*! @name Editing
16408@{ */
16409/// @}
16410
16411
16412/*! @name Persistence
16413@{ */
16414/// @}
16415
16416};
16417
16418/*!
16419@brief A GuiControlProfile with additional fields specific to GuiGameListOptionsCtrl.
16420
16421@tsexample
16422new GuiGameListOptionsProfile()
16423{
16424   columnSplit = "100";
16425   rightPad = "4";
16426   //Properties not specific to this control have been omitted from this example.
16427};
16428@endtsexample
16429
16430@ingroup GuiGame
16431*/
16432class GuiGameListOptionsProfile : public GuiGameListMenuProfile {
16433public:
16434
16435/*! @name Callbacks
16436@{ */
16437/// @}
16438
16439
16440/*! @name Behavior
16441@{ */
16442/// @}
16443
16444
16445/*! @name Appearance
16446@{ */
16447/// @}
16448
16449
16450/*! @name Text
16451@{ */
16452/// @}
16453
16454
16455/*! @name Misc
16456@{ */
16457/// @}
16458
16459
16460/*! @name Ungrouped
16461@{ */
16462/// @}
16463
16464
16465/*! @name Object
16466@{ */
16467/// @}
16468
16469
16470/*! @name Editing
16471@{ */
16472/// @}
16473
16474
16475/*! @name Persistence
16476@{ */
16477/// @}
16478
16479};
16480
16481/*!
16482@brief A text control that uses the Gui Markup Language ('ML') tags to dynamically change the text.
16483
16484Example of dynamic changes include colors, styles, and/or hyperlinks. These changes can occur without having to use separate text controls with separate text profiles.
16485
16486@tsexample
16487new GuiMLTextCtrl(CenterPrintText)
16488{
16489    lineSpacing = "2";
16490    allowColorChars = "0";
16491    maxChars = "-1";
16492    deniedSound = "DeniedSoundProfile";
16493    text = "The Text for This Control.";
16494    useURLMouseCursor = "true";
16495    //Properties not specific to this control have been omitted from this example.
16496};
16497@endtsexample
16498
16499@see GuiControl
16500
16501@ingroup GuiCore
16502
16503*/
16504class GuiMLTextCtrl : public GuiControl {
16505public:
16506/*!
16507@brief Set the text contained in the control.
16508
16509@param text The text to display in the control.
16510@tsexample
16511// Define the text to display
16512%text = "Nifty Control Text";
16513
16514// Set the text displayed within the control
16515%thisGuiMLTextCtrl.setText(%text);
16516@endtsexample
16517
16518@see GuiControl*/
16519void setText( string text );
16520/*!
16521@brief Returns the text from the control, including TorqueML characters.
16522
16523@tsexample
16524// Get the text displayed in the control
16525%controlText = %thisGuiMLTextCtrl.getText();
16526@endtsexample
16527
16528@return Text string displayed in the control, including any TorqueML characters.
16529
16530@see GuiControl*/
16531string getText();
16532/*!
16533@brief Appends the text in the control with additional text. Also .
16534
16535@param text New text to append to the existing text.
16536@param reformat If true, the control will also be visually reset (defaults to true).
16537@tsexample
16538// Define new text to add
16539%text = "New Text to Add";
16540
16541// Set reformat boolean
16542%reformat = "true";
16543
16544// Inform the control to add the new text
16545%thisGuiMLTextCtrl.addText(%text,%reformat);
16546@endtsexample
16547
16548@see GuiControl*/
16549void addText( string text, bool reformat=true );
16550/*!
16551@brief Change the text cursor's position to a new defined offset within the text in the control.
16552
16553@param newPos Offset to place cursor.
16554@tsexample
16555// Define cursor offset position
16556%position = "23";
16557
16558// Inform the GuiMLTextCtrl object to move the cursor to the new position.
16559%thisGuiMLTextCtrl.setCursorPosition(%position);
16560@endtsexample
16561
16562@return Returns true if the cursor position moved, or false if the position was not changed.
16563
16564@see GuiControl*/
16565bool setCursorPosition( int newPos );
16566/*!
16567@brief Scroll down to a specified tag.
16568
16569Detailed description
16570
16571@param tagID TagID to scroll the control to
16572@tsexample
16573// Define the TagID we want to scroll the control to
16574%tagId = "4";
16575
16576// Inform the GuiMLTextCtrl to scroll to the defined TagID
16577%thisGuiMLTextCtrl.scrollToTag(%tagId);
16578@endtsexample
16579
16580@see GuiControl*/
16581void scrollToTag( int tagID );
16582/*!
16583@brief Scroll to the top of the text.
16584
16585@tsexample
16586// Inform GuiMLTextCtrl object to scroll to its top
16587%thisGuiMLTextCtrl.scrollToTop();
16588@endtsexample
16589
16590@see GuiControl*/
16591void scrollToTop();
16592/*!
16593@brief Scroll to the bottom of the text.
16594
16595@tsexample
16596// Inform GuiMLTextCtrl object to scroll to its bottom
16597%thisGuiMLTextCtrl.scrollToBottom();
16598@endtsexample
16599
16600@see GuiControl*/
16601void scrollToBottom();
16602/*!
16603@brief Forces the text control to reflow the text after new text is added, possibly resizing the control.
16604
16605@tsexample
16606// Define new text to add
16607%newText = "BACON!";
16608
16609// Add the new text to the control
16610%thisGuiMLTextCtrl.addText(%newText);
16611
16612// Inform the GuiMLTextCtrl object to force a reflow to ensure the added text fits properly.
16613%thisGuiMLTextCtrl.forceReflow();
16614@endtsexample
16615
16616@see GuiControl*/
16617void forceReflow();
16618/*!
16619@brief Sets the alpha value of the control.
16620
16621@param alphaVal n - 1.0 floating value for the alpha
16622@tsexample
16623// Define the alphe value
16624%alphaVal = "0.5";
16625
16626// Inform the control to update its alpha value.
16627%thisGuiMLTextCtrl.setAlpha(%alphaVal);
16628@endtsexample
16629
16630@see GuiControl*/
16631void setAlpha( float alphaVal );
16632
16633/*! @name Callbacks
16634@{ */
16635/*!
16636@brief Called whenever a URL was clicked on within the control.
16637
16638@param url The URL address that was clicked on.
16639@tsexample
16640// A URL address was clicked on in the control, causing the callback to occur.
16641GuiMLTextCtrl::onUrl(%this,%url)
16642  {
16643     // Code to run whenever a URL was clicked on
16644  }
16645@endtsexample
16646
16647@see GuiControl*/
16648void onURL( string url );
16649/*!
16650@brief Called whenever the control size changes.
16651
16652@param width The new width value for the control
16653@param maxY The current maximum allowed Y value for the control
16654
16655@tsexample
16656// Control size changed, causing the callback to occur.
16657GuiMLTextCtrl::onResize(%this,%width,%maxY)
16658  {
16659     // Code to call when the control size changes
16660  }
16661@endtsexample
16662
16663@see GuiControl*/
16664void onResize( int width, int maxY );
16665/// @}
16666
16667
16668/*! @name Text
16669@{ */
16670/*!
16671@brief The number of blank pixels to place between each line.
16672
16673
16674*/
16675int lineSpacing;
16676/*!
16677@brief If true, the control will allow characters to have unique colors.
16678*/
16679bool allowColorChars;
16680/*!
16681@brief Maximum number of characters that the control will display.
16682*/
16683int maxChars;
16684/*!
16685@brief If the text will not fit in the control, the deniedSound is played.
16686*/
16687SFXTrack deniedSound;
16688/*!
16689@brief Text to display in this control.
16690*/
16691caseString text;
16692/*!
16693@brief If true, the mouse cursor will turn into a hand cursor while over a link in the text.
16694
16695This is dependant on the markup language used by the GuiMLTextCtrl
16696
16697*/
16698bool useURLMouseCursor;
16699/// @}
16700
16701
16702/*! @name Layout
16703@{ */
16704/// @}
16705
16706
16707/*! @name Control
16708@{ */
16709/// @}
16710
16711
16712/*! @name ToolTip
16713@{ */
16714/// @}
16715
16716
16717/*! @name Editing
16718@{ */
16719/// @}
16720
16721
16722/*! @name Localization
16723@{ */
16724/// @}
16725
16726
16727/*! @name Ungrouped
16728@{ */
16729/// @}
16730
16731
16732/*! @name Object
16733@{ */
16734/// @}
16735
16736
16737/*! @name Editing
16738@{ */
16739/// @}
16740
16741
16742/*! @name Persistence
16743@{ */
16744/// @}
16745
16746};
16747
16748/*!
16749@brief A text entry control that accepts the Gui Markup Language ('ML') tags and multiple lines.
16750
16751@tsexample
16752new GuiMLTextEditCtrl()
16753   {
16754      lineSpacing = "2";
16755      allowColorChars = "0";
16756      maxChars = "-1";
16757      deniedSound = "DeniedSoundProfile";
16758      text = "";
16759      escapeCommand = "onEscapeScriptFunction();";
16760     //Properties not specific to this control have been omitted from this example.
16761   };
16762@endtsexample
16763
16764@see GuiMLTextCtrl
16765@see GuiControl
16766
16767@ingroup GuiControls
16768
16769*/
16770class GuiMLTextEditCtrl : public GuiMLTextCtrl {
16771public:
16772
16773/*! @name Callbacks
16774@{ */
16775/// @}
16776
16777/*!
16778@brief Script function to run whenever the 'escape' key is pressed when this control is in focus.
16779
16780
16781*/
16782string escapeCommand;
16783
16784/*! @name Text
16785@{ */
16786/// @}
16787
16788
16789/*! @name Layout
16790@{ */
16791/// @}
16792
16793
16794/*! @name Control
16795@{ */
16796/// @}
16797
16798
16799/*! @name ToolTip
16800@{ */
16801/// @}
16802
16803
16804/*! @name Editing
16805@{ */
16806/// @}
16807
16808
16809/*! @name Localization
16810@{ */
16811/// @}
16812
16813
16814/*! @name Ungrouped
16815@{ */
16816/// @}
16817
16818
16819/*! @name Object
16820@{ */
16821/// @}
16822
16823
16824/*! @name Editing
16825@{ */
16826/// @}
16827
16828
16829/*! @name Persistence
16830@{ */
16831/// @}
16832
16833};
16834
16835/*!
16836@brief GUI Control which displays a numerical value which can be increased or decreased using a pair of bitmap up/down buttons. 
16837
16838This control uses the bitmap specified in it's profile (GuiControlProfile::bitmapName). It takes this image and breaks up aspects of it to render the up and down arrows. It is also important to set GuiControlProfile::hasBitmapArray to true on the profile as well.
16839
16840The bitmap referenced should be broken up into a 1 x 4 grid (using the top left color pixel as a border color between each of the images) in which it will map to the following places:
16841<ol>
16842<li>Up arrow active</li>
16843<li>Up arrow inactive</li>
16844<li>Down arrow active</li>
16845<li>Down arrow inactive</li>
16846</ol>
16847
16848<pre>
168491
168502
168513
168524</pre>
16853
16854@tsexample
16855singleton GuiControlProfile (SliderBitmapGUIProfile)
16856{
16857   bitmap = "core/art/gui/images/sliderArray";
16858   hasBitmapArray = true;
16859   opaque = false;
16860};
16861
16862new GuiTextEditSliderBitmapCtrl()
16863{
16864   profile = "SliderBitmapGUIProfile";
16865   format = "%3.2f";
16866   range = "-1e+03 1e+03";
16867   increment = "0.1";
16868   focusOnMouseWheel = "0";
16869   bitmap = "";
16870   //Properties not specific to this control have been omitted from this example.
16871};
16872@endtsexample
16873
16874@see GuiTextEditSliderCtrl
16875
16876@see GuiTextEditCtrl
16877
16878@ingroup GuiCore
16879
16880*/
16881class GuiTextEditSliderBitmapCtrl : public GuiTextEditCtrl {
16882public:
16883
16884/*! @name Callbacks
16885@{ */
16886/// @}
16887
16888/*!
16889@brief Character format type to place in the control.
16890
16891
16892*/
16893string Format;
16894/*!
16895@brief Maximum vertical and horizontal range to allow in the control.
16896
16897
16898*/
16899Point2F range;
16900/*!
16901@brief How far to increment the slider on each step.
16902
16903
16904*/
16905float increment;
16906/*!
16907@brief If true, the control will accept giving focus to the user when the mouse wheel is used.
16908
16909
16910*/
16911bool focusOnMouseWheel;
16912/*!
16913@brief Unused
16914*/
16915filename bitmap;
16916
16917/*! @name Text Input
16918@{ */
16919/// @}
16920
16921
16922/*! @name Layout
16923@{ */
16924/// @}
16925
16926
16927/*! @name Layout
16928@{ */
16929/// @}
16930
16931
16932/*! @name Control
16933@{ */
16934/// @}
16935
16936
16937/*! @name ToolTip
16938@{ */
16939/// @}
16940
16941
16942/*! @name Editing
16943@{ */
16944/// @}
16945
16946
16947/*! @name Localization
16948@{ */
16949/// @}
16950
16951
16952/*! @name Ungrouped
16953@{ */
16954/// @}
16955
16956
16957/*! @name Object
16958@{ */
16959/// @}
16960
16961
16962/*! @name Editing
16963@{ */
16964/// @}
16965
16966
16967/*! @name Persistence
16968@{ */
16969/// @}
16970
16971};
16972
16973/*!
16974@brief GUI Control which displays a numerical value which can be increased or decreased using a pair of arrows.
16975
16976@tsexample
16977new GuiTextEditSliderCtrl()
16978{
16979   format = "%3.2f";
16980   range = "-1e+03 1e+03";
16981   increment = "0.1";
16982   focusOnMouseWheel = "0";
16983   //Properties not specific to this control have been omitted from this example.
16984};
16985@endtsexample
16986
16987@see GuiTextEditCtrl
16988
16989@ingroup GuiCore
16990
16991*/
16992class GuiTextEditSliderCtrl : public GuiTextEditCtrl {
16993public:
16994
16995/*! @name Callbacks
16996@{ */
16997/// @}
16998
16999/*!
17000@brief Character format type to place in the control.
17001
17002
17003*/
17004string Format;
17005/*!
17006@brief Maximum vertical and horizontal range to allow in the control.
17007
17008
17009*/
17010Point2F range;
17011/*!
17012@brief How far to increment the slider on each step.
17013
17014
17015*/
17016float increment;
17017/*!
17018@brief If true, the control will accept giving focus to the user when the mouse wheel is used.
17019
17020
17021*/
17022bool focusOnMouseWheel;
17023
17024/*! @name Text Input
17025@{ */
17026/// @}
17027
17028
17029/*! @name Layout
17030@{ */
17031/// @}
17032
17033
17034/*! @name Layout
17035@{ */
17036/// @}
17037
17038
17039/*! @name Control
17040@{ */
17041/// @}
17042
17043
17044/*! @name ToolTip
17045@{ */
17046/// @}
17047
17048
17049/*! @name Editing
17050@{ */
17051/// @}
17052
17053
17054/*! @name Localization
17055@{ */
17056/// @}
17057
17058
17059/*! @name Ungrouped
17060@{ */
17061/// @}
17062
17063
17064/*! @name Object
17065@{ */
17066/// @}
17067
17068
17069/*! @name Editing
17070@{ */
17071/// @}
17072
17073
17074/*! @name Persistence
17075@{ */
17076/// @}
17077
17078};
17079
17080/*!
17081@brief Acts as a skin for the cursor, where each GuiCursor object can have its own look and click-zone.
17082
17083GuiCursors act as skins for the cursor in the game, where each individual GuiCursor can have its own defined imagemap,
17084click zone and render offset. This allows a game to easily support a wide range of cursors. The active cursor can de changed
17085for each Canvas using %canvasObj.setCursor(GuiCursor);.@tsexample
17086new GuiCursor(DefaultCursor)
17087{
17088   hotSpot = "1 1";
17089   renderOffset = "0 0";
17090   bitmapName = "~/art/gui/images/defaultCursor";
17091};
17092@endtsexample
17093
17094@see GuiCanvas
17095
17096@ingroup GuiCore
17097
17098*/
17099class GuiCursor : public SimObject {
17100public:
17101
17102/*! @name Callbacks
17103@{ */
17104/// @}
17105
17106/*!
17107@brief The location of the cursor's hot spot (which pixel carries the click).
17108*/
17109Point2I hotSpot;
17110/*!
17111@brief Offset of the bitmap, where 0 signifies left edge of the bitmap, 1, the right. Similarly for the Y-component.
17112*/
17113Point2F renderOffset;
17114/*!
17115@brief File name of the bitmap for the cursor.
17116*/
17117filename bitmapName;
17118
17119/*! @name Ungrouped
17120@{ */
17121/// @}
17122
17123
17124/*! @name Object
17125@{ */
17126/// @}
17127
17128
17129/*! @name Editing
17130@{ */
17131/// @}
17132
17133
17134/*! @name Persistence
17135@{ */
17136/// @}
17137
17138};
17139
17140/*!
17141@brief GUI Control which displays a horizontal bar which increases as the progress value of 0.0 - 1.0 increases.
17142
17143@tsexample
17144     new GuiProgressCtrl(JS_statusBar)
17145    {
17146          //Properties not specific to this control have been omitted from this example.
17147     };
17148
17149// Define the value to set the progress bar%value = "0.5f"
17150
17151// Set the value of the progress bar, from 0.0 - 1.0
17152%thisGuiProgressCtrl.setValue(%value);
17153// Get the value of the progress bar.
17154%progress = %thisGuiProgressCtrl.getValue();
17155@endtsexample
17156
17157@see GuiTextCtrl
17158@see GuiControl
17159
17160@ingroup GuiValues
17161
17162*/
17163class GuiProgressCtrl : public GuiTextCtrl {
17164public:
17165
17166/*! @name Callbacks
17167@{ */
17168/// @}
17169
17170
17171/*! @name Layout
17172@{ */
17173/// @}
17174
17175
17176/*! @name Layout
17177@{ */
17178/// @}
17179
17180
17181/*! @name Control
17182@{ */
17183/// @}
17184
17185
17186/*! @name ToolTip
17187@{ */
17188/// @}
17189
17190
17191/*! @name Editing
17192@{ */
17193/// @}
17194
17195
17196/*! @name Localization
17197@{ */
17198/// @}
17199
17200
17201/*! @name Ungrouped
17202@{ */
17203/// @}
17204
17205
17206/*! @name Object
17207@{ */
17208/// @}
17209
17210
17211/*! @name Editing
17212@{ */
17213/// @}
17214
17215
17216/*! @name Persistence
17217@{ */
17218/// @}
17219
17220};
17221
17222/*!
17223@brief A single-line text control that displays its text in a multi-line popup when clicked.
17224
17225This control acts like a GuiTextCtrl (and inherits from it), when clicked it creates a GuiMLTextCtrl roughly where you clicked with the same text in it.  This allows you to have a single line text control which upon clicking will display the entire text contained in a multi-line format.
17226
17227@tsexample
17228new GuiBubbleTextCtrl(BubbleTextGUI)
17229{
17230   text = "This is the first sentence.  This second sentence can be sized outside of the default single line view, upon clicking this will be displayed in a multi-line format.";
17231};
17232@endtsexample
17233
17234@see GuiTextCtrl
17235@see GuiMLTextCtrl
17236
17237@ingroup GuiControls
17238
17239*/
17240class GuiBubbleTextCtrl : public GuiTextCtrl {
17241public:
17242
17243/*! @name Callbacks
17244@{ */
17245/// @}
17246
17247
17248/*! @name Layout
17249@{ */
17250/// @}
17251
17252
17253/*! @name Layout
17254@{ */
17255/// @}
17256
17257
17258/*! @name Control
17259@{ */
17260/// @}
17261
17262
17263/*! @name ToolTip
17264@{ */
17265/// @}
17266
17267
17268/*! @name Editing
17269@{ */
17270/// @}
17271
17272
17273/*! @name Localization
17274@{ */
17275/// @}
17276
17277
17278/*! @name Ungrouped
17279@{ */
17280/// @}
17281
17282
17283/*! @name Object
17284@{ */
17285/// @}
17286
17287
17288/*! @name Editing
17289@{ */
17290/// @}
17291
17292
17293/*! @name Persistence
17294@{ */
17295/// @}
17296
17297};
17298
17299/*!
17300@brief The most widely used button class.
17301
17302GuiRenderTargetVizCtrl renders seperately of, but utilizes all of the functionality of GuiBaseButtonCtrl.
17303This grants GuiRenderTargetVizCtrl the versatility to be either of the 3 button types.
17304
17305@tsexample
17306// Create a PushButton GuiRenderTargetVizCtrl that calls randomFunction when clicked
17307%button = new GuiRenderTargetVizCtrl()
17308{
17309   profile    = "GuiButtonProfile";
17310   buttonType = "PushButton";
17311   command    = "randomFunction();";
17312};
17313@endtsexample
17314
17315@ingroup GuiButtons
17316*/
17317class GuiRenderTargetVizCtrl : public GuiControl {
17318public:
17319
17320/*! @name Callbacks
17321@{ */
17322/// @}
17323
17324
17325/*! @name Layout
17326@{ */
17327/// @}
17328
17329
17330/*! @name Control
17331@{ */
17332/// @}
17333
17334
17335/*! @name ToolTip
17336@{ */
17337/// @}
17338
17339
17340/*! @name Editing
17341@{ */
17342/// @}
17343
17344
17345/*! @name Localization
17346@{ */
17347/// @}
17348
17349
17350/*! @name Ungrouped
17351@{ */
17352/// @}
17353
17354
17355/*! @name Object
17356@{ */
17357/// @}
17358
17359
17360/*! @name Editing
17361@{ */
17362/// @}
17363
17364
17365/*! @name Persistence
17366@{ */
17367/// @}
17368
17369/*!
17370*/
17371string RenderTargetName;
17372/*!
17373*/
17374SimObject cameraObject;
17375};
17376
17377/*!
17378@brief A material in Torque 3D is a data structure that describes a surface.
17379
17380It contains many different types of information for rendering properties. Torque 3D generates shaders from Material definitions. The shaders are compiled at runtime and output into the example/shaders directory. Any errors or warnings generated from compiling the procedurally generated shaders are output to the console as well as the output window in the Visual C IDE.
17381
17382@tsexample
17383singleton Material(DECAL_scorch)
17384{
17385   baseTex[0] = "./scorch_decal.png";
17386   vertColor[ 0 ] = true;
17387
17388   translucent = true;
17389   translucentBlendOp = None;
17390   translucentZWrite = true;
17391   alphaTest = true;
17392   alphaRef = 84;
17393};
17394@endtsexample
17395
17396@see Rendering
17397@see ShaderData
17398@ingroup GFX
17399
17400*/
17401class Material : public SimObject {
17402public:
17403/*!
17404@brief Flushes all material instances that use this material.
17405
17406*/
17407void flush();
17408/*!
17409@brief Reloads all material instances that use this material.
17410
17411*/
17412void reload();
17413/*!
17414@brief Dumps a formatted list of the currently allocated material instances for this material to the console.
17415
17416*/
17417void dumpInstances();
17418/*!
17419@brief Dumps a formatted list of the currently allocated material instances for this material to the console.
17420
17421*/
17422void getMaterialInstances( GuiTreeViewCtrl matTree=nullAsType< GuiTreeViewCtrl*>() );
17423string getAnimFlags( uint id );
17424/*!
17425@brief Get filename of material
17426
17427*/
17428string getFilename();
17429/*!
17430@brief Returns true if this Material was automatically generated by MaterialList::mapMaterials()
17431
17432*/
17433bool isAutoGenerated();
17434/*!
17435@brief setAutoGenerated(bool isAutoGenerated): Set whether or not the Material is autogenerated.
17436
17437*/
17438void setAutoGenerated( bool isAutoGenerated );
17439/*!
17440@brief Get filename of autogenerated shader file
17441
17442*/
17443string getAutogeneratedFile();
17444
17445/*! @name Callbacks
17446@{ */
17447/// @}
17448
17449/*!
17450@brief Used to map this material to the material name used by TSShape.
17451*/
17452string mapTo;
17453/*!
17454@brief This color is multiplied against the diffuse texture color.  If no diffuse texture is present this is the material color.
17455*/
17456LinearColorF diffuseColor[ 4 ];
17457/*!
17458@brief ðŒE 
17459*/
17460filename DiffuseMap[ 4 ];
17461/*!
17462@brief ðŒE 
17463*/
17464assetIdString DiffuseMapAsset[ 4 ];
17465/*!
17466@brief ðŒE 
17467*/
17468filename OverlayMap[ 4 ];
17469/*!
17470@brief ðŒE 
17471*/
17472assetIdString OverlayMapAsset[ 4 ];
17473/*!
17474@brief ðŒE 
17475*/
17476filename LightMap[ 4 ];
17477/*!
17478@brief ðŒE 
17479*/
17480assetIdString LightMapAsset[ 4 ];
17481/*!
17482@brief ðŒE 
17483*/
17484filename ToneMap[ 4 ];
17485/*!
17486@brief ðŒE 
17487*/
17488assetIdString ToneMapAsset[ 4 ];
17489/*!
17490@brief ðŒE 
17491*/
17492filename DetailMap[ 4 ];
17493/*!
17494@brief ðŒE 
17495*/
17496assetIdString DetailMapAsset[ 4 ];
17497/*!
17498@brief ðŒE 
17499*/
17500filename NormalMap[ 4 ];
17501/*!
17502@brief ðŒE 
17503*/
17504assetIdString NormalMapAsset[ 4 ];
17505/*!
17506@brief `Oç
17507*/
17508filename ORMConfigMap[ 4 ];
17509/*!
17510@brief ðŒE 
17511*/
17512assetIdString ORMConfigMapAsset[ 4 ];
17513/*!
17514@brief `Oç
17515*/
17516filename RoughMap[ 4 ];
17517/*!
17518@brief ðŒE 
17519*/
17520assetIdString RoughMapAsset[ 4 ];
17521/*!
17522*/
17523filename AOMap[ 4 ];
17524/*!
17525@brief ðŒE 
17526*/
17527assetIdString AOMapAsset[ 4 ];
17528/*!
17529@brief `Oç
17530*/
17531filename MetalMap[ 4 ];
17532/*!
17533@brief ðŒE 
17534*/
17535assetIdString MetalMapAsset[ 4 ];
17536/*!
17537@brief ,ŽE 
17538*/
17539filename GlowMap[ 4 ];
17540/*!
17541@brief ðŒE 
17542*/
17543assetIdString GlowMapAsset[ 4 ];
17544/*!
17545@brief ðŒE 
17546*/
17547filename DetailNormalMap[ 4 ];
17548/*!
17549@brief ðŒE 
17550*/
17551assetIdString DetailNormalMapAsset[ 4 ];
17552/*!
17553@brief Enable sRGB for the diffuse color texture map.
17554*/
17555bool diffuseMapSRGB[ 4 ];
17556/*!
17557@brief The scale factor for the detail map.
17558*/
17559Point2F detailScale[ 4 ];
17560/*!
17561@brief Used to scale the strength of the detail normal map when blended with the base normal map.
17562*/
17563float detailNormalMapStrength[ 4 ];
17564/*!
17565@brief The degree of roughness when not using a ORMConfigMap.
17566*/
17567float roughness[ 4 ];
17568/*!
17569@brief The degree of Metalness when not using a ORMConfigMap.
17570*/
17571float metalness[ 4 ];
17572/*!
17573@brief glow mask multiplier
17574*/
17575float glowMul[ 4 ];
17576/*!
17577@brief Accumulation texture.
17578*/
17579bool accuEnabled[ 4 ];
17580/*!
17581@brief The scale that is applied to the accu map texture. You can use this to fit the texture to smaller or larger objects.
17582*/
17583float accuScale[ 4 ];
17584/*!
17585@brief The direction of the accumulation. Chose whether you want the accu map to go from top to bottom (ie. snow) or upwards (ie. mold).
17586*/
17587float accuDirection[ 4 ];
17588/*!
17589@brief The strength of the accu map. This changes the transparency of the accu map texture. Make it subtle or add more contrast.
17590*/
17591float accuStrength[ 4 ];
17592/*!
17593@brief The coverage ratio of the accu map texture. Use this to make the entire shape pick up some of the accu map texture or none at all.
17594*/
17595float accuCoverage[ 4 ];
17596/*!
17597@brief Changes specularity to this value where the accumulated material is present.
17598*/
17599float accuSpecular[ 4 ];
17600/*!
17601@brief Substance Designer Workaround.
17602*/
17603bool isSRGB[ 4 ];
17604/*!
17605@brief Treat Roughness as Roughness
17606*/
17607bool invertRoughness[ 4 ];
17608/*!
17609@brief The input channel roughness maps use.
17610*/
17611float roughnessChan[ 4 ];
17612/*!
17613@brief The input channel AO maps use.
17614*/
17615float AOChan[ 4 ];
17616/*!
17617@brief The input channel metalness maps use.
17618*/
17619float metalChan[ 4 ];
17620/*!
17621@brief Enables rendering as glowing.
17622*/
17623bool glow[ 4 ];
17624/*!
17625@brief Enables parallax mapping and defines the scale factor for the parallax effect.  Typically this value is less than 0.4 else the effect breaks down.
17626*/
17627float parallaxScale[ 4 ];
17628/*!
17629@brief Use anisotropic filtering for the textures of this stage.
17630*/
17631bool useAnisotropic[ 4 ];
17632/*!
17633@brief If true the vertex color is used for lighting.
17634*/
17635bool vertLit[ 4 ];
17636/*!
17637@brief If enabled, vertex colors are premultiplied with diffuse colors.
17638*/
17639bool vertColor[ 4 ];
17640/*!
17641@brief The Minnaert shading constant value.  Must be greater than 0 to enable the effect.
17642*/
17643float minnaertConstant[ 4 ];
17644/*!
17645@brief Enables the subsurface scattering approximation.
17646*/
17647bool subSurface[ 4 ];
17648/*!
17649@brief The color used for the subsurface scattering approximation.
17650*/
17651LinearColorF subSurfaceColor[ 4 ];
17652/*!
17653@brief The 0 to 1 rolloff factor used in the subsurface scattering approximation.
17654*/
17655float subSurfaceRolloff[ 4 ];
17656/*!
17657@brief Enables emissive lighting for the material.
17658*/
17659bool emissive[ 4 ];
17660/*!
17661@brief Disables backface culling casing surfaces to be double sided. Note that the lighting on the backside will be a mirror of the front side of the surface.
17662*/
17663bool doubleSided;
17664/*!
17665@brief The types of animation to play on this material.
17666*/
17667MaterialAnimType animFlags[ 4 ];
17668/*!
17669@brief The scroll direction in UV space when scroll animation is enabled.
17670*/
17671Point2F scrollDir[ 4 ];
17672/*!
17673@brief The speed to scroll the texture in UVs per second when scroll animation is enabled.
17674*/
17675float scrollSpeed[ 4 ];
17676/*!
17677@brief The speed to rotate the texture in degrees per second when rotation animation is enabled.
17678*/
17679float rotSpeed[ 4 ];
17680/*!
17681@brief The piviot position in UV coordinates to center the rotation animation.
17682*/
17683Point2F rotPivotOffset[ 4 ];
17684/*!
17685@brief The type of wave animation to perform when wave animation is enabled.
17686*/
17687MaterialWaveType waveType[ 4 ];
17688/*!
17689@brief The wave frequency when wave animation is enabled.
17690*/
17691float waveFreq[ 4 ];
17692/*!
17693@brief The wave amplitude when wave animation is enabled.
17694*/
17695float waveAmp[ 4 ];
17696/*!
17697@brief The number of frames per second for frame based sequence animations if greater than zero.
17698*/
17699float sequenceFramePerSec[ 4 ];
17700/*!
17701@brief The size of each frame in UV units for sequence animations.
17702*/
17703float sequenceSegmentSize[ 4 ];
17704/*!
17705@brief @internal
17706*/
17707Point2I cellIndex[ 4 ];
17708/*!
17709@brief @internal
17710*/
17711Point2I cellLayout[ 4 ];
17712/*!
17713@brief @internal
17714*/
17715int cellSize[ 4 ];
17716/*!
17717@brief @internal
17718*/
17719bool bumpAtlas[ 4 ];
17720/*!
17721@brief For backwards compatibility.
17722
17723@see diffuseMap
17724
17725*/
17726filename baseTex[ 4 ];
17727/*!
17728@brief For backwards compatibility.
17729
17730@see detailMap
17731
17732*/
17733filename detailTex[ 4 ];
17734/*!
17735@brief For backwards compatibility.
17736
17737@see overlayMap
17738
17739*/
17740filename overlayTex[ 4 ];
17741/*!
17742@brief For backwards compatibility.
17743
17744@see normalMap
17745
17746*/
17747filename bumpTex[ 4 ];
17748/*!
17749@brief For backwards compatibility.
17750
17751@see diffuseColor
17752
17753*/
17754LinearColorF colorMultiply[ 4 ];
17755/*!
17756@brief If set to false the lighting system will not cast shadows from this material.
17757*/
17758bool castShadows;
17759/*!
17760@brief @internal
17761*/
17762bool planarReflection;
17763/*!
17764@brief If true this material is translucent blended.
17765*/
17766bool translucent;
17767/*!
17768@brief The type of blend operation to use when the material is translucent.
17769*/
17770MaterialBlendOp translucentBlendOp;
17771/*!
17772@brief If enabled and the material is translucent it will write into the depth buffer.
17773*/
17774bool translucentZWrite;
17775/*!
17776@brief Enables alpha test when rendering the material.
17777
17778@see alphaRef
17779
17780*/
17781bool alphaTest;
17782/*!
17783@brief The alpha reference value for alpha testing.  Must be between 0 to 255.
17784
17785@see alphaTest
17786
17787*/
17788int alphaRef;
17789/*!
17790@brief The name of a CubemapData for environment mapping.
17791*/
17792string cubemap;
17793/*!
17794@brief Enables the material to use the dynamic cubemap from the ShapeBase object its applied to.
17795*/
17796bool dynamicCubemap;
17797
17798/*! @name Behavioral
17799@{ */
17800/*!
17801@brief Whether to show player footprint decals on this material.
17802
17803
17804@see PlayerData::decalData
17805*/
17806bool showFootprints;
17807/*!
17808@brief Whether to emit dust particles from a shape moving over the material.  This is, for example, used by vehicles or players to decide whether to show dust trails.
17809*/
17810bool showDust;
17811/*!
17812@brief If #showDust is true, this is the set of colors to use for the ParticleData of the dust emitter.
17813
17814
17815@see ParticleData::colors
17816*/
17817LinearColorF effectColor[ 2 ];
17818/*!
17819@brief What sound to play from the PlayerData sound list when the player walks over the material.  -1 (default) to not play any sound.
17820
17821
17822The IDs are:
17823
17824- 0: PlayerData::FootSoftSound
17825- 1: PlayerData::FootHardSound
17826- 2: PlayerData::FootMetalSound
17827- 3: PlayerData::FootSnowSound
17828- 4: PlayerData::FootShallowSound
17829- 5: PlayerData::FootWadingSound
17830- 6: PlayerData::FootUnderwaterSound
17831- 7: PlayerData::FootBubblesSound
17832- 8: PlayerData::movingBubblesSound
17833- 9: PlayerData::waterBreathSound
17834- 10: PlayerData::impactSoftSound
17835- 11: PlayerData::impactHardSound
17836- 12: PlayerData::impactMetalSound
17837- 13: PlayerData::impactSnowSound
17838- 14: PlayerData::impactWaterEasy
17839- 15: PlayerData::impactWaterMedium
17840- 16: PlayerData::impactWaterHard
17841- 17: PlayerData::exitingWater
17842
17843*/
17844int footstepSoundId;
17845/*!
17846@brief The sound to play when the player walks over the material.  If this is set, it overrides #footstepSoundId.  This field is useful for directly assigning custom footstep sounds to materials without having to rely on the PlayerData sound assignment.
17847
17848
17849@warn Be aware that materials are client-side objects.  This means that the SFXTracks assigned to materials must be client-side, too.
17850*/
17851SFXTrack customFootstepSound;
17852/*!
17853@brief What sound to play from the PlayerData sound list when the player impacts on the surface with a velocity equal or greater than PlayerData::groundImpactMinSpeed.
17854
17855
17856For a list of IDs, see #footstepSoundId
17857*/
17858int impactSoundId;
17859/*!
17860@brief What FX to play from the PlayerData sound list when the player impacts on the surface with a velocity equal or greater than PlayerData::groundImpactMinSpeed.
17861
17862
17863For a list of IDs, see #impactFXId
17864*/
17865int ImpactFXIndex;
17866/*!
17867@brief The sound to play when the player impacts on the surface with a velocity equal or greater than PlayerData::groundImpactMinSpeed.  If this is set, it overrides #impactSoundId.  This field is useful for directly assigning custom impact sounds to materials without having to rely on the PlayerData sound assignment.
17868
17869
17870@warn Be aware that materials are client-side objects.  This means that the SFXTracks assigned to materials must be client-side, too.
17871*/
17872SFXTrack customImpactSound;
17873/// @}
17874
17875
17876/*! @name Ungrouped
17877@{ */
17878/// @}
17879
17880
17881/*! @name Object
17882@{ */
17883/// @}
17884
17885
17886/*! @name Editing
17887@{ */
17888/// @}
17889
17890
17891/*! @name Persistence
17892@{ */
17893/// @}
17894
17895};
17896
17897/*!
17898@brief Material object which provides more control over surface properties.
17899
17900CustomMaterials allow the user to specify their own shaders via the ShaderData datablock. Because CustomMaterials are derived from Materials, they can hold a lot of the same properties. It is up to the user to code how these properties are used.
17901
17902@tsexample
17903singleton CustomMaterial( WaterBasicMat )
17904{
17905   sampler["reflectMap"] = "$reflectbuff";
17906   sampler["refractBuff"] = "$backbuff";
17907
17908   cubemap = NewLevelSkyCubemap;
17909   shader = WaterBasicShader;
17910   stateBlock = WaterBasicStateBlock;
17911   version = 2.0;
17912};
17913@endtsexample
17914
17915@see Material, GFXStateBlockData, ShaderData
17916
17917@ingroup Materials
17918
17919*/
17920class CustomMaterial : public Material {
17921public:
17922
17923/*! @name Callbacks
17924@{ */
17925/// @}
17926
17927/*!
17928@brief @brief Specifies pixel shader version for hardware.
17929
17930
17931Valid pixel shader versions include 2.0, 3.0, etc. @note All features aren't compatible with all pixel shader versions.
17932*/
17933float version;
17934/*!
17935@brief @brief Alternate material for targeting lower end hardware.
17936
17937
17938If the CustomMaterial requires a higher pixel shader version than the one it's using, it's fallback Material will be processed instead. If the fallback material wasn't defined, Torque 3D will assert and attempt to use a very basic material in it's place.
17939
17940
17941*/
17942Material fallback;
17943/*!
17944@brief @brief Name of the ShaderData to use for this effect.
17945
17946
17947
17948*/
17949string shader;
17950/*!
17951@brief @brief Name of a GFXStateBlockData for this effect.
17952
17953
17954
17955*/
17956GFXStateBlockData stateBlock;
17957/*!
17958@brief @brief String identifier of this material's target texture.
17959*/
17960string Target;
17961/*!
17962@brief @brief Determines if the material should recieve lights in Basic Lighting. Has no effect in Advanced Lighting.
17963
17964
17965
17966*/
17967bool forwardLit;
17968
17969/*! @name Behavioral
17970@{ */
17971/// @}
17972
17973
17974/*! @name Ungrouped
17975@{ */
17976/// @}
17977
17978
17979/*! @name Object
17980@{ */
17981/// @}
17982
17983
17984/*! @name Editing
17985@{ */
17986/// @}
17987
17988
17989/*! @name Persistence
17990@{ */
17991/// @}
17992
17993};
17994
17995/*!
17996@brief The abstract base for all render bins.
17997
17998The render bins are used by the engine as a high level method to order and batch rendering operations.
17999@ingroup RenderBin
18000
18001*/
18002class RenderBinManager : public SimObject {
18003public:
18004/*!
18005@brief Returns the bin type string.
18006
18007*/
18008string getBinType();
18009/*!
18010@brief Returns the bin render order.
18011
18012*/
18013float getRenderOrder();
18014
18015/*! @name Callbacks
18016@{ */
18017/// @}
18018
18019/*!
18020@brief Sets the render bin type which limits what render instances are added to this bin.
18021*/
18022string binType;
18023/*!
18024@brief Defines the order for rendering in relation to other bins.
18025*/
18026float renderOrder;
18027/*!
18028@brief Defines the order for adding instances in relation to other bins.
18029*/
18030float processAddOrder;
18031/*!
18032@brief Limites the render bin to basic lighting only.
18033*/
18034bool basicOnly;
18035
18036/*! @name Ungrouped
18037@{ */
18038/// @}
18039
18040
18041/*! @name Object
18042@{ */
18043/// @}
18044
18045
18046/*! @name Editing
18047@{ */
18048/// @}
18049
18050
18051/*! @name Persistence
18052@{ */
18053/// @}
18054
18055};
18056
18057/*!
18058@brief A render bin for mesh rendering.
18059
18060This is the primary render bin in Torque which does most of the work of rendering DTS shapes and arbitrary mesh geometry.  It knows how to render mesh instances using materials and supports hardware mesh instancing.
18061
18062@ingroup RenderBin
18063
18064*/
18065class RenderMeshMgr : public RenderBinManager {
18066public:
18067
18068/*! @name Callbacks
18069@{ */
18070/// @}
18071
18072
18073/*! @name Ungrouped
18074@{ */
18075/// @}
18076
18077
18078/*! @name Object
18079@{ */
18080/// @}
18081
18082
18083/*! @name Editing
18084@{ */
18085/// @}
18086
18087
18088/*! @name Persistence
18089@{ */
18090/// @}
18091
18092};
18093
18094/*!
18095@brief An abstract base class for render bin managers that render to a named textue target.
18096
18097This bin itself doesn't do any rendering work.  It offers functionality to manage a texture render target which derived render bin classes can render into.
18098
18099@see RenderDeferredMgr
18100@ingroup RenderBin
18101
18102*/
18103class RenderTexTargetBinManager : public RenderBinManager {
18104public:
18105
18106/*! @name Callbacks
18107@{ */
18108/// @}
18109
18110
18111/*! @name Ungrouped
18112@{ */
18113/// @}
18114
18115
18116/*! @name Object
18117@{ */
18118/// @}
18119
18120
18121/*! @name Editing
18122@{ */
18123/// @}
18124
18125
18126/*! @name Persistence
18127@{ */
18128/// @}
18129
18130};
18131
18132/*!
18133@brief The render bin which performs a z+normals deferred used in Advanced Lighting.
18134
18135This render bin is used in Advanced Lighting to gather all opaque mesh render instances and render them to the g-buffer for use in lighting the scene and doing effects.
18136
18137PostEffect and other shaders can access the output of this bin by using the #deferred texture target name.  See the edge anti-aliasing post effect for an example.
18138
18139@see game/core/scripts/client/postFx/edgeAA.cs
18140@ingroup RenderBin
18141
18142*/
18143class RenderDeferredMgr : public RenderTexTargetBinManager {
18144public:
18145
18146/*! @name Callbacks
18147@{ */
18148/// @}
18149
18150
18151/*! @name Ungrouped
18152@{ */
18153/// @}
18154
18155
18156/*! @name Object
18157@{ */
18158/// @}
18159
18160
18161/*! @name Editing
18162@{ */
18163/// @}
18164
18165
18166/*! @name Persistence
18167@{ */
18168/// @}
18169
18170};
18171
18172/*!
18173@brief Abstract base class for RenderFormatToken, used to manipulate what goes on in the render manager
18174
18175You cannot actually instantiate RenderPassToken, only its child: RenderFormatToken. RenderFormatToken is an implementation which changes the format of the back buffer and/or the depth buffer.
18176
18177The RenderPassStateBin manager changes the rendering state associated with a token it is declared with. In stock Torque 3D, a single example exists in the way of AL_FormatToken (found in renderManager.cs). In that script file, all the render managers are intialized, and a single RenderFormatToken is used. This implementation basically exists to ensure Advanced Lighting works with MSAA.
18178
18179@see RenderFormatToken
18180@see RenderPassStateBin
18181@see game/core/scripts/client/renderManager.cs
18182@ingroup RenderBin
18183
18184*/
18185class RenderPassStateToken : public SimObject {
18186public:
18187/*!
18188@brief Enables the token.*/
18189void enable();
18190/*!
18191@brief Disables the token.*/
18192void disable();
18193/*!
18194@brief Toggles the token from enabled to disabled or vice versa.*/
18195void toggle();
18196
18197/*! @name Callbacks
18198@{ */
18199/// @}
18200
18201/*!
18202@brief Enables or disables this token.
18203*/
18204bool Enabled;
18205
18206/*! @name Ungrouped
18207@{ */
18208/// @}
18209
18210
18211/*! @name Object
18212@{ */
18213/// @}
18214
18215
18216/*! @name Editing
18217@{ */
18218/// @}
18219
18220
18221/*! @name Persistence
18222@{ */
18223/// @}
18224
18225};
18226
18227/*!
18228@brief Used to change the render target format when rendering in AL.
18229
18230RenderFormatToken is an implementation which changes the format of the back buffer and/or the depth buffer.
18231
18232The RenderPassStateBin manager changes the rendering state associated with this token. In stock Torque 3D, a single example exists in the way of AL_FormatToken (found in renderManager.cs). In that script file, all the render managers are intialized, and a single RenderFormatToken is used. This implementation basically exists to ensure Advanced Lighting works with MSAA.
18233
18234The actions for this token toggle the format of the back/depth buffers and it lets you specify a custom shader to "copy" the data so it can be reformatted or altered. This is done through the variables copyEffect and resolveEffect (which are post processes just like fog or glow)
18235
18236@tsexample
18237// This token, and the associated render managers, ensure that driver MSAA does not get used for Advanced Lighting renders.
18238// The 'AL_FormatResolve' PostEffect copies the result to the backbuffer.
18239new RenderFormatToken(AL_FormatToken)
18240{
18241   enabled = "false";
18242
18243   format = "GFXFormatR8G8B8A8";
18244   depthFormat = "GFXFormatD24S8";
18245   aaLevel = 0; // -1 = match backbuffer
18246
18247   // The contents of the back buffer before this format token is executed
18248   // is provided in $inTex
18249   copyEffect = "AL_FormatCopy";
18250
18251   // The contents of the render target created by this format token is
18252   // provided in $inTex
18253   resolveEffect = "AL_FormatCopy";
18254};
18255@endtsexample
18256
18257@see RenderPassToken
18258
18259@see RenderPassStateBin
18260@see game/core/scripts/client/renderManager.cs
18261@ingroup GFX
18262
18263*/
18264class RenderFormatToken : public RenderPassStateToken {
18265public:
18266
18267/*! @name Callbacks
18268@{ */
18269/// @}
18270
18271/*!
18272@brief Sets the color buffer format for this token.
18273*/
18274GFXFormat Format;
18275/*!
18276@brief Sets the depth/stencil buffer format for this token.
18277*/
18278GFXFormat depthFormat;
18279/*!
18280@brief This PostEffect will be run when the render target is changed to the format specified by this token. It is used to copy/format data into the token rendertarget
18281*/
18282PostEffect copyEffect;
18283/*!
18284@brief This PostEffect will be run when the render target is changed back to the format active prior to this token. It is used to copy/format data from the token rendertarget to the backbuffer.
18285*/
18286PostEffect resolveEffect;
18287/*!
18288@brief Anti-ailiasing level for the this token. 0 disables, -1 uses adapter default.
18289*/
18290int aaLevel;
18291
18292/*! @name Ungrouped
18293@{ */
18294/// @}
18295
18296
18297/*! @name Object
18298@{ */
18299/// @}
18300
18301
18302/*! @name Editing
18303@{ */
18304/// @}
18305
18306
18307/*! @name Persistence
18308@{ */
18309/// @}
18310
18311};
18312
18313/*!
18314@brief A render bin for the glow pass.
18315
18316When the glow buffer PostEffect is enabled this bin gathers mesh render instances with glow materials and renders them to the #glowbuffer offscreen render target.
18317
18318This render target is then used by the 'GlowPostFx' PostEffect to blur and render the glowing portions of the screen.
18319
18320@ingroup RenderBin
18321
18322*/
18323class RenderGlowMgr : public RenderTexTargetBinManager {
18324public:
18325
18326/*! @name Callbacks
18327@{ */
18328/// @}
18329
18330
18331/*! @name Ungrouped
18332@{ */
18333/// @}
18334
18335
18336/*! @name Object
18337@{ */
18338/// @}
18339
18340
18341/*! @name Editing
18342@{ */
18343/// @}
18344
18345
18346/*! @name Persistence
18347@{ */
18348/// @}
18349
18350};
18351
18352/*!
18353@brief A render bin for batch rendering imposters.
18354
18355This render bin gathers imposter render instances and renders them in large batches.
18356
18357You can type 'metrics( imposter )' in the console to see rendering statistics.
18358
18359@ingroup RenderBin
18360
18361*/
18362class RenderImposterMgr : public RenderBinManager {
18363public:
18364
18365/*! @name Callbacks
18366@{ */
18367/// @}
18368
18369
18370/*! @name Ungrouped
18371@{ */
18372/// @}
18373
18374
18375/*! @name Object
18376@{ */
18377/// @}
18378
18379
18380/*! @name Editing
18381@{ */
18382/// @}
18383
18384
18385/*! @name Persistence
18386@{ */
18387/// @}
18388
18389};
18390
18391/*!
18392@brief A render bin which uses object callbacks for rendering.
18393
18394This render bin gathers object render instances and calls its delegate method to perform rendering.  It is used infrequently for specialized scene objects which perform custom rendering.
18395
18396@ingroup RenderBin
18397
18398*/
18399class RenderObjectMgr : public RenderBinManager {
18400public:
18401
18402/*! @name Callbacks
18403@{ */
18404/// @}
18405
18406
18407/*! @name Ungrouped
18408@{ */
18409/// @}
18410
18411
18412/*! @name Object
18413@{ */
18414/// @}
18415
18416
18417/*! @name Editing
18418@{ */
18419/// @}
18420
18421
18422/*! @name Persistence
18423@{ */
18424/// @}
18425
18426};
18427
18428/*!
18429@brief A render bin which renders occlusion query requests.
18430
18431This render bin gathers occlusion query render instances and renders them. It is currently used by light flares and ShapeBase reflection cubemaps.
18432
18433You can type '$RenderOcclusionMgr::debugRender = true' in the console to see debug rendering of the occlusion geometry.
18434
18435@ingroup RenderBin
18436
18437*/
18438class RenderOcclusionMgr : public RenderBinManager {
18439public:
18440
18441/*! @name Callbacks
18442@{ */
18443/// @}
18444
18445/*!
18446@brief A debugging feature which renders the occlusion volumes to the scene.
18447@see RenderOcclusionMgr
18448@ingroup RenderBin
18449*/
18450static bool debugRender;
18451
18452/*! @name Ungrouped
18453@{ */
18454/// @}
18455
18456
18457/*! @name Object
18458@{ */
18459/// @}
18460
18461
18462/*! @name Editing
18463@{ */
18464/// @}
18465
18466
18467/*! @name Persistence
18468@{ */
18469/// @}
18470
18471};
18472
18473/*!
18474@brief A render bin which renders particle geometry.
18475
18476This render bin gathers particle render instances, sorts, and renders them. It is currently used by ParticleEmitter and LightFlareData.
18477
18478@ingroup RenderBin
18479
18480*/
18481class RenderParticleMgr : public RenderTexTargetBinManager {
18482public:
18483
18484/*! @name Callbacks
18485@{ */
18486/// @}
18487
18488
18489/*! @name Ungrouped
18490@{ */
18491/// @}
18492
18493
18494/*! @name Object
18495@{ */
18496/// @}
18497
18498
18499/*! @name Editing
18500@{ */
18501/// @}
18502
18503
18504/*! @name Persistence
18505@{ */
18506/// @}
18507
18508};
18509
18510/*!
18511@brief A non-rendering render bin used to enable/disable a RenderPassStateToken.
18512
18513This is a utility RenderBinManager which does not render any render instances.  Its only used to define a point in the render bin order at which a RenderPassStateToken is triggered.
18514
18515@see RenderPassStateToken
18516@ingroup RenderBin
18517
18518*/
18519class RenderPassStateBin : public RenderBinManager {
18520public:
18521
18522/*! @name Callbacks
18523@{ */
18524/// @}
18525
18526/*!
18527*/
18528RenderPassStateToken stateToken;
18529
18530/*! @name Ungrouped
18531@{ */
18532/// @}
18533
18534
18535/*! @name Object
18536@{ */
18537/// @}
18538
18539
18540/*! @name Editing
18541@{ */
18542/// @}
18543
18544
18545/*! @name Persistence
18546@{ */
18547/// @}
18548
18549};
18550
18551/*!
18552@brief A render bin for terrain mesh rendering.
18553
18554This bin renders terrain render instances from a TerrainBlock. Normally a mesh would render via the RenderMeshMgr, but terrain uses a TerrainMaterial designed for multi-layered surfaces which this bin can processs.
18555
18556@ingroup RenderBin
18557
18558*/
18559class RenderTerrainMgr : public RenderBinManager {
18560public:
18561
18562/*! @name Callbacks
18563@{ */
18564/// @}
18565
18566/*!
18567@brief Used to enable wireframe rendering on terrain for debugging.
18568
18569@ingroup RenderBin
18570*/
18571static bool renderWireframe;
18572
18573/*! @name Ungrouped
18574@{ */
18575/// @}
18576
18577
18578/*! @name Object
18579@{ */
18580/// @}
18581
18582
18583/*! @name Editing
18584@{ */
18585/// @}
18586
18587
18588/*! @name Persistence
18589@{ */
18590/// @}
18591
18592};
18593
18594/*!
18595@brief A render bin for rendering translucent meshes.
18596
18597This bin is used to render translucent render mesh instances and render object instances. It is generally ordered late in the RenderPassManager after all opaque geometry bins.
18598
18599@ingroup RenderBin
18600
18601*/
18602class RenderTranslucentMgr : public RenderBinManager {
18603public:
18604
18605/*! @name Callbacks
18606@{ */
18607/// @}
18608
18609
18610/*! @name Ungrouped
18611@{ */
18612/// @}
18613
18614
18615/*! @name Object
18616@{ */
18617/// @}
18618
18619
18620/*! @name Editing
18621@{ */
18622/// @}
18623
18624
18625/*! @name Persistence
18626@{ */
18627/// @}
18628
18629};
18630
18631/*!
18632@brief A datablock which defines performance and quality properties for dynamic reflections.
18633
18634ReflectorDesc is not itself a reflection and does not render reflections. It is a dummy class for holding and exposing to the user a set of reflection related properties. Objects which support dynamic reflections may then reference a ReflectorDesc.
18635
18636@tsexample
18637datablock ReflectorDesc( ExampleReflectorDesc )
18638{
18639   texSize = 256;
18640   nearDist = 0.1;
18641   farDist = 500;
18642   objectTypeMask = 0xFFFFFFFF;
18643   detailAdjust = 1.0;
18644   priority = 1.0;
18645   maxRateMs = 0;
18646   useOcclusionQuery = true;
18647};
18648@endtsexample
18649@see ShapeBaseData::cubeReflectorDesc
18650@ingroup enviroMisc
18651*/
18652class ReflectorDesc : public SimDataBlock {
18653public:
18654
18655/*! @name Callbacks
18656@{ */
18657/// @}
18658
18659
18660/*! @name ReflectorDesc
18661@{ */
18662/*!
18663@brief Size in pixels of the (square) reflection texture. For a cubemap this value is interpreted as size of each face.
18664*/
18665int texSize;
18666/*!
18667@brief Near plane distance to use when rendering this reflection. Adjust this to limit self-occlusion artifacts.
18668*/
18669float nearDist;
18670/*!
18671@brief Far plane distance to use when rendering reflections.
18672*/
18673float farDist;
18674/*!
18675@brief Object types which render into this reflection.
18676*/
18677int objectTypeMask;
18678/*!
18679@brief Scale applied to lod calculation of objects rendering into this reflection ( modulates $pref::TS::detailAdjust ).
18680*/
18681float detailAdjust;
18682/*!
18683@brief Priority for updating this reflection, relative to others.
18684*/
18685float priority;
18686/*!
18687@brief If less than maxRateMs has elapsed since this relfection was last updated, then do not update it again. This 'skip' can be disabled by setting maxRateMs to zero.
18688*/
18689int maxRateMs;
18690/*!
18691@brief If available on the device use HOQs to determine if the reflective object is visible before updating its reflection.
18692*/
18693bool useOcclusionQuery;
18694/// @}
18695
18696
18697/*! @name Ungrouped
18698@{ */
18699/// @}
18700
18701
18702/*! @name Object
18703@{ */
18704/// @}
18705
18706
18707/*! @name Editing
18708@{ */
18709/// @}
18710
18711
18712/*! @name Persistence
18713@{ */
18714/// @}
18715
18716};
18717
18718/*!
18719@brief Superclass for all ghostable networked objects.
18720
18721@ingroup Networking
18722
18723*/
18724class NetObject : public SimGroup {
18725public:
18726/*!
18727@brief Cause the NetObject to be forced as scoped on the specified NetConnection.
18728
18729@param client The connection this object will always be scoped to
18730
18731@tsexample
18732// Called to create new cameras in TorqueScript
18733// %this - The active GameConnection
18734// %spawnPoint - The spawn point location where we creat the camera
18735function GameConnection::spawnCamera(%this, %spawnPoint)
18736{
18737   // If this connection's camera exists
18738   if(isObject(%this.camera))
18739   {
18740      // Add it to the mission group to be cleaned up later
18741      MissionCleanup.add( %this.camera );
18742
18743      // Force it to scope to the client side
18744      %this.camera.scopeToClient(%this);
18745   }
18746}
18747@endtsexample
18748
18749@see clearScopeToClient()*/
18750void scopeToClient( NetConnection client );
18751/*!
18752@brief Undo the effects of a scopeToClient() call.
18753
18754@param client The connection to remove this object's scoping from 
18755
18756@see scopeToClient()*/
18757void clearScopeToClient( NetConnection client );
18758/*!
18759@brief Always scope this object on all connections.
18760
18761The object is marked as ScopeAlways and is immediately ghosted to all active connections.  This function has no effect if the object is not marked as Ghostable.*/
18762void setScopeAlways();
18763/*!
18764@brief Get the ghost index of this object from the server.
18765
18766@returns The ghost ID of this NetObject on the server
18767@tsexample
18768%ghostID = LocalClientConnection.getGhostId( %serverObject );
18769@endtsexample*/
18770int getGhostID();
18771/*!
18772@brief Returns a pointer to the client object when on a local connection.
18773
18774Short-Circuit-Networking: this is only valid for a local-client / singleplayer situation.
18775
18776@returns the SimObject ID of the client object.
18777@tsexample
18778// Psuedo-code, some values left out for this example
18779%node = new ParticleEmitterNode(){};
18780%clientObject = %node.getClientObject();
18781if(isObject(%clientObject)
18782   %clientObject.setTransform("0 0 0");
18783
18784@endtsexample
18785
18786@see @ref local_connections*/
18787int getClientObject();
18788/*!
18789@brief Returns a pointer to the client object when on a local connection.
18790
18791Short-Circuit-Netorking: this is only valid for a local-client / singleplayer situation.
18792
18793@returns The SimObject ID of the server object.
18794@tsexample
18795// Psuedo-code, some values left out for this example
18796%node = new ParticleEmitterNode(){};
18797%serverObject = %node.getServerObject();
18798if(isObject(%serverObject)
18799   %serverObject.setTransform("0 0 0");
18800
18801@endtsexample
18802
18803@see @ref local_connections*/
18804int getServerObject();
18805/*!
18806@brief Called to check if an object resides on the clientside.
18807
18808@return True if the object resides on the client, false otherwise.*/
18809bool isClientObject();
18810/*!
18811@brief Checks if an object resides on the server.
18812
18813@return True if the object resides on the server, false otherwise.*/
18814bool isServerObject();
18815/*!
18816@brief Clears the scope always flag on this object.*/
18817void clearScopeAlways();
18818
18819/*! @name Callbacks
18820@{ */
18821/// @}
18822
18823
18824/*! @name Ungrouped
18825@{ */
18826/// @}
18827
18828
18829/*! @name Object
18830@{ */
18831/// @}
18832
18833
18834/*! @name Editing
18835@{ */
18836/// @}
18837
18838
18839/*! @name Persistence
18840@{ */
18841/// @}
18842
18843};
18844
18845/*!
18846@brief A networkable object that exists in the 3D world.
18847
18848The SceneObject class provides the foundation for 3D objects in the Engine.  It exposes the functionality for:
18849
18850<ul><li>Position, rotation and scale within the world.</li><li>Working with a scene graph (in the Zone and Portal sections), allowing efficient and robust rendering of the game scene.</li><li>Various helper functions, including functions to get bounding information and momentum/velocity.</li><li>Mounting one SceneObject to another.</li><li>An interface for collision detection, as well as ray casting.</li><li>Lighting. SceneObjects can register lights both at lightmap generation time, and dynamic lights at runtime (for special effects, such as from flame or a projectile, or from an explosion).</li></ul>
18851
18852You do not typically work with SceneObjects themselves.  The SceneObject provides a reference within the game world (the scene), but does not render to the client on its own.  The same is true of collision detection beyond that of the bounding box.  Instead you use one of the many classes that derrive from SceneObject, such as TSStatic.
18853
18854@section SceneObject_Hiding Difference Between setHidden() and isRenderEnabled
18855
18856When it comes time to decide if a SceneObject should render or not, there are two methods that can stop the SceneObject from rendering at all.  You need to be aware of the differences between these two methods as they impact how the SceneObject is networked from the server to the client.
18857
18858The first method of manually controlling if a SceneObject is rendered is through its SceneObject::isRenderEnabled property.  When set to false the SceneObject is considered invisible but still present within the scene.  This means it still takes part in collisions and continues to be networked.
18859
18860The second method is using the setHidden() method.  This will actually remove a SceneObject from the scene and it will no longer be networked from the server to the cleint.  Any client-side ghost of the object will be deleted as the server no longer considers the object to be in scope.
18861
18862@ingroup gameObjects
18863
18864*/
18865class SceneObject : public NetObject {
18866public:
18867/*!
18868@brief Return the type mask for this object.
18869
18870@return The numeric type mask for the object.*/
18871int getType();
18872/*!
18873@brief Mount objB to this object at the desired slot with optional transform.
18874
18875@param objB  Object to mount onto us
18876@param slot  Mount slot ID
18877@param txfm (optional) mount offset transform
18878@return true if successful, false if failed (objB is not valid)*/
18879bool mountObject( SceneObject objB, int slot, TransformF txfm=TransformF::Identity );
18880/*!
18881@brief Unmount an object from ourselves.
18882
18883@param target object to unmount
18884@return true if successful, false if failed*/
18885bool unmountObject( SceneObject target );
18886/*!
18887@brief Unmount us from the currently mounted object if any.
18888
18889*/
18890void unmount();
18891/*!
18892@brief Check if we are mounted to another object.
18893
18894@return true if mounted to another object, false if not mounted.*/
18895bool isMounted();
18896/*!
18897@brief Get the object we are mounted to.
18898
18899@return the SimObjectID of the object we're mounted to, or 0 if not mounted.*/
18900int getObjectMount();
18901/*!
18902@brief Get the number of objects mounted to us.
18903
18904@return the number of mounted objects.*/
18905int getMountedObjectCount();
18906/*!
18907@brief Get the object mounted at a particular slot.
18908
18909@param slot mount slot index to query
18910@return ID of the object mounted in the slot, or 0 if no object.*/
18911int getMountedObject( int slot );
18912/*!
18913@brief Get the mount node index of the object mounted at our given slot.
18914
18915@param slot mount slot index to query
18916@return index of the mount node used by the object mounted in this slot.*/
18917int getMountedObjectNode( int slot );
18918/*!
18919@brief Get the object mounted at our given node index.
18920
18921@param node mount node index to query
18922@return ID of the first object mounted at the node, or 0 if none found.*/
18923int getMountNodeObject( int node );
18924/*!
18925@brief Get the object's transform.
18926
18927@return the current transform of the object
18928*/
18929TransformF getTransform();
18930/*!
18931@brief Get the object's inverse transform.
18932
18933@return the inverse transform of the object
18934*/
18935TransformF getInverseTransform();
18936/*!
18937@brief Get the object's world position.
18938
18939@return the current world position of the object
18940*/
18941Point3F getPosition();
18942/*!
18943@brief Set the object's world position.
18944
18945@param pos the new world position of the object
18946*/
18947void setPosition( Point3F pos );
18948/*!
18949@brief Get Euler rotation of this object.
18950
18951@return the orientation of the object in the form of rotations around the X, Y and Z axes in degrees.
18952*/
18953Point3F getEulerRotation();
18954/*!
18955@brief Get the direction this object is facing.
18956
18957@return a vector indicating the direction this object is facing.
18958@note This is the object's y axis.*/
18959VectorF getForwardVector();
18960/*!
18961@brief Get the right vector of the object.
18962
18963@return a vector indicating the right direction of this object.@note This is the object's x axis.*/
18964VectorF getRightVector();
18965/*!
18966@brief Get the up vector of the object.
18967
18968@return a vector indicating the up direction of this object.@note This is the object's z axis.*/
18969VectorF getUpVector();
18970/*!
18971@brief Set the object's transform (orientation and position).@param txfm object transform to set
18972
18973*/
18974void setTransform( TransformF txfm );
18975/*!
18976@brief Get the object's scale.
18977
18978@return object scale as a Point3F*/
18979Point3F getScale();
18980/*!
18981@brief Set the object's scale.
18982
18983@param scale object scale to set
18984*/
18985void setScale( Point3F scale );
18986/*!
18987@brief Get the object's world bounding box.
18988
18989@return six fields, two Point3Fs, containing the min and max points of the worldbox.*/
18990Box3F getWorldBox();
18991/*!
18992@brief Get the center of the object's world bounding box.
18993
18994@return the center of the world bounding box for this object.*/
18995Point3F getWorldBoxCenter();
18996/*!
18997@brief Get the object's bounding box (relative to the object's origin).
18998
18999@return six fields, two Point3Fs, containing the min and max points of the objectbox.*/
19000Box3F getObjectBox();
19001/*!
19002@brief Check if this object has a global bounds set.
19003
19004If global bounds are set to be true, then the object is assumed to have an infinitely large bounding box for collision and rendering purposes.
19005@return true if the object has a global bounds.*/
19006bool isGlobalBounds();
19007/*!
19008@brief Sets the forward vector of a scene object, making it face Y+ along the new vector.
19009
19010@param The new forward vector to set.
19011@param (Optional) The up vector to use to help orient the rotation.*/
19012void setForwardVector( VectorF newForward=VectorF(0, 0, 0), VectorF upVector=VectorF(0, 0, 1) );
19013/*!
19014@brief returns number of direct child objects
19015
19016*/
19017int getNumChildren();
19018/*!
19019@brief returns number of recursively-nested child objects
19020
19021*/
19022int getNumProgeny();
19023/*!
19024@brief getChild(S32 index) -- returns child SceneObject at given index
19025
19026*/
19027int getChild( int _index=0 );
19028/*!
19029@brief Mount object to this one with the specified offset expressed in our coordinate space.
19030
19031*/
19032bool attachChildAt( SceneObject _subObject=nullAsType<SceneObject*>(), MatrixF _offset=MatrixF::Identity, int _node=0 );
19033/*!
19034@brief attachToParent(SceneObject)specify a null or non-null parent
19035
19036*/
19037bool attachToParent( string _sceneObject );
19038/*!
19039@brief returns ID of parent SceneObject
19040
19041*/
19042int getParent();
19043/*!
19044@brief attach an object to this one, preserving its present transform.
19045
19046*/
19047bool attachChild( string _subObject );
19048/*!
19049@brief SceneObject subObject
19050
19051*/
19052bool detachChild( string _subObject );
19053/*!
19054@brief Returns the velocity of a scene-object.
19055
19056
19057@ingroup AFX*/
19058float getSpeed();
19059
19060/*! @name Callbacks
19061@{ */
19062/// @}
19063
19064/*!
19065@brief Disables rendering of all instances of this type.
19066
19067
19068@ingroup UNDOCUMENTED
19069*/
19070static bool isRenderable;
19071/*!
19072@brief Disables selection of all instances of this type.
19073
19074
19075@ingroup UNDOCUMENTED
19076*/
19077static bool isSelectable;
19078
19079/*! @name GameObject
19080@{ */
19081/*!
19082@brief The asset Id used for the game object this entity is based on.
19083*/
19084GameObjectAssetPtr GameObject;
19085/*!
19086@brief If this entity is a GameObject, it flags if this instance delinates from the template.
19087*/
19088bool dirtyGameObject;
19089/// @}
19090
19091
19092/*! @name Transform
19093@{ */
19094/*!
19095@brief Object world position.
19096*/
19097MatrixPosition position;
19098/*!
19099@brief Object world orientation.
19100*/
19101MatrixRotation rotation;
19102/*!
19103@brief Object world scale.
19104*/
19105Point3F scale;
19106/// @}
19107
19108
19109/*! @name Editing
19110@{ */
19111/*!
19112@brief Controls client-side rendering of the object.
19113
19114@see isRenderable()
19115
19116*/
19117bool isRenderEnabled;
19118/*!
19119@brief Determines if the object may be selected from wihin the Tools.
19120
19121@see isSelectable()
19122
19123*/
19124bool isSelectionEnabled;
19125/// @}
19126
19127
19128/*! @name Mounting
19129@{ */
19130/*!
19131@brief @brief PersistentID of object we are mounted to.
19132
19133
19134Unlike the SimObjectID that is determined at run time, the PersistentID of an object is saved with the level/mission and may be used to form a link between objects.
19135*/
19136pid mountPID;
19137/*!
19138@brief Node we are mounted to.
19139*/
19140int mountNode;
19141/*!
19142@brief Position we are mounted at ( object space of our mount object ).
19143*/
19144MatrixPosition mountPos;
19145/*!
19146@brief Rotation we are mounted at ( object space of our mount object ).
19147*/
19148MatrixRotation mountRot;
19149/// @}
19150
19151
19152/*! @name Ungrouped
19153@{ */
19154/// @}
19155
19156
19157/*! @name Object
19158@{ */
19159/// @}
19160
19161
19162/*! @name Editing
19163@{ */
19164/// @}
19165
19166
19167/*! @name Persistence
19168@{ */
19169/// @}
19170
19171};
19172
19173/*!
19174@brief A single joint, or knot, along a path. Should be stored inside a Path container object. A path markers can be
19175one of three primary movement types: "normal", "Position Only", or "Kink". 
19176@tsexample
19177new path()
19178   {
19179     isLooping = "1";
19180
19181     new Marker()
19182      {
19183         seqNum = "0";
19184         type = "Normal";
19185         msToNext = "1000";
19186         smoothingType = "Spline";
19187         position = "-0.054708 -35.0612 234.802";
19188         rotation = "1 0 0 0";
19189      };
19190
19191   };
19192@endtsexample
19193@see Path
19194@ingroup enviroMisc
19195
19196*/
19197class Marker : public SceneObject {
19198public:
19199
19200/*! @name Callbacks
19201@{ */
19202/// @}
19203
19204/*!
19205@brief Disables rendering of all instances of this type.
19206
19207
19208@ingroup UNDOCUMENTED
19209*/
19210static bool isRenderable;
19211/*!
19212@brief Disables selection of all instances of this type.
19213
19214
19215@ingroup UNDOCUMENTED
19216*/
19217static bool isSelectable;
19218
19219/*! @name Misc
19220@{ */
19221/*!
19222@brief Marker position in sequence of markers on this path.
19223
19224
19225*/
19226int seqNum;
19227/*!
19228@brief Type of this marker/knot. A "normal" knot will have a smooth camera translation/rotation effect.
19229
19230"Position Only" will do the same for translations, leaving rotation un-touched.
19231Lastly, a "Kink" means the rotation will take effect immediately for an abrupt rotation change.
19232
19233*/
19234MarkerKnotType type;
19235/*!
19236@brief Milliseconds to next marker in sequence.
19237
19238
19239*/
19240int msToNext;
19241/*!
19242@brief Path smoothing at this marker/knot. "Linear" means no smoothing, while "Spline" means to smooth.
19243
19244
19245*/
19246MarkerSmoothingType smoothingType;
19247/// @}
19248
19249
19250/*! @name GameObject
19251@{ */
19252/// @}
19253
19254
19255/*! @name Transform
19256@{ */
19257/// @}
19258
19259
19260/*! @name Editing
19261@{ */
19262/// @}
19263
19264
19265/*! @name Mounting
19266@{ */
19267/// @}
19268
19269
19270/*! @name Ungrouped
19271@{ */
19272/// @}
19273
19274
19275/*! @name Object
19276@{ */
19277/// @}
19278
19279
19280/*! @name Editing
19281@{ */
19282/// @}
19283
19284
19285/*! @name Persistence
19286@{ */
19287/// @}
19288
19289};
19290
19291/*!
19292@brief The TerrainMaterial class orginizes the material settings for a single terrain material layer.
19293
19294@note You should not be creating TerrainMaterials by hand in code. All TerrainMaterials should be created in the editors, as intended by the system.
19295
19296@tsexample
19297// Created by the Terrain Painter tool in the World Editor
19298new TerrainMaterial()
19299{
19300   internalName = "grass1";
19301   diffuseMap = "art/terrains/Test/grass1";
19302   detailMap = "art/terrains/Test/grass1_d";
19303   detailSize = "10";
19304   isManaged = "1";
19305   detailBrightness = "1";
19306   Enabled = "1";
19307   diffuseSize = "200";
19308};
19309@endtsexample
19310
19311@see Materials
19312@ingroup enviroMisc
19313
19314*/
19315class TerrainMaterial : public SimObject {
19316public:
19317
19318/*! @name Callbacks
19319@{ */
19320/// @}
19321
19322/*!
19323@brief  ¨ç
19324*/
19325filename DiffuseMap;
19326/*!
19327@brief ðŒE 
19328*/
19329assetIdString DiffuseMapAsset;
19330/*!
19331@brief Used to scale the diffuse map to the material square
19332*/
19333float diffuseSize;
19334/*!
19335@brief ðŒE 
19336*/
19337filename NormalMap;
19338/*!
19339@brief ðŒE 
19340*/
19341assetIdString NormalMapAsset;
19342/*!
19343@brief Used to scale the height from the normal map to give some self occlusion effect (aka parallax) to the terrain material
19344*/
19345float parallaxScale;
19346/*!
19347@brief A fixed value to add while blending using heightmap-based blending.Higher numbers = larger blend radius.
19348*/
19349float blendHeightBase;
19350/*!
19351@brief A fixed value to add while blending using heightmap-based blending.Higher numbers = larger blend radius.
19352*/
19353float blendHeightContrast;
19354/*!
19355@brief y 6 
19356*/
19357filename DetailMap;
19358/*!
19359@brief ðŒE 
19360*/
19361assetIdString DetailMapAsset;
19362/*!
19363@brief Used to scale the detail map to the material square
19364*/
19365float detailSize;
19366/*!
19367@brief Exponentially sharpens or lightens the detail map rendering on the material
19368*/
19369float detailStrength;
19370/*!
19371@brief Changes how far camera can see the detail map rendering on the material
19372*/
19373float detailDistance;
19374/*!
19375@brief Makes that terrain material project along the sides of steep slopes instead of projected downwards
19376*/
19377bool useSideProjection;
19378/*!
19379@brief XÅ’E 
19380*/
19381filename ORMConfigMap;
19382/*!
19383@brief ðŒE 
19384*/
19385assetIdString ORMConfigMapAsset;
19386/*!
19387@brief Is the PBR Config map's image in sRGB format?
19388*/
19389bool isSRGB;
19390/*!
19391@brief Should the roughness channel of the PBR Config map be inverted?
19392*/
19393bool invertRoughness;
19394/*!
19395@brief y 6 
19396*/
19397filename MacroMap;
19398/*!
19399@brief ðŒE 
19400*/
19401assetIdString MacroMapAsset;
19402/*!
19403@brief Used to scale the Macro map to the material square
19404*/
19405float macroSize;
19406/*!
19407@brief Exponentially sharpens or lightens the Macro map rendering on the material
19408*/
19409float macroStrength;
19410/*!
19411@brief Changes how far camera can see the Macro map rendering on the material
19412*/
19413float macroDistance;
19414
19415/*! @name Ungrouped
19416@{ */
19417/// @}
19418
19419
19420/*! @name Object
19421@{ */
19422/// @}
19423
19424
19425/*! @name Editing
19426@{ */
19427/// @}
19428
19429
19430/*! @name Persistence
19431@{ */
19432/// @}
19433
19434};
19435
19436/*!
19437@brief Creates and maintains one set of rendertargets to be used by every
19438VolumetricFog object in the scene.
19439
19440Will be loaded at startup end removed when ending game.
19441
19442Methods:
19443 get() returns the currently loaded VolumetricFogRTManager, also accessible
19444 through VFRTM define.
19445 Init() Initializes the rendertargets, called when a VolumetricFog object is
19446 added to the scene.
19447 isInitialed() returns true if Rendertargets are present, false if not, then
19448 Init() should be called to create the rendertargets.
19449 setQuality(U32 Quality) Normally a rendertarget has the same size as the view,
19450 with this method you can scale down the size of it.
19451 Be aware that scaling down will introduce renderartefacts.
19452@ingroup Atmosphere
19453*/
19454class VolumetricFogRTManager : public SceneObject {
19455public:
19456
19457/*! @name Callbacks
19458@{ */
19459/// @}
19460
19461/*!
19462@brief Disables rendering of all instances of this type.
19463
19464
19465@ingroup UNDOCUMENTED
19466*/
19467static bool isRenderable;
19468/*!
19469@brief Disables selection of all instances of this type.
19470
19471
19472@ingroup UNDOCUMENTED
19473*/
19474static bool isSelectable;
19475
19476/*! @name GameObject
19477@{ */
19478/// @}
19479
19480
19481/*! @name Transform
19482@{ */
19483/// @}
19484
19485
19486/*! @name Editing
19487@{ */
19488/// @}
19489
19490
19491/*! @name Mounting
19492@{ */
19493/// @}
19494
19495
19496/*! @name Ungrouped
19497@{ */
19498/// @}
19499
19500
19501/*! @name Object
19502@{ */
19503/// @}
19504
19505
19506/*! @name Editing
19507@{ */
19508/// @}
19509
19510
19511/*! @name Persistence
19512@{ */
19513/// @}
19514
19515};
19516
19517/*!
19518@brief Renders up to three layers of scrolling cloud-cover textures overhead.
19519
19520%BasicClouds always renders overhead, following the camera. It is intended as part of the background of your level, rendering in front of Sky/Sun type objects and behind everything else.
19521
19522The parameters controlling the rendering of each texture are refered to and grouped as 'layers'. They are rendered in sequential order, so, layer 1 obscures layer 0, and so on.
19523
19524BasicClouds is not affected by scene lighting and is therefore not appropriate for scenes in which lighting radically changes, such as day/night.
19525
19526@ingroup Atmosphere
19527*/
19528class BasicClouds : public SceneObject {
19529public:
19530
19531/*! @name Callbacks
19532@{ */
19533/// @}
19534
19535/*!
19536@brief Disables rendering of all instances of this type.
19537
19538
19539@ingroup UNDOCUMENTED
19540*/
19541static bool isRenderable;
19542/*!
19543@brief Disables selection of all instances of this type.
19544
19545
19546@ingroup UNDOCUMENTED
19547*/
19548static bool isSelectable;
19549
19550/*! @name BasicClouds
19551@{ */
19552/*!
19553@brief Enable or disable rendering of this layer.
19554*/
19555bool layerEnabled[ 3 ];
19556/*!
19557@brief Texture for this layer.
19558*/
19559filename texture[ 3 ];
19560/*!
19561@brief Texture repeat for this layer.
19562*/
19563float texScale[ 3 ];
19564/*!
19565@brief Texture scroll direction for this layer, relative to the world axis.
19566*/
19567Point2F texDirection[ 3 ];
19568/*!
19569@brief Texture scroll speed for this layer.
19570*/
19571float texSpeed[ 3 ];
19572/*!
19573@brief UV offset for this layer.
19574*/
19575Point2F texOffset[ 3 ];
19576/*!
19577@brief Abstract number which controls the curvature and height of the dome mesh
19578*/
19579float height[ 3 ];
19580/// @}
19581
19582
19583/*! @name GameObject
19584@{ */
19585/// @}
19586
19587
19588/*! @name Transform
19589@{ */
19590/// @}
19591
19592
19593/*! @name Editing
19594@{ */
19595/// @}
19596
19597
19598/*! @name Mounting
19599@{ */
19600/// @}
19601
19602
19603/*! @name Ungrouped
19604@{ */
19605/// @}
19606
19607
19608/*! @name Object
19609@{ */
19610/// @}
19611
19612
19613/*! @name Editing
19614@{ */
19615/// @}
19616
19617
19618/*! @name Persistence
19619@{ */
19620/// @}
19621
19622};
19623
19624/*!
19625@brief A layer of clouds which change shape over time and are affected by scene lighting.
19626
19627%CloudLayer always renders overhead, following the camera. It is intended as part of the background of your level, rendering in front of Sky/Sun type objects and behind everything else.
19628
19629The illusion of clouds forming and changing over time is controlled by the normal/opacity texture and the three sets of texture animation parameters. The texture is sampled three times.  The first sample defines overall cloud density, where clouds are likely to form and their general size and shape. The second two samples control how it changes over time; they are combined and used as modifiers to the first sample.
19630
19631%CloudLayer is affected by scene lighting and is designed to be used in scenes with dynamic lighting or time of day changes.
19632
19633@ingroup Atmosphere
19634*/
19635class CloudLayer : public SceneObject {
19636public:
19637
19638/*! @name Callbacks
19639@{ */
19640/// @}
19641
19642/*!
19643@brief Disables rendering of all instances of this type.
19644
19645
19646@ingroup UNDOCUMENTED
19647*/
19648static bool isRenderable;
19649/*!
19650@brief Disables selection of all instances of this type.
19651
19652
19653@ingroup UNDOCUMENTED
19654*/
19655static bool isSelectable;
19656
19657/*! @name CloudLayer
19658@{ */
19659/*!
19660@brief An RGBA texture which should contain normals and opacity (density).
19661*/
19662filename texture;
19663/*!
19664@brief Controls the texture repeat of this slot.
19665*/
19666float texScale[ 3 ];
19667/*!
19668@brief Controls the direction this slot scrolls.
19669*/
19670Point2F texDirection[ 3 ];
19671/*!
19672@brief Controls the speed this slot scrolls.
19673*/
19674float texSpeed[ 3 ];
19675/*!
19676@brief Base cloud color before lighting.
19677*/
19678LinearColorF baseColor;
19679/*!
19680@brief Brightness scale so CloudLayer can be overblown if desired.
19681*/
19682float exposure;
19683/*!
19684@brief Fraction of sky covered by clouds 0-1.
19685*/
19686float coverage;
19687/*!
19688@brief Overall scalar to texture scroll speed.
19689*/
19690float windSpeed;
19691/*!
19692@brief Abstract number which controls the curvature and height of the dome mesh.
19693*/
19694float height;
19695/// @}
19696
19697
19698/*! @name GameObject
19699@{ */
19700/// @}
19701
19702
19703/*! @name Transform
19704@{ */
19705/// @}
19706
19707
19708/*! @name Editing
19709@{ */
19710/// @}
19711
19712
19713/*! @name Mounting
19714@{ */
19715/// @}
19716
19717
19718/*! @name Ungrouped
19719@{ */
19720/// @}
19721
19722
19723/*! @name Object
19724@{ */
19725/// @}
19726
19727
19728/*! @name Editing
19729@{ */
19730/// @}
19731
19732
19733/*! @name Persistence
19734@{ */
19735/// @}
19736
19737};
19738
19739/*!
19740@brief Abstract base class for representing a body of water.
19741
19742%WaterObject is abstract and may not be created. It defines functionality shared by its derived classes.
19743
19744%WaterObject exposes many fields for controlling it visual quality.
19745
19746%WaterObject surface rendering has the following general features:
19747   - Waves represented by vertex undulation and user paramaters.
19748   - Ripples represented by a normal map and user parameters.
19749   - Refraction of underwater objects.
19750   - Dynamic planar reflection or static cubemap reflection.
19751   - Paramable water fog and color shift.
19752
19753It will, however, look significantly different depending on the LightingManager that is active. With Basic Lighting, we do not have a deferred texture to lookup per-pixel depth and therefore cannot use our rendering techniques that depend on it.
19754
19755In particular, the following field groups are not used under Basic Lighting:
19756   - Underwater Fogging 
19757   - Misc 
19758   - Distortion 
19759   - And foam related fields under the %WaterObject group.
19760
19761%WaterObject also defines several fields for gameplay use and objects that support buoyancy.
19762
19763@ingroup Water
19764*/
19765class WaterObject : public SceneObject {
19766public:
19767
19768/*! @name Callbacks
19769@{ */
19770/// @}
19771
19772/*!
19773@brief If true, will render the wireframe of the WaterObject.
19774
19775@ingroup Water
19776*/
19777static bool wireframe;
19778/*!
19779@brief Disables rendering of all instances of this type.
19780
19781
19782@ingroup UNDOCUMENTED
19783*/
19784static bool isRenderable;
19785/*!
19786@brief Disables selection of all instances of this type.
19787
19788
19789@ingroup UNDOCUMENTED
19790*/
19791static bool isSelectable;
19792
19793/*! @name WaterObject
19794@{ */
19795/*!
19796@brief Affects buoyancy of an object, thus affecting the Z velocity of a player (jumping, falling, etc.
19797*/
19798float density;
19799/*!
19800@brief Affects drag force applied to an object submerged in this container.
19801*/
19802float viscosity;
19803/*!
19804@brief Liquid type of WaterBlock, such as water, ocean, lava Currently only Water is defined and used.
19805*/
19806string liquidType;
19807/*!
19808@brief Changes color of water fog.
19809*/
19810ColorI baseColor;
19811/*!
19812@brief Extent of fresnel affecting reflection fogging.
19813*/
19814float fresnelBias;
19815/*!
19816@brief Measures intensity of affect on reflection based on fogging.
19817*/
19818float fresnelPower;
19819/*!
19820@brief Power used for specularity on the water surface ( sun only ).
19821*/
19822float specularPower;
19823/*!
19824@brief Color used for specularity on the water surface ( sun only ).
19825*/
19826LinearColorF specularColor;
19827/*!
19828@brief When true the water colors don't react to changes to environment lighting.
19829*/
19830bool emissive;
19831/*!
19832@brief Direction waves flow toward shores.
19833*/
19834Point2F waveDir[ 3 ];
19835/*!
19836@brief Speed of water undulation.
19837*/
19838float waveSpeed[ 3 ];
19839/*!
19840@brief Height of water undulation.
19841*/
19842float waveMagnitude[ 3 ];
19843/*!
19844@brief Master variable affecting entire body of water's undulation
19845*/
19846float overallWaveMagnitude;
19847/*!
19848@brief Normal map used to simulate small surface ripples
19849*/
19850filename rippleTex;
19851/*!
19852@brief Modifies the direction of ripples on the surface.
19853*/
19854Point2F rippleDir[ 3 ];
19855/*!
19856@brief Modifies speed of surface ripples.
19857*/
19858float rippleSpeed[ 3 ];
19859/*!
19860@brief Intensifies the affect of the normal map applied to the surface.
19861*/
19862Point2F rippleTexScale[ 3 ];
19863/*!
19864@brief Intensifies the vertext modification of the surface.
19865*/
19866float rippleMagnitude[ 3 ];
19867/*!
19868@brief Master variable affecting entire surface
19869*/
19870float overallRippleMagnitude;
19871/*!
19872@brief Diffuse texture for foam in shallow water (advanced lighting only)
19873*/
19874filename foamTex;
19875/*!
19876*/
19877Point2F foamDir[ 2 ];
19878/*!
19879*/
19880float foamSpeed[ 2 ];
19881/*!
19882@brief applied to the surface.
19883*/
19884Point2F foamTexScale[ 2 ];
19885/*!
19886*/
19887float foamOpacity[ 2 ];
19888/*!
19889*/
19890float overallFoamOpacity;
19891/*!
19892*/
19893float foamMaxDepth;
19894/*!
19895*/
19896float foamAmbientLerp;
19897/*!
19898*/
19899float foamRippleInfluence;
19900/// @}
19901
19902
19903/*! @name Reflect
19904@{ */
19905/*!
19906@brief Cubemap used instead of reflection texture if fullReflect is off.
19907*/
19908string cubemap;
19909/*!
19910@brief Enables dynamic reflection rendering.
19911*/
19912bool fullReflect;
19913/*!
19914@brief Overall scalar to the reflectivity of the water surface.
19915*/
19916float reflectivity;
19917/*!
19918@brief Affects the sort order of reflected objects.
19919*/
19920float reflectPriority;
19921/*!
19922@brief Affects the sort time of reflected objects.
19923*/
19924int reflectMaxRateMs;
19925/*!
19926@brief scale up or down the detail level for objects rendered in a reflection
19927*/
19928float reflectDetailAdjust;
19929/*!
19930@brief always use z up as the reflection normal
19931*/
19932bool reflectNormalUp;
19933/*!
19934@brief turn off reflection rendering when occluded (delayed).
19935*/
19936bool useOcclusionQuery;
19937/*!
19938@brief The texture size used for reflections (square)
19939*/
19940int reflectTexSize;
19941/// @}
19942
19943
19944/*! @name Underwater Fogging
19945@{ */
19946/*!
19947@brief Intensity of underwater fogging.
19948*/
19949float waterFogDensity;
19950/*!
19951@brief Delta, or limit, applied to waterFogDensity.
19952*/
19953float waterFogDensityOffset;
19954/*!
19955@brief The depth in world units at which full darkening will be received, giving a wet look to objects underwater.
19956*/
19957float wetDepth;
19958/*!
19959@brief The refract color intensity scaled at wetDepth.
19960*/
19961float wetDarkening;
19962/// @}
19963
19964
19965/*! @name Misc
19966@{ */
19967/*!
19968@brief 1D texture defining the base water color by depth
19969*/
19970filename depthGradientTex;
19971/*!
19972@brief Depth in world units, the max range of the color gradient texture.
19973*/
19974float depthGradientMax;
19975/// @}
19976
19977
19978/*! @name Distortion
19979@{ */
19980/*!
19981@brief Determines start of distortion effect where water surface intersects the camera near plane.
19982*/
19983float distortStartDist;
19984/*!
19985@brief Max distance that distortion algorithm is performed. The lower, the more distorted the effect.
19986*/
19987float distortEndDist;
19988/*!
19989@brief Determines the scaling down of distortion in shallow water.
19990*/
19991float distortFullDepth;
19992/// @}
19993
19994
19995/*! @name Basic Lighting
19996@{ */
19997/*!
19998@brief Relative opacity or transparency of the water surface.
19999*/
20000float clarity;
20001/*!
20002@brief Changes the color shading of objects beneath the water surface.
20003*/
20004ColorI underwaterColor;
20005/// @}
20006
20007
20008/*! @name Sound
20009@{ */
20010/*!
20011@brief Ambient sound environment when listener is submerged.
20012*/
20013SFXAmbience soundAmbience;
20014/// @}
20015
20016
20017/*! @name GameObject
20018@{ */
20019/// @}
20020
20021
20022/*! @name Transform
20023@{ */
20024/// @}
20025
20026
20027/*! @name Editing
20028@{ */
20029/// @}
20030
20031
20032/*! @name Mounting
20033@{ */
20034/// @}
20035
20036
20037/*! @name Ungrouped
20038@{ */
20039/// @}
20040
20041
20042/*! @name Object
20043@{ */
20044/// @}
20045
20046
20047/*! @name Editing
20048@{ */
20049/// @}
20050
20051
20052/*! @name Persistence
20053@{ */
20054/// @}
20055
20056};
20057
20058/*!
20059@brief A block shaped water volume defined by a 3D scale and orientation.
20060
20061@see WaterObject for inherited functionality.
20062
20063@ingroup Water
20064*/
20065class WaterBlock : public WaterObject {
20066public:
20067
20068/*! @name Callbacks
20069@{ */
20070/// @}
20071
20072/*!
20073@brief Disables rendering of all instances of this type.
20074
20075
20076@ingroup UNDOCUMENTED
20077*/
20078static bool isRenderable;
20079/*!
20080@brief Disables selection of all instances of this type.
20081
20082
20083@ingroup UNDOCUMENTED
20084*/
20085static bool isSelectable;
20086
20087/*! @name WaterBlock
20088@{ */
20089/*!
20090@brief Spacing between vertices in the WaterBlock mesh
20091*/
20092float gridElementSize;
20093/*!
20094@brief Duplicate of gridElementSize for backwards compatility
20095*/
20096float gridSize;
20097/// @}
20098
20099
20100/*! @name WaterObject
20101@{ */
20102/// @}
20103
20104
20105/*! @name Reflect
20106@{ */
20107/// @}
20108
20109
20110/*! @name Underwater Fogging
20111@{ */
20112/// @}
20113
20114
20115/*! @name Misc
20116@{ */
20117/// @}
20118
20119
20120/*! @name Distortion
20121@{ */
20122/// @}
20123
20124
20125/*! @name Basic Lighting
20126@{ */
20127/// @}
20128
20129
20130/*! @name Sound
20131@{ */
20132/// @}
20133
20134
20135/*! @name GameObject
20136@{ */
20137/// @}
20138
20139
20140/*! @name Transform
20141@{ */
20142/// @}
20143
20144
20145/*! @name Editing
20146@{ */
20147/// @}
20148
20149
20150/*! @name Mounting
20151@{ */
20152/// @}
20153
20154
20155/*! @name Ungrouped
20156@{ */
20157/// @}
20158
20159
20160/*! @name Object
20161@{ */
20162/// @}
20163
20164
20165/*! @name Editing
20166@{ */
20167/// @}
20168
20169
20170/*! @name Persistence
20171@{ */
20172/// @}
20173
20174};
20175
20176/*!
20177@brief Represents a large body of water stretching to the horizon in all directions.
20178
20179WaterPlane's position is defined only height, the z element of position, it is infinite in xy and depth. %WaterPlane is designed to represent the ocean on an island scene and viewed from ground level; other uses may not be appropriate and a WaterBlock may be used.
20180
20181@see WaterObject for inherited functionality.
20182
20183Limitations:
20184
20185Because %WaterPlane cannot be projected exactly to the far-clip distance, other objects nearing this distance can have noticible artifacts as they clip through first the %WaterPlane and then the far plane.
20186
20187To avoid this large objects should be positioned such that they will not line up with the far-clip from vantage points the player is expected to be. In particular, your TerrainBlock should be completely contained by the far-clip distance.
20188
20189Viewing %WaterPlane from a high altitude with a tight far-clip distance will accentuate this limitation. %WaterPlane is primarily designed to be viewed from ground level.
20190
20191@ingroup Water
20192*/
20193class WaterPlane : public WaterObject {
20194public:
20195
20196/*! @name Callbacks
20197@{ */
20198/// @}
20199
20200/*!
20201@brief Disables rendering of all instances of this type.
20202
20203
20204@ingroup UNDOCUMENTED
20205*/
20206static bool isRenderable;
20207/*!
20208@brief Disables selection of all instances of this type.
20209
20210
20211@ingroup UNDOCUMENTED
20212*/
20213static bool isSelectable;
20214
20215/*! @name WaterPlane
20216@{ */
20217/*!
20218@brief Spacing between vertices in the WaterBlock mesh
20219*/
20220int gridSize;
20221/*!
20222@brief Duplicate of gridElementSize for backwards compatility
20223*/
20224float gridElementSize;
20225/// @}
20226
20227
20228/*! @name WaterObject
20229@{ */
20230/// @}
20231
20232
20233/*! @name Reflect
20234@{ */
20235/// @}
20236
20237
20238/*! @name Underwater Fogging
20239@{ */
20240/// @}
20241
20242
20243/*! @name Misc
20244@{ */
20245/// @}
20246
20247
20248/*! @name Distortion
20249@{ */
20250/// @}
20251
20252
20253/*! @name Basic Lighting
20254@{ */
20255/// @}
20256
20257
20258/*! @name Sound
20259@{ */
20260/// @}
20261
20262
20263/*! @name GameObject
20264@{ */
20265/// @}
20266
20267
20268/*! @name Transform
20269@{ */
20270/// @}
20271
20272
20273/*! @name Editing
20274@{ */
20275/// @}
20276
20277
20278/*! @name Mounting
20279@{ */
20280/// @}
20281
20282
20283/*! @name Ungrouped
20284@{ */
20285/// @}
20286
20287
20288/*! @name Object
20289@{ */
20290/// @}
20291
20292
20293/*! @name Editing
20294@{ */
20295/// @}
20296
20297
20298/*! @name Persistence
20299@{ */
20300/// @}
20301
20302};
20303
20304/*!
20305@brief Base class for defining a type of ForestItem. It does not implement loading or rendering of the shapeFile.
20306
20307@ingroup Forest
20308*/
20309class ForestItemData : public SimDataBlock {
20310public:
20311
20312/*! @name Callbacks
20313@{ */
20314/// @}
20315
20316
20317/*! @name Ungrouped
20318@{ */
20319/// @}
20320
20321
20322/*! @name Object
20323@{ */
20324/// @}
20325
20326
20327/*! @name Editing
20328@{ */
20329/// @}
20330
20331
20332/*! @name Persistence
20333@{ */
20334/// @}
20335
20336
20337/*! @name Media
20338@{ */
20339/*!
20340@brief Shape file for this item type
20341*/
20342filename shapeFile;
20343/*!
20344@brief Can other objects or spacial queries hit items of this type.
20345*/
20346bool collidable;
20347/*!
20348@brief Radius used during placement to ensure items are not crowded.
20349*/
20350float radius;
20351/// @}
20352
20353
20354/*! @name Wind
20355@{ */
20356/*!
20357@brief Mass used in calculating spring forces on the trunk. Generally how springy a plant is.
20358*/
20359float mass;
20360/*!
20361@brief Rigidity used in calculating spring forces on the trunk. How much the plant resists the wind force
20362*/
20363float rigidity;
20364/*!
20365@brief Coefficient used in calculating spring forces on the trunk. How much the plant resists bending.
20366*/
20367float tightnessCoefficient;
20368/*!
20369@brief Coefficient used in calculating spring forces on the trunk. Causes oscillation and forces to decay faster over time.
20370*/
20371float dampingCoefficient;
20372/*!
20373@brief Overall scale to the effect of wind.
20374*/
20375float windScale;
20376/*!
20377@brief Overall bend amount of the tree trunk by wind and impacts.
20378*/
20379float trunkBendScale;
20380/*!
20381@brief Amplitude of the effect on larger branches.
20382*/
20383float branchAmp;
20384/*!
20385@brief Amplitude of the winds effect on leafs/fronds.
20386*/
20387float detailAmp;
20388/*!
20389@brief Frequency (speed) of the effect on leafs/fronds.
20390*/
20391float detailFreq;
20392/// @}
20393
20394};
20395
20396/*!
20397@brief Concrete implementation of ForestItemData which loads and renders dts format shapeFiles.
20398
20399@ingroup Forest
20400*/
20401class TSForestItemData : public ForestItemData {
20402public:
20403
20404/*! @name Callbacks
20405@{ */
20406/// @}
20407
20408
20409/*! @name Ungrouped
20410@{ */
20411/// @}
20412
20413
20414/*! @name Object
20415@{ */
20416/// @}
20417
20418
20419/*! @name Editing
20420@{ */
20421/// @}
20422
20423
20424/*! @name Persistence
20425@{ */
20426/// @}
20427
20428
20429/*! @name Media
20430@{ */
20431/// @}
20432
20433
20434/*! @name Wind
20435@{ */
20436/// @}
20437
20438};
20439
20440/*!
20441@brief An invisible shape that allow objects within it to have an accumulation map.
20442
20443AccumulationVolume is used to add additional realism to a scene. It's main use is in outdoor scenes  where objects could benefit from overlaying environment accumulation textures such as sand, snow, etc.
20444
20445Objects within the volume must have accumulation enabled in their material. 
20446
20447@ingroup enviroMisc
20448*/
20449class AccumulationVolume : public SceneObject {
20450public:
20451
20452/*! @name Callbacks
20453@{ */
20454/// @}
20455
20456/*!
20457@brief Disables rendering of all instances of this type.
20458
20459
20460@ingroup UNDOCUMENTED
20461*/
20462static bool isRenderable;
20463/*!
20464@brief Disables selection of all instances of this type.
20465
20466
20467@ingroup UNDOCUMENTED
20468*/
20469static bool isSelectable;
20470/*!
20471@brief Accumulation texture.
20472*/
20473filename texture;
20474
20475/*! @name Internal
20476@{ */
20477/*!
20478@brief For internal use only.
20479*/
20480string plane;
20481/*!
20482@brief For internal use only.
20483*/
20484string point;
20485/*!
20486@brief For internal use only.
20487*/
20488string edge;
20489/// @}
20490
20491
20492/*! @name GameObject
20493@{ */
20494/// @}
20495
20496
20497/*! @name Transform
20498@{ */
20499/// @}
20500
20501
20502/*! @name Editing
20503@{ */
20504/// @}
20505
20506
20507/*! @name Mounting
20508@{ */
20509/// @}
20510
20511
20512/*! @name Ungrouped
20513@{ */
20514/// @}
20515
20516
20517/*! @name Object
20518@{ */
20519/// @}
20520
20521
20522/*! @name Editing
20523@{ */
20524/// @}
20525
20526
20527/*! @name Persistence
20528@{ */
20529/// @}
20530
20531};
20532
20533/*!
20534@brief Scriptable, demo-able datablock.  Used by GameBase objects.
20535
20536@see GameBase
20537@ingroup gameObjects
20538
20539*/
20540class GameBaseData : public SimDataBlock {
20541public:
20542
20543/*! @name Callbacks
20544@{ */
20545/*!
20546@brief Called when the object is added to the scene.
20547
20548@param obj the GameBase object
20549
20550@tsexample
20551datablock GameBaseData(MyObjectData)
20552{
20553   category = "Misc";
20554};
20555
20556function MyObjectData::onAdd( %this, %obj )
20557{
20558   echo( "Added " @ %obj.getName() @ " to the scene." );
20559}
20560
20561function MyObjectData::onNewDataBlock( %this, %obj )
20562{
20563   echo( "Assign " @ %this.getName() @ " datablock to " %obj.getName() );
20564}
20565
20566function MyObjectData::onRemove( %this, %obj )
20567{
20568   echo( "Removed " @ %obj.getName() @ " to the scene." );
20569}
20570
20571function MyObjectData::onMount( %this, %obj, %mountObj, %node )
20572{
20573   echo( %obj.getName() @ " mounted to " @ %mountObj.getName() );
20574}
20575
20576function MyObjectData::onUnmount( %this, %obj, %mountObj, %node )
20577{
20578   echo( %obj.getName() @ " unmounted from " @ %mountObj.getName() );
20579}
20580
20581@endtsexample*/
20582void onAdd( GameBase obj );
20583/*!
20584@brief Called when the object has a new datablock assigned.
20585
20586@param obj the GameBase object
20587
20588@see onAdd for an example*/
20589void onNewDataBlock( GameBase obj );
20590/*!
20591@brief Called when the object is removed from the scene.
20592
20593@param obj the GameBase object
20594
20595@see onAdd for an example*/
20596void onRemove( GameBase obj );
20597/*!
20598@brief Called when the object is mounted to another object in the scene.
20599
20600@param obj the GameBase object being mounted
20601@param mountObj the object we are mounted to
20602@param node the mountObj node we are mounted to
20603
20604@see onAdd for an example*/
20605void onMount( SceneObject obj, SceneObject mountObj, int node );
20606/*!
20607@brief Called when the object is unmounted from another object in the scene.
20608
20609@param obj the GameBase object being unmounted
20610@param mountObj the object we are unmounted from
20611@param node the mountObj node we are unmounted from
20612
20613@see onAdd for an example*/
20614void onUnmount( SceneObject obj, SceneObject mountObj, int node );
20615/// @}
20616
20617
20618/*! @name Scripting
20619@{ */
20620/*!
20621@brief The group that this datablock will show up in under the "Scripted" tab in the World Editor Library.
20622*/
20623caseString category;
20624/// @}
20625
20626
20627/*! @name Ungrouped
20628@{ */
20629/// @}
20630
20631
20632/*! @name Object
20633@{ */
20634/// @}
20635
20636
20637/*! @name Editing
20638@{ */
20639/// @}
20640
20641
20642/*! @name Persistence
20643@{ */
20644/// @}
20645
20646};
20647
20648/*!
20649@brief Defines properties for a ShapeBase object.
20650
20651@see ShapeBase
20652@ingroup gameObjects
20653
20654*/
20655class ShapeBaseData : public GameBaseData {
20656public:
20657/*!
20658@brief Check if there is the space at the given transform is free to spawn into.
20659
20660The shape's bounding box volume is used to check for collisions at the given world transform.  Only interior and static objects are checked for collision.
20661@param txfm Deploy transform to check
20662@return True if the space is free, false if there is already something in the way.
20663@note This is a server side only check, and is not actually limited to spawning.*/
20664bool checkDeployPos( TransformF txfm );
20665/*!
20666@brief Helper method to get a transform from a position and vector (suitable for use with setTransform).
20667
20668@param pos Desired transform position
20669@param normal Vector of desired direction
20670@return The deploy transform*/
20671TransformF getDeployTransform( Point3F pos, Point3F normal );
20672
20673/*! @name Callbacks
20674@{ */
20675/*!
20676@brief Called when the object damage state changes to Enabled.
20677
20678@param obj The ShapeBase object
20679@param lastState The previous damage state*/
20680void onEnabled( ShapeBase obj, string lastState );
20681/*!
20682@brief Called when the object damage state changes to Disabled.
20683
20684@param obj The ShapeBase object
20685@param lastState The previous damage state*/
20686void onDisabled( ShapeBase obj, string lastState );
20687/*!
20688@brief Called when the object damage state changes to Destroyed.
20689
20690@param obj The ShapeBase object
20691@param lastState The previous damage state*/
20692void onDestroyed( ShapeBase obj, string lastState );
20693/*!
20694@brief Called when we collide with another object beyond some impact speed.
20695
20696The Player class makes use of this callback when a collision speed is more than PlayerData::minImpactSpeed.
20697@param obj The ShapeBase object
20698@param collObj The object we collided with
20699@param vec Collision impact vector
20700@param len Length of the impact vector*/
20701void onImpact( ShapeBase obj, SceneObject  collObj, VectorF vec, float len );
20702/*!
20703@brief Called when we collide with another object.
20704
20705@param obj The ShapeBase object
20706@param collObj The object we collided with
20707@param vec Collision impact vector
20708@param len Length of the impact vector*/
20709void onCollision( ShapeBase obj, SceneObject  collObj, VectorF vec, float len );
20710/*!
20711@brief Called when the object is damaged.
20712
20713@param obj The ShapeBase object
20714@param obj The ShapeBase object
20715@param delta The amount of damage received.*/
20716void onDamage( ShapeBase obj, float delta );
20717/*!
20718@brief Called when a move trigger input changes state.
20719
20720@param obj The ShapeBase object
20721@param index Index of the trigger that changed
20722@param state New state of the trigger*/
20723void onTrigger( ShapeBase obj, int index, bool state );
20724/*!
20725@brief Called when a thread playing a non-cyclic sequence reaches the end of the sequence.
20726
20727@param obj The ShapeBase object
20728@param slot Thread slot that finished playing
20729@param name Thread name that finished playing*/
20730void onEndSequence( ShapeBase obj, int slot, string name );
20731/*!
20732@brief Called when the object is forced to uncloak.
20733
20734@param obj The ShapeBase object
20735@param reason String describing why the object was uncloaked*/
20736void onForceUncloak( ShapeBase obj, string reason );
20737/// @}
20738
20739
20740/*! @name Shadows
20741@{ */
20742/*!
20743@brief Enable shadows for this shape (currently unused, shadows are always enabled).
20744*/
20745bool shadowEnable;
20746/*!
20747@brief Size of the projected shadow texture (must be power of 2).
20748*/
20749int shadowSize;
20750/*!
20751@brief Maximum distance at which shadow is visible (currently unused).
20752*/
20753float shadowMaxVisibleDistance;
20754/*!
20755@brief Maximum height above ground to project shadow. If the object is higher than this no shadow will be rendered.
20756*/
20757float shadowProjectionDistance;
20758/*!
20759@brief Scalar applied to the radius of spot shadows (initial radius is based on the shape bounds but can be adjusted with this field).
20760*/
20761float shadowSphereAdjust;
20762/// @}
20763
20764
20765/*! @name Render
20766@{ */
20767/*!
20768@brief The source shape asset.
20769*/
20770assetIdString ShapeAsset;
20771/*!
20772@brief The DTS or DAE model to use for this object.
20773*/
20774filename shapeFile;
20775/// @}
20776
20777
20778/*! @name Destruction
20779Parameters related to the destruction effects of this object.
20780@{ */
20781/*!
20782@brief %Explosion to generate when this shape is blown up.
20783*/
20784ExplosionData Explosion;
20785/*!
20786@brief %Explosion to generate when this shape is blown up underwater.
20787*/
20788ExplosionData underwaterExplosion;
20789/*!
20790@brief %Debris to generate when this shape is blown up.
20791*/
20792DebrisData Debris;
20793/*!
20794@brief Whether to render the shape when it is in the "Destroyed" damage state.
20795*/
20796bool renderWhenDestroyed;
20797/*!
20798@brief The DTS or DAE model to use for auto-generated breakups. @note may not be functional.
20799*/
20800filename debrisShapeName;
20801/// @}
20802
20803
20804/*! @name Physics
20805@{ */
20806/*!
20807@brief Shape mass.
20808
20809Used in simulation of moving objects.
20810
20811*/
20812float mass;
20813/*!
20814@brief Drag factor.
20815
20816Reduces velocity of moving objects.
20817*/
20818float drag;
20819/*!
20820@brief Shape density.
20821
20822Used when computing buoyancy when in water.
20823
20824*/
20825float density;
20826/// @}
20827
20828
20829/*! @name Damage/Energy
20830@{ */
20831/*!
20832@brief Maximum energy level for this object.
20833*/
20834float maxEnergy;
20835/*!
20836@brief Maximum damage level for this object.
20837*/
20838float maxDamage;
20839/*!
20840@brief Damage level above which the object is disabled.
20841
20842Currently unused.
20843*/
20844float disabledLevel;
20845/*!
20846@brief Damage level above which the object is destroyed.
20847
20848When the damage level increases above this value, the object damage state is set to "Destroyed".
20849*/
20850float destroyedLevel;
20851/*!
20852@brief Rate at which damage is repaired in damage units/tick.
20853
20854This value is subtracted from the damage level until it reaches 0.
20855*/
20856float repairRate;
20857/*!
20858@brief Flag controlling whether to manage our own energy level, or to use the energy level of the object we are mounted to.
20859*/
20860bool inheritEnergyFromMount;
20861/*!
20862@brief Invincible flag; when invincible, the object cannot be damaged or repaired.
20863*/
20864bool isInvincible;
20865/// @}
20866
20867
20868/*! @name Camera
20869The settings used by the shape when it is the camera.
20870@{ */
20871/*!
20872@brief The maximum distance from the camera to the object.
20873
20874Used when computing a custom camera transform for this object.
20875
20876@see observeThroughObject
20877*/
20878float cameraMaxDist;
20879/*!
20880@brief The minimum distance from the camera to the object.
20881
20882Used when computing a custom camera transform for this object.
20883
20884@see observeThroughObject
20885*/
20886float cameraMinDist;
20887/*!
20888@brief The default camera vertical FOV in degrees.
20889*/
20890float cameraDefaultFov;
20891/*!
20892@brief The minimum camera vertical FOV allowed in degrees.
20893*/
20894float cameraMinFov;
20895/*!
20896@brief The maximum camera vertical FOV allowed in degrees.
20897*/
20898float cameraMaxFov;
20899/*!
20900@brief If the derrived class supports it, allow the camera to bank.
20901*/
20902bool cameraCanBank;
20903/*!
20904@brief Do mounted images bank along with the camera?
20905*/
20906bool mountedImagesBank;
20907/*!
20908@brief Flag controlling whether the view from this object is first person only.
20909*/
20910bool firstPersonOnly;
20911/*!
20912@brief Flag controlling whether the client uses this object's eye point to view from.
20913*/
20914bool useEyePoint;
20915/*!
20916@brief Observe this object through its camera transform and default fov.
20917
20918If true, when this object is the camera it can provide a custom camera transform and FOV (instead of the default eye transform).
20919*/
20920bool observeThroughObject;
20921/// @}
20922
20923
20924/*! @name Misc
20925@{ */
20926/*!
20927@brief If true, verify that the CRC of the client's shape model matches the server's CRC for the shape model when loaded by the client.
20928*/
20929bool computeCRC;
20930/// @}
20931
20932
20933/*! @name Reflection
20934@{ */
20935/*!
20936@brief References a ReflectorDesc datablock that defines performance and quality properties for dynamic reflections.
20937
20938
20939*/
20940string cubeReflectorDesc;
20941/// @}
20942
20943/*!
20944*/
20945string remapTextureTags;
20946/*!
20947*/
20948bool silentBBoxValidation;
20949
20950/*! @name Scripting
20951@{ */
20952/// @}
20953
20954
20955/*! @name Ungrouped
20956@{ */
20957/// @}
20958
20959
20960/*! @name Object
20961@{ */
20962/// @}
20963
20964
20965/*! @name Editing
20966@{ */
20967/// @}
20968
20969
20970/*! @name Persistence
20971@{ */
20972/// @}
20973
20974};
20975
20976/*!
20977@brief A datablock that describes a camera.
20978
20979@tsexample
20980datablock CameraData(Observer)
20981{
20982   mode = "Observer";
20983};
20984@endtsexample
20985@see Camera
20986
20987@ref Datablock_Networking
20988@ingroup BaseCamera
20989@ingroup Datablocks
20990
20991*/
20992class CameraData : public ShapeBaseData {
20993public:
20994
20995/*! @name Callbacks
20996@{ */
20997/// @}
20998
20999
21000/*! @name Shadows
21001@{ */
21002/// @}
21003
21004
21005/*! @name Render
21006@{ */
21007/// @}
21008
21009
21010/*! @name Destruction
21011Parameters related to the destruction effects of this object.
21012@{ */
21013/// @}
21014
21015
21016/*! @name Physics
21017@{ */
21018/// @}
21019
21020
21021/*! @name Damage/Energy
21022@{ */
21023/// @}
21024
21025
21026/*! @name Camera
21027The settings used by the shape when it is the camera.
21028@{ */
21029/// @}
21030
21031
21032/*! @name Misc
21033@{ */
21034/// @}
21035
21036
21037/*! @name Reflection
21038@{ */
21039/// @}
21040
21041
21042/*! @name Scripting
21043@{ */
21044/// @}
21045
21046
21047/*! @name Ungrouped
21048@{ */
21049/// @}
21050
21051
21052/*! @name Object
21053@{ */
21054/// @}
21055
21056
21057/*! @name Editing
21058@{ */
21059/// @}
21060
21061
21062/*! @name Persistence
21063@{ */
21064/// @}
21065
21066};
21067
21068/*!
21069@brief A renderable, collidable convex shape defined by a collection of surface planes.
21070
21071%ConvexShape is intended to be used as a temporary asset for quickly blocking out a scene or filling in approximate shapes to be later replaced with final assets. This is most easily done by using the WorldEditor's Sketch Tool.
21072
21073@ingroup enviroMisc
21074*/
21075class ConvexShape : public SceneObject {
21076public:
21077
21078/*! @name Callbacks
21079@{ */
21080/// @}
21081
21082/*!
21083@brief Disables rendering of all instances of this type.
21084
21085
21086@ingroup UNDOCUMENTED
21087*/
21088static bool isRenderable;
21089/*!
21090@brief Disables selection of all instances of this type.
21091
21092
21093@ingroup UNDOCUMENTED
21094*/
21095static bool isSelectable;
21096
21097/*! @name Rendering
21098@{ */
21099/*!
21100@brief Material used to render the ConvexShape surface.
21101*/
21102string Material;
21103/// @}
21104
21105
21106/*! @name Internal
21107@{ */
21108/*!
21109@brief Do not modify, for internal use.
21110*/
21111string surface;
21112/*!
21113@brief Do not modify, for internal use.
21114*/
21115string surfaceTexture;
21116/// @}
21117
21118
21119/*! @name GameObject
21120@{ */
21121/// @}
21122
21123
21124/*! @name Transform
21125@{ */
21126/// @}
21127
21128
21129/*! @name Editing
21130@{ */
21131/// @}
21132
21133
21134/*! @name Mounting
21135@{ */
21136/// @}
21137
21138
21139/*! @name Ungrouped
21140@{ */
21141/// @}
21142
21143
21144/*! @name Object
21145@{ */
21146/// @}
21147
21148
21149/*! @name Editing
21150@{ */
21151/// @}
21152
21153
21154/*! @name Persistence
21155@{ */
21156/// @}
21157
21158};
21159
21160/*!
21161@brief Stores properties for an individual debris type.
21162
21163DebrisData defines the base properties for a Debris object.  Typically you'll want a Debris object to consist of a shape and possibly up to two particle emitters.  The DebrisData datablock provides the definition for these items, along with physical properties and how a Debris object will react to other game objects, such as water and terrain.
21164@tsexample
21165datablock DebrisData(GrenadeDebris)
21166{
21167   shapeFile = "art/shapes/weapons/ramrifle/debris.dts";
21168   emitters[0] = GrenadeDebrisFireEmitter;
21169   elasticity = 0.4;
21170   friction = 0.25;
21171   numBounces = 3;
21172   bounceVariance = 1;
21173   explodeOnMaxBounce = false;
21174   staticOnMaxBounce = false;
21175   snapOnMaxBounce = false;
21176   minSpinSpeed = 200;
21177   maxSpinSpeed = 600;
21178   lifetime = 4;
21179   lifetimeVariance = 1.5;
21180   velocity = 15;
21181   velocityVariance = 5;
21182   fade = true;
21183   useRadiusMass = true;
21184   baseRadius = 0.3;
21185   gravModifier = 1.0;
21186   terminalVelocity = 20;
21187   ignoreWater = false;
21188};
21189@endtsexample
21190
21191@see Debris
21192
21193@ingroup FX
21194
21195*/
21196class DebrisData : public GameBaseData {
21197public:
21198
21199/*! @name Callbacks
21200@{ */
21201/// @}
21202
21203
21204/*! @name Display
21205@{ */
21206/*!
21207@brief @brief Texture imagemap to use for this debris object.
21208
21209
21210Not used any more.
21211
21212*/
21213string texture;
21214/*!
21215@brief @brief Object model to use for this debris object.
21216
21217
21218This shape is optional.  You could have Debris made up of only particles.
21219
21220*/
21221filename shapeFile;
21222/// @}
21223
21224
21225/*! @name Datablocks
21226@{ */
21227/*!
21228@brief @brief List of particle emitters to spawn along with this debris object.
21229
21230
21231These are optional.  You could have Debris made up of only a shape.
21232
21233*/
21234ParticleEmitterData emitters[ 2 ];
21235/*!
21236@brief @brief ExplosionData to spawn along with this debris object.
21237
21238
21239This is optional as not all Debris explode.
21240
21241*/
21242ExplosionData Explosion;
21243/// @}
21244
21245
21246/*! @name Physical Properties
21247@{ */
21248/*!
21249@brief @brief A floating-point value specifying how 'bouncy' this object is.
21250
21251
21252Must be in the range of -10 to 10.
21253
21254*/
21255float elasticity;
21256/*!
21257@brief @brief A floating-point value specifying how much velocity is lost to impact and sliding friction.
21258
21259
21260Must be in the range of -10 to 10.
21261
21262*/
21263float friction;
21264/*!
21265@brief @brief How many times to allow this debris object to bounce until it either explodes, becomes static or snaps (defined in explodeOnMaxBounce, staticOnMaxBounce, snapOnMaxBounce).
21266
21267
21268Must be within the range of 0 to 10000.
21269@see bounceVariance
21270
21271*/
21272int numBounces;
21273/*!
21274@brief @brief Allowed variance in the value of numBounces.
21275
21276
21277Must be less than numBounces.
21278@see numBounces
21279
21280*/
21281int bounceVariance;
21282/*!
21283@brief @brief Minimum speed that this debris object will rotate.
21284
21285
21286Must be in the range of -10000 to 1000, and must be less than maxSpinSpeed.
21287@see maxSpinSpeed
21288
21289*/
21290float minSpinSpeed;
21291/*!
21292@brief @brief Maximum speed that this debris object will rotate.
21293
21294
21295Must be in the range of -10000 to 10000.
21296@see minSpinSpeed
21297
21298*/
21299float maxSpinSpeed;
21300/*!
21301@brief How much gravity affects debris.
21302*/
21303float gravModifier;
21304/*!
21305@brief Max velocity magnitude.
21306*/
21307float terminalVelocity;
21308/*!
21309@brief @brief Speed at which this debris object will move.
21310
21311
21312@see velocityVariance
21313
21314*/
21315float velocity;
21316/*!
21317@brief @brief Allowed variance in the value of velocity
21318
21319
21320Must be less than velocity.
21321@see velocity
21322
21323*/
21324float velocityVariance;
21325/*!
21326@brief @brief Amount of time until this debris object is destroyed.
21327
21328
21329Must be in the range of 0 to 1000.
21330@see lifetimeVariance
21331*/
21332float lifetime;
21333/*!
21334@brief @brief Allowed variance in the value of lifetime.
21335
21336
21337Must be less than lifetime.
21338@see lifetime
21339
21340*/
21341float lifetimeVariance;
21342/*!
21343@brief @brief Use mass calculations based on radius.
21344
21345
21346Allows for the adjustment of elasticity and friction based on the Debris size.
21347@see baseRadius
21348
21349*/
21350bool useRadiusMass;
21351/*!
21352@brief @brief Radius at which the standard elasticity and friction apply.
21353
21354
21355Only used when useRaduisMass is true.
21356@see useRadiusMass.
21357
21358*/
21359float baseRadius;
21360/// @}
21361
21362
21363/*! @name Behavior
21364@{ */
21365/*!
21366@brief @brief If true, this debris object will explode after it has bounced max times.
21367
21368
21369Be sure to provide an ExplosionData datablock for this to take effect.
21370@see explosion
21371
21372*/
21373bool explodeOnMaxBounce;
21374/*!
21375@brief If true, this debris object becomes static after it has bounced max times.
21376*/
21377bool staticOnMaxBounce;
21378/*!
21379@brief If true, this debris object will snap into a resting position on the last bounce.
21380*/
21381bool snapOnMaxBounce;
21382/*!
21383@brief @brief If true, this debris object will fade out when destroyed.
21384
21385
21386This fade occurs over the last second of the Debris' lifetime.
21387
21388*/
21389bool fade;
21390/*!
21391@brief If true, this debris object will not collide with water, acting as if the water is not there.
21392*/
21393bool ignoreWater;
21394/// @}
21395
21396
21397/*! @name Scripting
21398@{ */
21399/// @}
21400
21401
21402/*! @name Ungrouped
21403@{ */
21404/// @}
21405
21406
21407/*! @name Object
21408@{ */
21409/// @}
21410
21411
21412/*! @name Editing
21413@{ */
21414/// @}
21415
21416
21417/*! @name Persistence
21418@{ */
21419/// @}
21420
21421};
21422
21423/*!
21424@brief Abstract base class for controls that render 3D scenes.
21425
21426GuiTSCtrl is the base class for controls that render 3D camera views in Torque.  The class itself does not implement a concrete scene rendering.  Use GuiObjectView to display invidiual shapes in the Gui and GameTSCtrl to render full scenes.
21427
21428@see GameTSCtrl
21429@see GuiObjectView
21430@ingroup Gui3D
21431
21432*/
21433class GuiTSCtrl : public GuiContainer {
21434public:
21435/*!
21436@brief Transform 3D screen-space coordinates (x, y, depth) to world space.
21437
21438This method can be, for example, used to find the world-space position relating to the current mouse cursor position.
21439@param screenPosition The x/y position on the screen plus the depth from the screen-plane outwards.
21440@return The world-space position corresponding to the given screen-space coordinates.*/
21441Point3F unproject( Point3F screenPosition );
21442/*!
21443@brief Transform world-space coordinates to screen-space (x, y, depth) coordinates.
21444
21445@param worldPosition The world-space position to transform to screen-space.
21446@return The */
21447Point3F project( Point3F worldPosition );
21448/*!
21449@brief Get the ratio between world-space units and pixels.
21450
21451@return The amount of world-space units covered by the extent of a single pixel.*/
21452Point2F getWorldToScreenScale();
21453/*!
21454@brief Given the camera's current FOV, get the distance from the camera's viewpoint at which the given radius will fit in the render area.
21455
21456@param radius Radius in world-space units which should fit in the view.
21457@return The distance from the viewpoint at which the given radius would be fully visible.*/
21458float calculateViewDistance( float radius );
21459/*!
21460@brief Sets the current stereo texture to an offscreen canvas
21461
21462@param canvas The desired canvas.*/
21463void setStereoGui( GuiOffscreenCanvas canvas );
21464
21465/*! @name Callbacks
21466@{ */
21467/// @}
21468
21469
21470/*! @name Camera
21471@{ */
21472/*!
21473@brief Z rotation angle of camera.
21474*/
21475float cameraZRot;
21476/*!
21477@brief The vertical field of view in degrees or zero to use the normal camera FOV.
21478*/
21479float forceFOV;
21480/// @}
21481
21482
21483/*! @name Rendering
21484@{ */
21485/*!
21486@brief The share of the per-frame reflection update work this control's rendering should run.
21487
21488The reflect update priorities of all visible GuiTSCtrls are added together and each control is assigned a share of the per-frame reflection update time according to its percentage of the total priority value.
21489*/
21490float reflectPriority;
21491/*!
21492@brief Indicates how this control should render its contents.
21493*/
21494GuiTSRenderStyles renderStyle;
21495/// @}
21496
21497
21498/*! @name Layout
21499@{ */
21500/// @}
21501
21502
21503/*! @name Layout
21504@{ */
21505/// @}
21506
21507
21508/*! @name Control
21509@{ */
21510/// @}
21511
21512
21513/*! @name ToolTip
21514@{ */
21515/// @}
21516
21517
21518/*! @name Editing
21519@{ */
21520/// @}
21521
21522
21523/*! @name Localization
21524@{ */
21525/// @}
21526
21527
21528/*! @name Ungrouped
21529@{ */
21530/// @}
21531
21532
21533/*! @name Object
21534@{ */
21535/// @}
21536
21537
21538/*! @name Editing
21539@{ */
21540/// @}
21541
21542
21543/*! @name Persistence
21544@{ */
21545/// @}
21546
21547};
21548
21549/*!
21550@brief The main 3D viewport for a Torque 3D game.
21551
21552@ingroup Gui3D
21553
21554*/
21555class GameTSCtrl : public GuiTSCtrl {
21556public:
21557
21558/*! @name Callbacks
21559@{ */
21560/// @}
21561
21562
21563/*! @name Camera
21564@{ */
21565/// @}
21566
21567
21568/*! @name Rendering
21569@{ */
21570/// @}
21571
21572
21573/*! @name Layout
21574@{ */
21575/// @}
21576
21577
21578/*! @name Layout
21579@{ */
21580/// @}
21581
21582
21583/*! @name Control
21584@{ */
21585/// @}
21586
21587
21588/*! @name ToolTip
21589@{ */
21590/// @}
21591
21592
21593/*! @name Editing
21594@{ */
21595/// @}
21596
21597
21598/*! @name Localization
21599@{ */
21600/// @}
21601
21602
21603/*! @name Ungrouped
21604@{ */
21605/// @}
21606
21607
21608/*! @name Object
21609@{ */
21610/// @}
21611
21612
21613/*! @name Editing
21614@{ */
21615/// @}
21616
21617
21618/*! @name Persistence
21619@{ */
21620/// @}
21621
21622};
21623
21624/*!
21625@brief Stores properties for an individual Item type.
21626
21627Items represent an object in the world, usually one that the player will interact with.  One example is a health kit on the group that is automatically picked up when the player comes into contact with it.
21628
21629ItemData provides the common properties for a set of Items.  These properties include a DTS or DAE model used to render the Item in the world, its physical properties for when the Item interacts with the world (such as being tossed by the player), and any lights that emit from the Item.
21630
21631@tsexample
21632datablock ItemData(HealthKitSmall)
21633{
21634   category ="Health";
21635   className = "HealthPatch";
21636   shapeFile = "art/shapes/items/kit/healthkit.dts";
21637   gravityMod = "1.0";
21638   mass = 2;
21639   friction = 1;
21640   elasticity = 0.3;
21641   density = 2;
21642   drag = 0.5;
21643   maxVelocity = "10.0";
21644   emap = true;
21645   sticky = false;
21646   dynamicType = "0"
21647;   lightOnlyStatic = false;
21648   lightType = "NoLight";
21649   lightColor = "1.0 1.0 1.0 1.0";
21650   lightTime = 1000;
21651   lightRadius = 10.0;
21652   simpleServerCollision = true;   // Dynamic properties used by the scripts
21653
21654   pickupName = "a small health kit";
21655   repairAmount = 50;
21656};
21657@endtsexample
21658@ingroup gameObjects
21659
21660*/
21661class ItemData : public ShapeBaseData {
21662public:
21663
21664/*! @name Callbacks
21665@{ */
21666/// @}
21667
21668/*!
21669@brief A floating-point value specifying how much velocity is lost to impact and sliding friction.
21670*/
21671float friction;
21672/*!
21673@brief A floating-point value specifying how 'bouncy' this ItemData is.
21674*/
21675float elasticity;
21676/*!
21677@brief @brief If true, ItemData will 'stick' to any surface it collides with.
21678
21679
21680When an item does stick to a surface, the Item::onStickyCollision() callback is called.  The Item has methods to retrieve the world position and normal the Item is stuck to.
21681@note Valid objects to stick to must be of StaticShapeObjectType.
21682
21683*/
21684bool sticky;
21685/*!
21686@brief Floating point value to multiply the existing gravity with, just for this ItemData.
21687*/
21688float gravityMod;
21689/*!
21690@brief Maximum velocity that this ItemData is able to move.
21691*/
21692float maxVelocity;
21693/*!
21694@brief Type of light to apply to this ItemData. Options are NoLight, ConstantLight, PulsingLight. Default is NoLight.
21695*/
21696ItemLightType lightType;
21697/*!
21698@brief @brief Color value to make this light. Example: "1.0,1.0,1.0"
21699
21700
21701@see lightType
21702
21703*/
21704LinearColorF lightColor;
21705/*!
21706@brief @brief Time value for the light of this ItemData, used to control the pulse speed of the PulsingLight LightType.
21707
21708
21709@see lightType
21710
21711*/
21712int lightTime;
21713/*!
21714@brief @brief Distance from the center point of this ItemData for the light to affect
21715
21716
21717@see lightType
21718
21719*/
21720float lightRadius;
21721/*!
21722@brief @brief If true, this ItemData will only cast a light if the Item for this ItemData has a static value of true.
21723
21724
21725@see lightType
21726
21727*/
21728bool lightOnlyStatic;
21729/*!
21730@brief @brief Determines if only simple server-side collision will be used (for pick ups).
21731
21732
21733If set to true then only simple, server-side collision detection will be used.  This is often the case if the item is used for a pick up object, such as ammo.  If set to false then a full collision volume will be used as defined by the shape.  The default is true.
21734@note Only applies when using a physics library.
21735@see TurretShape and ProximityMine for examples that should set this to false to allow them to be shot by projectiles.
21736
21737*/
21738bool simpleServerCollision;
21739
21740/*! @name Shadows
21741@{ */
21742/// @}
21743
21744
21745/*! @name Render
21746@{ */
21747/// @}
21748
21749
21750/*! @name Destruction
21751Parameters related to the destruction effects of this object.
21752@{ */
21753/// @}
21754
21755
21756/*! @name Physics
21757@{ */
21758/// @}
21759
21760
21761/*! @name Damage/Energy
21762@{ */
21763/// @}
21764
21765
21766/*! @name Camera
21767The settings used by the shape when it is the camera.
21768@{ */
21769/// @}
21770
21771
21772/*! @name Misc
21773@{ */
21774/// @}
21775
21776
21777/*! @name Reflection
21778@{ */
21779/// @}
21780
21781
21782/*! @name Scripting
21783@{ */
21784/// @}
21785
21786
21787/*! @name Ungrouped
21788@{ */
21789/// @}
21790
21791
21792/*! @name Object
21793@{ */
21794/// @}
21795
21796
21797/*! @name Editing
21798@{ */
21799/// @}
21800
21801
21802/*! @name Persistence
21803@{ */
21804/// @}
21805
21806};
21807
21808/*!
21809@brief Stores and controls the rendering and status information for a game level.
21810
21811@tsexample
21812new LevelInfo(theLevelInfo)
21813{
21814  visibleDistance = "1000";
21815  fogColor = "0.6 0.6 0.7 1";
21816  fogDensity = "0";
21817  fogDensityOffset = "700";
21818  fogAtmosphereHeight = "0";
21819  canvasClearColor = "0 0 0 255";
21820  canSaveDynamicFields = "1";
21821  levelName = "Blank Room";
21822  desc0 = "A blank room ready to be populated with Torque objects.";
21823  Enabled = "1";
21824};
21825@endtsexample
21826@ingroup enviroMisc
21827
21828*/
21829class LevelInfo : public NetObject {
21830public:
21831
21832/*! @name Callbacks
21833@{ */
21834/// @}
21835
21836
21837/*! @name Visibility
21838@{ */
21839/*!
21840@brief Closest distance from the camera's position to render the world.
21841*/
21842float nearClip;
21843/*!
21844@brief Furthest distance from the camera's position to render the world.
21845*/
21846float visibleDistance;
21847/*!
21848@brief Furthest distance from the camera's position to render players. Defaults to visibleDistance.
21849*/
21850float visibleGhostDistance;
21851/*!
21852@brief NearPlane bias used when rendering Decal and DecalRoad. This should be tuned to the visibleDistance in your level.
21853*/
21854float decalBias;
21855/// @}
21856
21857
21858/*! @name Fog
21859@{ */
21860/*!
21861@brief The default color for the scene fog.
21862*/
21863LinearColorF fogColor;
21864/*!
21865@brief The 0 to 1 density value for the exponential fog falloff.
21866*/
21867float fogDensity;
21868/*!
21869@brief An offset from the camera in meters for moving the start of the fog effect.
21870*/
21871float fogDensityOffset;
21872/*!
21873@brief A height in meters for altitude fog falloff.
21874*/
21875float fogAtmosphereHeight;
21876/// @}
21877
21878
21879/*! @name LevelInfo
21880@{ */
21881/*!
21882@brief The color used to clear the background before the scene or any GUIs are rendered.
21883*/
21884ColorI canvasClearColor;
21885/// @}
21886
21887
21888/*! @name Lighting
21889@{ */
21890/*!
21891@brief Number of seconds it takes to blend from one ambient light color to a different one.
21892*/
21893float ambientLightBlendPhase;
21894/*!
21895@brief Interpolation curve to use for blending from one ambient light color to a different one.
21896*/
21897EaseF ambientLightBlendCurve;
21898/*!
21899@brief Accumulation texture.
21900*/
21901filename AccuTexture;
21902/// @}
21903
21904
21905/*! @name Sound
21906@{ */
21907/*!
21908@brief The global ambient sound environment.
21909*/
21910SFXAmbience soundAmbience;
21911/*!
21912@brief The distance attenuation model to use.
21913*/
21914SFXDistanceModel soundDistanceModel;
21915/// @}
21916
21917
21918/*! @name Ungrouped
21919@{ */
21920/// @}
21921
21922
21923/*! @name Object
21924@{ */
21925/// @}
21926
21927
21928/*! @name Editing
21929@{ */
21930/// @}
21931
21932
21933/*! @name Persistence
21934@{ */
21935/// @}
21936
21937};
21938
21939/*!
21940@brief A datablock which defines and performs light animation, such as rotation, brightness fade, and colorization.
21941
21942@tsexample
21943datablock LightAnimData( SubtlePulseLightAnim )
21944{
21945   brightnessA = 0.5;
21946   brightnessZ = 1;
21947   brightnessPeriod = 1;
21948   brightnessKeys = "aza";
21949   brightnessSmooth = true;
21950};
21951@endtsexample
21952
21953@see LightBase
21954
21955@see LightDescription
21956
21957@ingroup FX
21958@ingroup Lighting
21959
21960*/
21961class LightAnimData : public SimDataBlock {
21962public:
21963
21964/*! @name Callbacks
21965@{ */
21966/// @}
21967
21968
21969/*! @name Offset
21970The XYZ translation animation state relative to the light position.
21971@{ */
21972/*!
21973@brief The value of the A key in the keyframe sequence.
21974*/
21975float offsetA[ 3 ];
21976/*!
21977@brief The value of the Z key in the keyframe sequence.
21978*/
21979float OffsetZ[ 3 ];
21980/*!
21981@brief The animation time for keyframe sequence.
21982*/
21983float offsetPeriod[ 3 ];
21984/*!
21985@brief The keyframe sequence encoded into a string where characters from A to Z define a position between the two animation values.
21986*/
21987string offsetKeys[ 3 ];
21988/*!
21989@brief If true the transition between keyframes will be smooth.
21990*/
21991bool offsetSmooth[ 3 ];
21992/// @}
21993
21994
21995/*! @name Rotation
21996The XYZ rotation animation state relative to the light orientation.
21997@{ */
21998/*!
21999@brief The value of the A key in the keyframe sequence.
22000*/
22001float rotA[ 3 ];
22002/*!
22003@brief The value of the Z key in the keyframe sequence.
22004*/
22005float rotZ[ 3 ];
22006/*!
22007@brief The animation time for keyframe sequence.
22008*/
22009float rotPeriod[ 3 ];
22010/*!
22011@brief The keyframe sequence encoded into a string where characters from A to Z define a position between the two animation values.
22012*/
22013string rotKeys[ 3 ];
22014/*!
22015@brief If true the transition between keyframes will be smooth.
22016*/
22017bool rotSmooth[ 3 ];
22018/// @}
22019
22020
22021/*! @name Color
22022The RGB color animation state.
22023@{ */
22024/*!
22025@brief The value of the A key in the keyframe sequence.
22026*/
22027float colorA[ 3 ];
22028/*!
22029@brief The value of the Z key in the keyframe sequence.
22030*/
22031float colorZ[ 3 ];
22032/*!
22033@brief The animation time for keyframe sequence.
22034*/
22035float colorPeriod[ 3 ];
22036/*!
22037@brief The keyframe sequence encoded into a string where characters from A to Z define a position between the two animation values.
22038*/
22039string colorKeys[ 3 ];
22040/*!
22041@brief If true the transition between keyframes will be smooth.
22042*/
22043bool colorSmooth[ 3 ];
22044/// @}
22045
22046
22047/*! @name Brightness
22048The brightness animation state.
22049@{ */
22050/*!
22051@brief The value of the A key in the keyframe sequence.
22052*/
22053float brightnessA;
22054/*!
22055@brief The value of the Z key in the keyframe sequence.
22056*/
22057float brightnessZ;
22058/*!
22059@brief The animation time for keyframe sequence.
22060*/
22061float brightnessPeriod;
22062/*!
22063@brief The keyframe sequence encoded into a string where characters from A to Z define a position between the two animation values.
22064*/
22065string brightnessKeys;
22066/*!
22067@brief If true the transition between keyframes will be smooth.
22068*/
22069bool brightnessSmooth;
22070/// @}
22071
22072
22073/*! @name Ungrouped
22074@{ */
22075/// @}
22076
22077
22078/*! @name Object
22079@{ */
22080/// @}
22081
22082
22083/*! @name Editing
22084@{ */
22085/// @}
22086
22087
22088/*! @name Persistence
22089@{ */
22090/// @}
22091
22092};
22093
22094/*!
22095@brief A very basic class containing information used by MissionMarker objects for rendering
22096
22097MissionMarkerData, is an extremely barebones class derived from ShapeBaseData. It is solely used by MissionMarker classes (such as SpawnSphere), so that you can see the object while editing a level.
22098
22099@tsexample
22100datablock MissionMarkerData(SpawnSphereMarker)
22101{
22102   category = "Misc";
22103   shapeFile = "core/art/shapes/octahedron.dts";
22104};
22105@endtsexample
22106
22107@see MissionMarker
22108
22109@see SpawnSphere
22110
22111@see WayPoint
22112
22113@ingroup enviroMisc
22114
22115*/
22116class MissionMarkerData : public ShapeBaseData {
22117public:
22118
22119/*! @name Callbacks
22120@{ */
22121/// @}
22122
22123
22124/*! @name Shadows
22125@{ */
22126/// @}
22127
22128
22129/*! @name Render
22130@{ */
22131/// @}
22132
22133
22134/*! @name Destruction
22135Parameters related to the destruction effects of this object.
22136@{ */
22137/// @}
22138
22139
22140/*! @name Physics
22141@{ */
22142/// @}
22143
22144
22145/*! @name Damage/Energy
22146@{ */
22147/// @}
22148
22149
22150/*! @name Camera
22151The settings used by the shape when it is the camera.
22152@{ */
22153/// @}
22154
22155
22156/*! @name Misc
22157@{ */
22158/// @}
22159
22160
22161/*! @name Reflection
22162@{ */
22163/// @}
22164
22165
22166/*! @name Scripting
22167@{ */
22168/// @}
22169
22170
22171/*! @name Ungrouped
22172@{ */
22173/// @}
22174
22175
22176/*! @name Object
22177@{ */
22178/// @}
22179
22180
22181/*! @name Editing
22182@{ */
22183/// @}
22184
22185
22186/*! @name Persistence
22187@{ */
22188/// @}
22189
22190};
22191
22192/*!
22193@brief Base class for game objects which use datablocks, networking, are editable, and need to process ticks.
22194
22195@ingroup gameObjects
22196
22197*/
22198class GameBase : public SceneObject {
22199public:
22200/*!
22201@brief Get the datablock used by this object.
22202
22203@return the datablock this GameBase is using.@see setDataBlock()*/
22204int getDataBlock();
22205/*!
22206@brief Assign this GameBase to use the specified datablock.
22207
22208@param data new datablock to use
22209@return true if successful, false if failed.@see getDataBlock()*/
22210bool setDataBlock( GameBaseData data );
22211/*!
22212@brief Apply an impulse to this object as defined by a world position and velocity vector.
22213
22214@param pos impulse world position
22215@param vel impulse velocity (impulse force F = m * v)
22216@return Always true
22217@note Not all objects that derrive from GameBase have this defined.*/
22218bool applyImpulse( Point3F pos, VectorF vel );
22219/*!
22220@brief Applies a radial impulse to the object using the given origin and force.
22221
22222@param origin World point of origin of the radial impulse.
22223@param radius The radius of the impulse area.
22224@param magnitude The strength of the impulse.
22225@note Not all objects that derrive from GameBase have this defined.*/
22226void applyRadialImpulse( Point3F origin, float radius, float magnitude );
22227/*!
22228@brief attach an object to this one, preserving its present transform.
22229
22230*/
22231bool attachChild( GameBase _subObject=nullAsType<GameBase*>() );
22232/*!
22233@brief attach an object to this one, preserving its present transform.
22234
22235*/
22236bool detachChild( GameBase _subObject=nullAsType<GameBase*>() );
22237
22238/*! @name Callbacks
22239@{ */
22240/*!
22241@brief Called when the client controlling the object changes.
22242
22243@param controlled true if a client now controls this object, false if no client controls this object.*/
22244void setControl( bool controlled );
22245/// @}
22246
22247/*!
22248@brief Toggles on the rendering of the bounding boxes for certain types of objects in scene.
22249
22250@ingroup GameBase*/
22251static bool boundingBox;
22252/*!
22253@brief Disables rendering of all instances of this type.
22254
22255
22256@ingroup UNDOCUMENTED
22257*/
22258static bool isRenderable;
22259/*!
22260@brief Disables selection of all instances of this type.
22261
22262
22263@ingroup UNDOCUMENTED
22264*/
22265static bool isSelectable;
22266
22267/*! @name Game
22268@{ */
22269/*!
22270@brief Script datablock used for game objects.
22271*/
22272GameBaseData dataBlock;
22273/// @}
22274
22275
22276/*! @name GameObject
22277@{ */
22278/// @}
22279
22280
22281/*! @name Transform
22282@{ */
22283/// @}
22284
22285
22286/*! @name Editing
22287@{ */
22288/// @}
22289
22290
22291/*! @name Mounting
22292@{ */
22293/// @}
22294
22295
22296/*! @name Ungrouped
22297@{ */
22298/// @}
22299
22300
22301/*! @name Object
22302@{ */
22303/// @}
22304
22305
22306/*! @name Editing
22307@{ */
22308/// @}
22309
22310
22311/*! @name Persistence
22312@{ */
22313/// @}
22314
22315};
22316
22317/*!
22318@ingroup gameObjects
22319*/
22320class ShapeBase : public GameBase {
22321public:
22322/*!
22323@brief Add or remove this object from the scene.
22324
22325When removed from the scene, the object will not be processed or rendered.
22326@param show False to hide the object, true to re-show it*/
22327void setHidden( bool show );
22328/*!
22329@brief Check if the object is hidden.
22330
22331@return true if the object is hidden, false if visible.
22332
22333*/
22334bool isHidden();
22335/*!
22336@brief Attach a sound to this shape and start playing it.
22337
22338@param slot Audio slot index for the sound (valid range is 0 - 3)
22339@param track SFXTrack to play
22340@return true if the sound was attached successfully, false if failed
22341
22342@see stopAudio()*/
22343bool playAudio( int slot, SFXTrack track );
22344/*!
22345@brief Stop a sound started with playAudio.
22346
22347@param slot audio slot index (started with playAudio)
22348@return true if the sound was stopped successfully, false if failed
22349
22350@see playAudio()*/
22351bool stopAudio( int slot );
22352/*!
22353@brief Start a new animation thread, or restart one that has been paused or stopped.
22354
22355@param slot thread slot to play. Valid range is 0 - 3)
22356@param name name of the animation sequence to play in this slot. If not specified, the paused or stopped thread in this slot will be resumed.
22357@return true if successful, false if failed
22358
22359@tsexample
22360%obj.playThread( 0, "ambient" );      // Play the ambient sequence in slot 0
22361%obj.setThreadTimeScale( 0, 0.5 );    // Play at half-speed
22362%obj.pauseThread( 0 );                // Pause the sequence
22363%obj.playThread( 0 );                 // Resume playback
22364%obj.playThread( 0, "spin" );         // Replace the sequence in slot 0
22365@endtsexample
22366@see pauseThread()
22367@see stopThread()
22368@see setThreadDir()
22369@see setThreadTimeScale()
22370@see destroyThread()*/
22371bool playThread( int slot, string name="" );
22372/*!
22373@brief Set the playback direction of an animation thread.
22374
22375@param slot thread slot to modify
22376@param fwd true to play the animation forwards, false to play backwards
22377@return true if successful, false if failed
22378
22379@see playThread()*/
22380bool setThreadDir( int slot, bool fwd );
22381/*!
22382@brief Set the playback time scale of an animation thread.
22383
22384@param slot thread slot to modify
22385@param scale new thread time scale (1=normal speed, 0.5=half speed etc)
22386@return true if successful, false if failed
22387
22388@see playThread*/
22389bool setThreadTimeScale( int slot, float scale );
22390/*!
22391@brief Set the position within an animation thread.
22392
22393@param slot thread slot to modify
22394@param pos position within thread
22395@return true if successful, false if failed
22396
22397@see playThread*/
22398bool setThreadPosition( int slot, float pos );
22399/*!
22400@brief Stop an animation thread.
22401
22402If restarted using playThread, the animation will start from the beginning again.
22403@param slot thread slot to stop
22404@return true if successful, false if failed
22405
22406@see playThread*/
22407bool stopThread( int slot );
22408/*!
22409@brief Destroy an animation thread, which prevents it from playing.
22410
22411@param slot thread slot to destroy
22412@return true if successful, false if failed
22413
22414@see playThread*/
22415bool destroyThread( int slot );
22416/*!
22417@brief Pause an animation thread.
22418
22419If restarted using playThread, the animation will resume from the paused position.
22420@param slot thread slot to stop
22421@return true if successful, false if failed
22422
22423@see playThread*/
22424bool pauseThread( int slot );
22425/*!
22426@brief Mount a new Image.
22427
22428@param image the Image to mount
22429@param slot Image slot to mount into (valid range is 0 - 3)
22430@param loaded initial loaded state for the Image
22431@param skinTag tagged string to reskin the mounted Image
22432@return true if successful, false if failed
22433
22434@tsexample
22435%player.mountImage( PistolImage, 1 );
22436%player.mountImage( CrossbowImage, 0, false );
22437%player.mountImage( RocketLauncherImage, 0, true, 'blue' );
22438@endtsexample
22439@see unmountImage()
22440@see getMountedImage()
22441@see getPendingImage()
22442@see isImageMounted()*/
22443bool mountImage( ShapeBaseImageData image, int slot, bool loaded=true, string skinTag="" );
22444/*!
22445@brief Unmount the mounted Image in the specified slot.
22446
22447@param slot Image slot to unmount
22448@return true if successful, false if failed
22449
22450@see mountImage()*/
22451bool unmountImage( int slot );
22452/*!
22453@brief Get the Image mounted in the specified slot.
22454
22455@param slot Image slot to query
22456@return ID of the ShapeBaseImageData datablock mounted in the slot, or 0 if no Image is mounted there.*/
22457int getMountedImage( int slot );
22458/*!
22459@brief Get the Image that will be mounted next in the specified slot.
22460
22461Calling mountImage when an Image is already mounted does one of two things: <ol><li>Mount the new Image immediately, the old Image is discarded and whatever state it was in is ignored.</li><li>If the current Image state does not allow Image changes, the new Image is marked as pending, and will not be mounted until the current state completes. eg. if the user changes weapons, you may wish to ensure that the current weapon firing state plays to completion first.</li></ol>
22462This command retrieves the ID of the pending Image (2nd case above).
22463@param slot Image slot to query
22464@return ID of the pending ShapeBaseImageData datablock, or 0 if none.*/
22465int getPendingImage( int slot );
22466/*!
22467@brief Check if the current Image state is firing.
22468
22469@param slot Image slot to query
22470@return true if the current Image state in this slot has the 'stateFire' flag set.*/
22471bool isImageFiring( int slot );
22472/*!
22473@brief Check if the given datablock is mounted to any slot on this object.
22474
22475@param image ShapeBaseImageData datablock to query
22476@return true if the Image is mounted to any slot, false otherwise.*/
22477bool isImageMounted( ShapeBaseImageData image );
22478/*!
22479@brief Get the first slot the given datablock is mounted to on this object.
22480
22481@param image ShapeBaseImageData datablock to query
22482@return index of the first slot the Image is mounted in, or -1 if the Image is not mounted in any slot on this object.*/
22483int getMountSlot( ShapeBaseImageData image );
22484/*!
22485@brief Get the skin tag ID for the Image mounted in the specified slot.
22486
22487@param slot Image slot to query
22488@return the skinTag value passed to mountImage when the image was mounted*/
22489int getImageSkinTag( int slot );
22490/*!
22491@brief Get the name of the current state of the Image in the specified slot.
22492
22493@param slot Image slot to query
22494@return name of the current Image state, or "Error" if slot is invalid*/
22495string getImageState( int slot );
22496/*!
22497@brief Check if the given state exists on the mounted Image.
22498
22499@param slot Image slot to query
22500@param state Image state to check for
22501@return true if the Image has the requested state defined.*/
22502bool hasImageState( int slot, string state );
22503/*!
22504@brief Get the trigger state of the Image mounted in the specified slot.
22505
22506@param slot Image slot to query
22507@return the Image's current trigger state*/
22508bool getImageTrigger( int slot );
22509/*!
22510@brief Set the trigger state of the Image mounted in the specified slot.
22511
22512@param slot Image slot to modify
22513@param state new trigger state for the Image
22514@return the Image's new trigger state*/
22515bool setImageTrigger( int slot, bool state );
22516/*!
22517@brief Get the generic trigger state of the Image mounted in the specified slot.
22518
22519@param slot Image slot to query
22520@param trigger Generic trigger number
22521@return the Image's current generic trigger state*/
22522bool getImageGenericTrigger( int slot, int trigger );
22523/*!
22524@brief Set the generic trigger state of the Image mounted in the specified slot.
22525
22526@param slot Image slot to modify
22527@param trigger Generic trigger number
22528@param state new generic trigger state for the Image
22529@return the Image's new generic trigger state or -1 if there was a problem.*/
22530int setImageGenericTrigger( int slot, int trigger, bool state );
22531/*!
22532@brief Get the alt trigger state of the Image mounted in the specified slot.
22533
22534@param slot Image slot to query
22535@return the Image's current alt trigger state*/
22536bool getImageAltTrigger( int slot );
22537/*!
22538@brief Set the alt trigger state of the Image mounted in the specified slot.
22539
22540@param slot Image slot to modify
22541@param state new alt trigger state for the Image
22542@return the Image's new alt trigger state*/
22543bool setImageAltTrigger( int slot, bool state );
22544/*!
22545@brief Get the ammo state of the Image mounted in the specified slot.
22546
22547@param slot Image slot to query
22548@return the Image's current ammo state*/
22549bool getImageAmmo( int slot );
22550/*!
22551@brief Set the ammo state of the Image mounted in the specified slot.
22552
22553@param slot Image slot to modify
22554@param state new ammo state for the Image
22555@return the Image's new ammo state*/
22556bool setImageAmmo( int slot, bool state );
22557/*!
22558@brief Get the loaded state of the Image mounted in the specified slot.
22559
22560@param slot Image slot to query
22561@return the Image's current loaded state*/
22562bool getImageLoaded( int slot );
22563/*!
22564@brief Set the loaded state of the Image mounted in the specified slot.
22565
22566@param slot Image slot to modify
22567@param state new loaded state for the Image
22568@return the Image's new loaded state*/
22569bool setImageLoaded( int slot, bool state );
22570/*!
22571@brief Get the target state of the Image mounted in the specified slot.
22572
22573@param slot Image slot to query
22574@return the Image's current target state*/
22575bool getImageTarget( int slot );
22576/*!
22577@brief Set the target state of the Image mounted in the specified slot.
22578
22579@param slot Image slot to modify
22580@param state new target state for the Image
22581@return the Image's new target state*/
22582bool setImageTarget( int slot, bool state );
22583/*!
22584@brief Get the script animation prefix of the Image mounted in the specified slot.
22585
22586@param slot Image slot to query
22587@return the Image's current script animation prefix*/
22588string getImageScriptAnimPrefix( int slot );
22589/*!
22590@brief Set the script animation prefix for the Image mounted in the specified slot.
22591
22592This is used to further modify the prefix used when deciding which animation sequence to play while this image is mounted.
22593@param slot Image slot to modify
22594@param prefix The prefix applied to the image*/
22595void setImageScriptAnimPrefix( int slot, string prefix );
22596/*!
22597@brief Get the muzzle vector of the Image mounted in the specified slot.
22598
22599If the Image shape contains a node called 'muzzlePoint', then the muzzle vector is the forward direction vector of that node's transform in world space. If no such node is specified, the slot's mount node is used instead.
22600
22601If the correctMuzzleVector flag (correctMuzzleVectorTP in 3rd person) is set in the Image, the muzzle vector is computed to point at whatever object is right in front of the object's 'eye' node.
22602@param slot Image slot to query
22603@return the muzzle vector, or "0 1 0" if the slot is invalid*/
22604VectorF getMuzzleVector( int slot );
22605/*!
22606@brief Get the muzzle position of the Image mounted in the specified slot.
22607
22608If the Image shape contains a node called 'muzzlePoint', then the muzzle position is the position of that node in world space. If no such node is specified, the slot's mount node is used instead.
22609@param slot Image slot to query
22610@return the muzzle position, or "0 0 0" if the slot is invalid*/
22611Point3F getMuzzlePoint( int slot );
22612/*!
22613@brief Get the world transform of the specified mount slot.
22614
22615@param slot Image slot to query
22616@return the mount transform*/
22617TransformF getSlotTransform( int slot );
22618/*!
22619@brief Get the position at which the AI should stand to repair things.
22620
22621If the shape defines a node called "AIRepairNode", this method will return the current world position of that node, otherwise "0 0 0".
22622@return the AI repair position*/
22623Point3F getAIRepairPoint();
22624/*!
22625@brief Get the object's current velocity.
22626
22627@return the current velocity*/
22628VectorF getVelocity();
22629/*!
22630@brief Set the object's velocity.
22631
22632@param vel new velocity for the object
22633@return true*/
22634bool setVelocity( Point3F vel );
22635/*!
22636@brief Apply an impulse to the object.
22637
22638@param pos world position of the impulse
22639@param vec impulse momentum (velocity * mass)
22640@return true*/
22641bool applyImpulse( Point3F pos, Point3F vec );
22642/*!
22643@brief Get the forward direction of the 'eye' for this object.
22644
22645If the object model has a node called 'eye', this method will return that node's current forward direction vector, otherwise it will return the object's current forward direction vector.
22646@return the eye vector for this object
22647@see getEyePoint
22648@see getEyeTransform*/
22649VectorF getEyeVector();
22650/*!
22651@brief Get the position of the 'eye' for this object.
22652
22653If the object model has a node called 'eye', this method will return that node's current world position, otherwise it will return the object's current world position.
22654@return the eye position for this object
22655@see getEyeVector
22656@see getEyeTransform*/
22657Point3F getEyePoint();
22658/*!
22659@brief Get the 'eye' transform for this object.
22660
22661If the object model has a node called 'eye', this method will return that node's current transform, otherwise it will return the object's current transform.
22662@return the eye transform for this object
22663@see getEyeVector
22664@see getEyePoint*/
22665TransformF getEyeTransform();
22666/*!
22667@brief Get the world position this object is looking at.
22668
22669Casts a ray from the eye and returns information about what the ray hits.
22670@param distance maximum distance of the raycast
22671@param typeMask typeMask of objects to include for raycast collision testing
22672@return look-at information as "Object HitX HitY HitZ [Material]" or empty string for no hit
22673
22674@tsexample
22675%lookat = %obj.getLookAtPoint();
22676echo( "Looking at: " @ getWords( %lookat, 1, 3 ) );
22677@endtsexample*/
22678string getLookAtPoint( float distance=2000, uint typeMask=0xFFFFFFFF );
22679/*!
22680@brief Set this object's current energy level.
22681
22682@param level new energy level
22683@see getEnergyLevel()
22684@see getEnergyPercent()*/
22685void setEnergyLevel( float level );
22686/*!
22687@brief Get the object's current energy level.
22688
22689@return energy level
22690@see setEnergyLevel()*/
22691float getEnergyLevel();
22692/*!
22693@brief Get the object's current energy level as a percentage of maxEnergy.
22694
22695@return energyLevel / datablock.maxEnergy
22696@see setEnergyLevel()*/
22697float getEnergyPercent();
22698/*!
22699@brief Set the object's current damage level.
22700
22701@param level new damage level
22702@see getDamageLevel()
22703@see getDamagePercent()*/
22704void setDamageLevel( float level );
22705/*!
22706@brief Get the object's current damage level.
22707
22708@return damage level
22709@see setDamageLevel()*/
22710float getDamageLevel();
22711/*!
22712@brief Get the object's current damage level as a percentage of maxDamage.
22713
22714@return damageLevel / datablock.maxDamage
22715@see setDamageLevel()*/
22716float getDamagePercent();
22717/*!
22718@brief Get the object's maxDamage level.
22719
22720@return datablock.maxDamage
22721*/
22722float getMaxDamage();
22723/*!
22724@brief Set the object's damage state.
22725
22726@param state should be one of "Enabled", "Disabled", "Destroyed"
22727@return true if successful, false if failed
22728@see getDamageState()*/
22729bool setDamageState( string state );
22730/*!
22731@brief Get the object's damage state.
22732
22733@return the damage state; one of "Enabled", "Disabled", "Destroyed"
22734@see setDamageState()*/
22735string getDamageState();
22736/*!
22737@brief Check if the object is in the Destroyed damage state.
22738
22739@return true if damage state is "Destroyed", false if not
22740@see isDisabled()
22741@see isEnabled()*/
22742bool isDestroyed();
22743/*!
22744@brief Check if the object is in the Disabled or Destroyed damage state.
22745
22746@return true if damage state is not "Enabled", false if it is
22747@see isDestroyed()
22748@see isEnabled()*/
22749bool isDisabled();
22750/*!
22751@brief Check if the object is in the Enabled damage state.
22752
22753@return true if damage state is "Enabled", false if not
22754@see isDestroyed()
22755@see isDisabled()*/
22756bool isEnabled();
22757/*!
22758@brief Explodes an object into pieces.*/
22759void blowUp();
22760/*!
22761@brief Increment the current damage level by the specified amount.
22762
22763@param amount value to add to current damage level*/
22764void applyDamage( float amount );
22765/*!
22766@brief Repair damage by the specified amount.
22767
22768Note that the damage level is only reduced by repairRate per tick, so it may take several ticks for the total repair to complete.
22769@param amount total repair value (subtracted from damage level over time)*/
22770void applyRepair( float amount );
22771/*!
22772@brief Set amount to repair damage by each tick.
22773
22774Note that this value is separate to the repairRate field in ShapeBaseData. This value will be subtracted from the damage level each tick, whereas the ShapeBaseData field limits how much of the applyRepair value is subtracted each tick. Both repair types can be active at the same time.
22775@param rate value to subtract from damage level each tick (must be > 0)
22776@see getRepairRate()*/
22777void setRepairRate( float rate );
22778/*!
22779@brief Get the per-tick repair amount.
22780
22781@return the current value to be subtracted from damage level each tick
22782@see setRepairRate*/
22783float getRepairRate();
22784/*!
22785@brief Set the recharge rate.
22786
22787The recharge rate is added to the object's current energy level each tick, up to the maxEnergy level set in the ShapeBaseData datablock.
22788@param rate the recharge rate (per tick)
22789@see getRechargeRate()*/
22790void setRechargeRate( float rate );
22791/*!
22792@brief Get the current recharge rate.
22793
22794@return the recharge rate (per tick)
22795@see setRechargeRate()*/
22796float getRechargeRate();
22797/*!
22798@brief Get the client (if any) that controls this object.
22799
22800The controlling client is the one that will send moves to us to act on.
22801@return the ID of the controlling GameConnection, or 0 if this object is not controlled by any client.
22802@see GameConnection*/
22803int getControllingClient();
22804/*!
22805@brief Get the object (if any) that controls this object.
22806
22807@return the ID of the controlling ShapeBase object, or 0 if this object is not controlled by another object.*/
22808int getControllingObject();
22809/*!
22810@brief Check if this object can cloak.
22811
22812@return true
22813@note Not implemented as it always returns true.*/
22814bool canCloak();
22815/*!
22816@brief Set the cloaked state of this object.
22817
22818When an object is cloaked it is not rendered.
22819@param cloak true to cloak the object, false to uncloak
22820@see isCloaked()*/
22821void setCloaked( bool cloak );
22822/*!
22823@brief Check if this object is cloaked.
22824
22825@return true if cloaked, false if not
22826@see setCloaked()*/
22827bool isCloaked();
22828/*!
22829@brief Set the damage flash level.
22830
22831Damage flash may be used as a postfx effect to flash the screen when the client is damaged.
22832@note Relies on the flash postFx.
22833@param level flash level (0-1)
22834@see getDamageFlash()*/
22835void setDamageFlash( float level );
22836/*!
22837@brief Get the damage flash level.
22838
22839@return flash level
22840@see setDamageFlash*/
22841float getDamageFlash();
22842/*!
22843@brief Set the white-out level.
22844
22845White-out may be used as a postfx effect to brighten the screen in response to a game event.
22846@note Relies on the flash postFx.
22847@param level flash level (0-1)
22848@see getWhiteOut()*/
22849void setWhiteOut( float level );
22850/*!
22851@brief Get the white-out level.
22852
22853@return white-out level
22854@see setWhiteOut*/
22855float getWhiteOut();
22856/*!
22857@brief Returns the default vertical field of view in degrees for this object if used as a camera.
22858
22859@return Default FOV*/
22860float getDefaultCameraFov();
22861/*!
22862@brief Returns the vertical field of view in degrees for this object if used as a camera.
22863
22864@return current FOV as defined in ShapeBaseData::cameraDefaultFov*/
22865float getCameraFov();
22866/*!
22867@brief Set the vertical field of view in degrees for this object if used as a camera.
22868
22869@param fov new FOV value*/
22870void setCameraFov( float fov );
22871/*!
22872@brief Fade the object in or out without removing it from the scene.
22873
22874A faded out object is still in the scene and can still be collided with, so if you want to disable collisions for this shape after it fades out use setHidden to temporarily remove this shape from the scene.
22875@note Items have the ability to light their surroundings. When an Item with an active light is fading out, the light it emits is correspondingly reduced until it goes out. Likewise, when the item fades in, the light is turned-up till it reaches it's normal brightntess.
22876@param time duration of the fade effect in ms
22877@param delay delay in ms before the fade effect begins
22878@param fadeOut true to fade-out to invisible, false to fade-in to full visibility*/
22879void startFade( int time, int delay, bool fadeOut );
22880/*!
22881@brief Set the damage direction vector.
22882
22883Currently this is only used to initialise the explosion if this object is blown up.
22884@param vec damage direction vector
22885
22886@tsexample
22887%obj.setDamageVector( "0 0 1" );
22888@endtsexample*/
22889void setDamageVector( Point3F vec );
22890/*!
22891@brief Set the name of this shape.
22892
22893@note This is the name of the shape object that is sent to the client, not the DTS or DAE model filename.
22894@param name new name for the shape
22895
22896@see getShapeName()*/
22897void setShapeName( string name );
22898/*!
22899@brief Get the name of the shape.
22900
22901@note This is the name of the shape object that is sent to the client, not the DTS or DAE model filename.
22902@return the name of the shape
22903
22904@see setShapeName()*/
22905string getShapeName();
22906/*!
22907@brief Apply a new skin to this shape.
22908
22909'Skinning' the shape effectively renames the material targets, allowing different materials to be used on different instances of the same model.
22910
22911@param name name of the skin to apply
22912
22913@see skin
22914@see getSkinName()*/
22915void setSkinName( string name );
22916/*!
22917@brief Get the name of the skin applied to this shape.
22918
22919@return the name of the skin
22920
22921@see skin
22922@see setSkinName()*/
22923string getSkinName();
22924/*!
22925@brief Set the hidden state on all the shape meshes.
22926
22927This allows you to hide all meshes in the shape, for example, and then only enable a few.
22928@param hide new hidden state for all meshes*/
22929void setAllMeshesHidden( bool hide );
22930/*!
22931@brief Set the hidden state on the named shape mesh.
22932
22933@param name name of the mesh to hide/show
22934@param hide new hidden state for the mesh*/
22935void setMeshHidden( string name, bool hide );
22936/*!
22937@brief Print a list of visible and hidden meshes in the shape to the console for debugging purposes.
22938
22939@note Only in a SHIPPING build.*/
22940void dumpMeshVisibility();
22941/*!
22942@brief Get the name of the indexed shape material.
22943
22944@param index index of the material to get (valid range is 0 - getTargetCount()-1).
22945@return the name of the indexed material.
22946
22947@see getTargetCount()*/
22948string getTargetName( int index );
22949/*!
22950@brief Get the number of materials in the shape.
22951
22952@return the number of materials in the shape.
22953
22954@see getTargetName()*/
22955int getTargetCount();
22956/*!
22957@brief Change one of the materials on the shape.
22958
22959This method changes materials per mapTo with others. The material that is being replaced is mapped to unmapped_mat as a part of this transition.
22960@note Warning, right now this only sort of works. It doesn't do a live update like it should.
22961@param mapTo the name of the material target to remap (from getTargetName)
22962@param oldMat the old Material that was mapped 
22963@param newMat the new Material to map
22964
22965@tsexample
22966// remap the first material in the shape
22967%mapTo = %obj.getTargetName( 0 );
22968%obj.changeMaterial( %mapTo, 0, MyMaterial );
22969@endtsexample*/
22970void changeMaterial( string mapTo, Material oldMat, Material newMat );
22971/*!
22972@brief Get the model filename used by this shape.
22973
22974@return the shape filename*/
22975string getModelFile();
22976
22977/*! @name Callbacks
22978@{ */
22979/*!
22980@brief Called on the server when the client has requested a FOV change.
22981
22982When the client requests that its field of view should be changed (because they want to use a sniper scope, for example) this new FOV needs to be validated by the server.  This method is called if it exists (it is optional) to validate the requested FOV, and modify it if necessary.  This could be as simple as checking that the FOV falls within a correct range, to making sure that the FOV matches the capabilities of the current weapon.
22983
22984Following this method, ShapeBase ensures that the given FOV still falls within the datablock's cameraMinFov and cameraMaxFov.  If that is good enough for your purposes, then you do not need to define the validateCameraFov() callback for your ShapeBase.
22985
22986@param fov The FOV that has been requested by the client.
22987@return The FOV as validated by the server.
22988
22989@see ShapeBaseData*/
22990float validateCameraFov( float fov );
22991/// @}
22992
22993/*!
22994@brief Disables rendering of all instances of this type.
22995
22996
22997@ingroup UNDOCUMENTED
22998*/
22999static bool isRenderable;
23000/*!
23001@brief Disables selection of all instances of this type.
23002
23003
23004@ingroup UNDOCUMENTED
23005*/
23006static bool isSelectable;
23007/*!
23008@brief @brief The skin applied to the shape.
23009
23010
23011'Skinning' the shape effectively renames the material targets, allowing different materials to be used on different instances of the same model. Using getSkinName() and setSkinName() is equivalent to reading and writing the skin field directly.
23012
23013Any material targets that start with the old skin name have that part of the name replaced with the new skin name. The initial old skin name is "base". For example, if a new skin of "blue" was applied to a model that had material targets <i>base_body</i> and <i>face</i>, the new targets would be <i>blue_body</i> and <i>face</i>. Note that <i>face</i> was not renamed since it did not start with the old skin name of "base".
23014
23015To support models that do not use the default "base" naming convention, you can also specify the part of the name to replace in the skin field itself. For example, if a model had a material target called <i>shapemat</i>, we could apply a new skin "shape=blue", and the material target would be renamed to <i>bluemat</i> (note "shape" has been replaced with "blue").
23016
23017Multiple skin updates can also be applied at the same time by separating them with a semicolon. For example: "base=blue;face=happy_face".
23018
23019Material targets are only renamed if an existing Material maps to that name, or if there is a diffuse texture in the model folder with the same name as the new target.
23020
23021
23022*/
23023string skin;
23024/*!
23025@brief @brief Is this object AI controlled.
23026
23027
23028If True then this object is considered AI controlled and not player controlled.
23029
23030*/
23031bool isAIControlled;
23032
23033/*! @name Game
23034@{ */
23035/// @}
23036
23037
23038/*! @name GameObject
23039@{ */
23040/// @}
23041
23042
23043/*! @name Transform
23044@{ */
23045/// @}
23046
23047
23048/*! @name Editing
23049@{ */
23050/// @}
23051
23052
23053/*! @name Mounting
23054@{ */
23055/// @}
23056
23057
23058/*! @name Ungrouped
23059@{ */
23060/// @}
23061
23062
23063/*! @name Object
23064@{ */
23065/// @}
23066
23067
23068/*! @name Editing
23069@{ */
23070/// @}
23071
23072
23073/*! @name Persistence
23074@{ */
23075/// @}
23076
23077};
23078
23079/*!
23080@brief This is a base class for all "marker" related objets. It is a 3D representation of a point in the level.
23081
23082The main use of a MissionMarker is to represent a point in 3D space with a mesh and basic ShapeBase information. If you simply need to mark a spot in your level, with no overhead from additional fields, this is a useful object.
23083
23084@tsexample
23085new MissionMarker()
23086{
23087   dataBlock = "WayPointMarker";
23088   position = "295.699 -171.817 280.124";
23089   rotation = "0 0 -1 13.8204";
23090   scale = "1 1 1";
23091   isRenderEnabled = "true";
23092   canSaveDynamicFields = "1";
23093   enabled = "1";
23094};
23095@endtsexample
23096
23097@note MissionMarkers will not add themselves to the scene except when in the editor.
23098
23099@see MissionMarkerData
23100
23101@see SpawnSphere
23102
23103@see WayPoint
23104
23105@ingroup enviroMisc
23106
23107*/
23108class MissionMarker : public ShapeBase {
23109public:
23110
23111/*! @name Callbacks
23112@{ */
23113/// @}
23114
23115/*!
23116@brief Disables rendering of all instances of this type.
23117
23118
23119@ingroup UNDOCUMENTED
23120*/
23121static bool isRenderable;
23122/*!
23123@brief Disables selection of all instances of this type.
23124
23125
23126@ingroup UNDOCUMENTED
23127*/
23128static bool isSelectable;
23129
23130/*! @name Game
23131@{ */
23132/// @}
23133
23134
23135/*! @name GameObject
23136@{ */
23137/// @}
23138
23139
23140/*! @name Transform
23141@{ */
23142/// @}
23143
23144
23145/*! @name Editing
23146@{ */
23147/// @}
23148
23149
23150/*! @name Mounting
23151@{ */
23152/// @}
23153
23154
23155/*! @name Ungrouped
23156@{ */
23157/// @}
23158
23159
23160/*! @name Object
23161@{ */
23162/// @}
23163
23164
23165/*! @name Editing
23166@{ */
23167/// @}
23168
23169
23170/*! @name Persistence
23171@{ */
23172/// @}
23173
23174};
23175
23176/*!
23177@brief Special type of marker, distinguished by a name and team ID number
23178
23179The original Torque engines were built from a multi-player game called Tribes. The Tribes series featured various team based game modes, such as capture the flag. The WayPoint class survived the conversion from game (Tribes) to game engine (Torque).
23180
23181Essentially, this is a MissionMarker with the addition of two variables: markerName and team. Whenever a WayPoint is created, it is added to a unique global list called WayPointSet. You can iterate through this set, seeking out specific markers determined by their markerName and team ID. This avoids the overhead of constantly calling commandToClient and commandToServer to determine a WayPoint object's name, unique ID, etc.
23182
23183@note The <i>markerName<i> field was previously called <i>name</i>, but was changed because this conflicted with the SimObject name field. Existing scripts that relied on the WayPoint <i>name</i> field will need to be updated.
23184
23185@tsexample
23186new WayPoint()
23187{
23188   team = "1";
23189   dataBlock = "WayPointMarker";
23190   position = "-0.0224786 1.53471 2.93219";
23191   rotation = "1 0 0 0";
23192   scale = "1 1 1";
23193   canSave = "1";
23194   canSaveDynamicFields = "1";
23195};
23196@endtsexample
23197
23198@see MissionMarker
23199
23200@see MissionMarkerData
23201
23202@ingroup enviroMisc
23203
23204*/
23205class WayPoint : public MissionMarker {
23206public:
23207
23208/*! @name Callbacks
23209@{ */
23210/// @}
23211
23212/*!
23213@brief Disables rendering of all instances of this type.
23214
23215
23216@ingroup UNDOCUMENTED
23217*/
23218static bool isRenderable;
23219/*!
23220@brief Disables selection of all instances of this type.
23221
23222
23223@ingroup UNDOCUMENTED
23224*/
23225static bool isSelectable;
23226
23227/*! @name Misc
23228@{ */
23229/*!
23230@brief Unique name representing this waypoint
23231*/
23232caseString markerName;
23233/// @}
23234
23235
23236/*! @name Game
23237@{ */
23238/// @}
23239
23240
23241/*! @name GameObject
23242@{ */
23243/// @}
23244
23245
23246/*! @name Transform
23247@{ */
23248/// @}
23249
23250
23251/*! @name Editing
23252@{ */
23253/// @}
23254
23255
23256/*! @name Mounting
23257@{ */
23258/// @}
23259
23260
23261/*! @name Ungrouped
23262@{ */
23263/// @}
23264
23265
23266/*! @name Object
23267@{ */
23268/// @}
23269
23270
23271/*! @name Editing
23272@{ */
23273/// @}
23274
23275
23276/*! @name Persistence
23277@{ */
23278/// @}
23279
23280};
23281
23282/*! UNDOCUMENTED!
23283@ingroup UNDOCUMENTED
23284 */
23285class NotesObject : public SceneObject {
23286public:
23287
23288/*! @name Callbacks
23289@{ */
23290/// @}
23291
23292/*!
23293@brief Disables rendering of all instances of this type.
23294
23295
23296@ingroup UNDOCUMENTED
23297*/
23298static bool isRenderable;
23299/*!
23300@brief Disables selection of all instances of this type.
23301
23302
23303@ingroup UNDOCUMENTED
23304*/
23305static bool isSelectable;
23306
23307/*! @name GameObject
23308@{ */
23309/// @}
23310
23311
23312/*! @name Transform
23313@{ */
23314/// @}
23315
23316
23317/*! @name Editing
23318@{ */
23319/// @}
23320
23321
23322/*! @name Mounting
23323@{ */
23324/// @}
23325
23326
23327/*! @name Ungrouped
23328@{ */
23329/// @}
23330
23331
23332/*! @name Object
23333@{ */
23334/// @}
23335
23336
23337/*! @name Editing
23338@{ */
23339/// @}
23340
23341
23342/*! @name Persistence
23343@{ */
23344/// @}
23345
23346/*!
23347*/
23348string Note;
23349/*!
23350*/
23351bool showArrow;
23352/*!
23353*/
23354LinearColorF arrowColor;
23355};
23356
23357/*!
23358@brief An invisible shape that causes objects hidden from view behind it to not be rendered.
23359
23360OcclusionVolume is a class for scene optimization.  It's main use is for outdoor spaces where zones and portals do not help in optimizing scene culling as they almost only make sense for modeling visibility in indoor scenarios (and for connecting indoor spaces to outdoor spaces).
23361
23362During rendering, every object that is fully behind an occluder 
23363
23364Be aware that occluders add overhead to scene culling.  Only if this overhead is outweighed by the time saved by not rendering hidden objects, is the occluder actually effective.  Because of this, chose only those spots for placing occluders where a significant number of objects will be culled from points that the player will actually be at during the game.
23365
23366Like zones and portals, OcclusionVolumes may have a default box shape or a more complex 
23367
23368@see Scene::maxOccludersPerZone
23369@see Scene::occluderMinWidthPercentage
23370@see Scene::occluderMinHeightPercentage
23371@ingroup enviroMisc
23372*/
23373class OcclusionVolume : public SceneObject {
23374public:
23375
23376/*! @name Callbacks
23377@{ */
23378/// @}
23379
23380/*!
23381@brief Disables rendering of all instances of this type.
23382
23383
23384@ingroup UNDOCUMENTED
23385*/
23386static bool isRenderable;
23387/*!
23388@brief Disables selection of all instances of this type.
23389
23390
23391@ingroup UNDOCUMENTED
23392*/
23393static bool isSelectable;
23394
23395/*! @name Internal
23396@{ */
23397/*!
23398@brief For internal use only.
23399*/
23400string plane;
23401/*!
23402@brief For internal use only.
23403*/
23404string point;
23405/*!
23406@brief For internal use only.
23407*/
23408string edge;
23409/// @}
23410
23411
23412/*! @name GameObject
23413@{ */
23414/// @}
23415
23416
23417/*! @name Transform
23418@{ */
23419/// @}
23420
23421
23422/*! @name Editing
23423@{ */
23424/// @}
23425
23426
23427/*! @name Mounting
23428@{ */
23429/// @}
23430
23431
23432/*! @name Ungrouped
23433@{ */
23434/// @}
23435
23436
23437/*! @name Object
23438@{ */
23439/// @}
23440
23441
23442/*! @name Editing
23443@{ */
23444/// @}
23445
23446
23447/*! @name Persistence
23448@{ */
23449/// @}
23450
23451};
23452
23453/*!
23454@brief General interface to control a PathCamera object from the script level.
23455@see PathCamera
23456@tsexample
23457datablock PathCameraData(LoopingCam)
23458   {
23459      mode = "";
23460   };
23461@endtsexample
23462@ingroup PathCameras
23463@ingroup Datablocks
23464
23465*/
23466class PathCameraData : public ShapeBaseData {
23467public:
23468
23469/*! @name Callbacks
23470@{ */
23471/// @}
23472
23473
23474/*! @name Shadows
23475@{ */
23476/// @}
23477
23478
23479/*! @name Render
23480@{ */
23481/// @}
23482
23483
23484/*! @name Destruction
23485Parameters related to the destruction effects of this object.
23486@{ */
23487/// @}
23488
23489
23490/*! @name Physics
23491@{ */
23492/// @}
23493
23494
23495/*! @name Damage/Energy
23496@{ */
23497/// @}
23498
23499
23500/*! @name Camera
23501The settings used by the shape when it is the camera.
23502@{ */
23503/// @}
23504
23505
23506/*! @name Misc
23507@{ */
23508/// @}
23509
23510
23511/*! @name Reflection
23512@{ */
23513/// @}
23514
23515
23516/*! @name Scripting
23517@{ */
23518/// @}
23519
23520
23521/*! @name Ungrouped
23522@{ */
23523/// @}
23524
23525
23526/*! @name Object
23527@{ */
23528/// @}
23529
23530
23531/*! @name Editing
23532@{ */
23533/// @}
23534
23535
23536/*! @name Persistence
23537@{ */
23538/// @}
23539
23540};
23541
23542/*!
23543@brief The most basic ShapeBaseData derrived shape datablock available in Torque 3D.
23544
23545When it comes to placing 3D objects in the scene, you effectively have two options:
23546
235471. TSStatic objects
23548
235492. ShapeBase derived objects
23550
23551Since ShapeBase and ShapeBaseData are not meant to be instantiated in script, you will use one of its child classes instead. Several game related objects are derived from ShapeBase: Player, Vehicle, Item, and so on.
23552
23553When you need a 3D object with datablock capabilities, you will use an object derived from ShapeBase. When you need an object with extremely low overhead, and with no other purpose than to be a 3D object in the scene, you will use TSStatic.
23554
23555The most basic child of ShapeBase is StaticShape. It does not introduce any of the additional functionality you see in Player, Item, Vehicle or the other game play heavy classes. At its core, it is comparable to a TSStatic, but with a datbalock.  Having a datablock provides a location for common variables as well as having access to various ShapeBaseData, GameBaseData and SimDataBlock callbacks.
23556
23557@tsexample
23558// Create a StaticShape using a datablock
23559datablock StaticShapeData(BasicShapeData)
23560{
23561  shapeFile = "art/shapes/items/kit/healthkit.dts";
23562  testVar = "Simple string, not a stock variable";
23563};
23564
23565new StaticShape()
23566{
23567  dataBlock = "BasicShapeData";
23568  position = "0.0 0.0 0.0";
23569  rotation = "1 0 0 0";
23570  scale = "1 1 1";
23571};
23572@endtsexample
23573
23574@see StaticShape
23575@see ShapeBaseData
23576@see TSStatic
23577
23578@ingroup gameObjects
23579@ingroup Datablocks
23580*/
23581class StaticShapeData : public ShapeBaseData {
23582public:
23583
23584/*! @name Callbacks
23585@{ */
23586/// @}
23587
23588/*!
23589@brief Deprecated
23590
23591
23592 @internal
23593*/
23594bool noIndividualDamage;
23595/*!
23596@brief @brief An integer value which, if speficied, is added to the value retured by getType().
23597
23598
23599This allows you to extend the type mask for a StaticShape that uses this datablock.  Type masks are used for container queries, etc.
23600*/
23601int dynamicType;
23602
23603/*! @name Shadows
23604@{ */
23605/// @}
23606
23607
23608/*! @name Render
23609@{ */
23610/// @}
23611
23612
23613/*! @name Destruction
23614Parameters related to the destruction effects of this object.
23615@{ */
23616/// @}
23617
23618
23619/*! @name Physics
23620@{ */
23621/// @}
23622
23623
23624/*! @name Damage/Energy
23625@{ */
23626/// @}
23627
23628
23629/*! @name Camera
23630The settings used by the shape when it is the camera.
23631@{ */
23632/// @}
23633
23634
23635/*! @name Misc
23636@{ */
23637/// @}
23638
23639
23640/*! @name Reflection
23641@{ */
23642/// @}
23643
23644
23645/*! @name Scripting
23646@{ */
23647/// @}
23648
23649
23650/*! @name Ungrouped
23651@{ */
23652/// @}
23653
23654
23655/*! @name Object
23656@{ */
23657/// @}
23658
23659
23660/*! @name Editing
23661@{ */
23662/// @}
23663
23664
23665/*! @name Persistence
23666@{ */
23667/// @}
23668
23669};
23670
23671/*! UNDOCUMENTED!
23672@ingroup UNDOCUMENTED
23673 */
23674class PathShapeData : public StaticShapeData {
23675public:
23676
23677/*! @name Callbacks
23678@{ */
23679/// @}
23680
23681
23682/*! @name Shadows
23683@{ */
23684/// @}
23685
23686
23687/*! @name Render
23688@{ */
23689/// @}
23690
23691
23692/*! @name Destruction
23693Parameters related to the destruction effects of this object.
23694@{ */
23695/// @}
23696
23697
23698/*! @name Physics
23699@{ */
23700/// @}
23701
23702
23703/*! @name Damage/Energy
23704@{ */
23705/// @}
23706
23707
23708/*! @name Camera
23709The settings used by the shape when it is the camera.
23710@{ */
23711/// @}
23712
23713
23714/*! @name Misc
23715@{ */
23716/// @}
23717
23718
23719/*! @name Reflection
23720@{ */
23721/// @}
23722
23723
23724/*! @name Scripting
23725@{ */
23726/// @}
23727
23728
23729/*! @name Ungrouped
23730@{ */
23731/// @}
23732
23733
23734/*! @name Object
23735@{ */
23736/// @}
23737
23738
23739/*! @name Editing
23740@{ */
23741/// @}
23742
23743
23744/*! @name Persistence
23745@{ */
23746/// @}
23747
23748};
23749
23750/*!
23751@brief This is the base class for light objects.
23752
23753It is *NOT* intended to be used directly in script, but exists to provide the base member variables and generic functionality. You should be using the derived classes PointLight and SpotLight, which can be declared in TorqueScript or added from the World Editor.
23754
23755For this class, we only add basic lighting options that all lighting systems would use. The specific lighting system options are injected at runtime by the lighting system itself.
23756
23757@see PointLight
23758
23759@see SpotLight
23760
23761@ingroup Lighting
23762
23763*/
23764class LightBase : public SceneObject {
23765public:
23766/*!
23767@brief Plays the light animation on this light using a new LightAnimData. If no LightAnimData is passed the existing one is played.
23768
23769@param anim Name of the LightAnimData datablock to be played
23770
23771@tsexample
23772// Play the animation using a new LightAnimData datablock
23773CrystalLight.playAnimation(SubtlePulseLightAnim);
23774@endtsexample
23775
23776*/
23777
23778void playAnimation(LightAnimData anim);
23779/*!
23780@brief Plays the light animation assigned to this light with the existing LightAnimData datablock.
23781
23782@tsexample
23783// Play the animation assigned to this light
23784CrystalLight.playAnimation();
23785@endtsexample
23786
23787*/
23788
23789void playAnimation();
23790/*!
23791@brief Toggles the light on and off
23792
23793@param state Turns the light on (true) or off (false)
23794@tsexample
23795// Disable the light
23796CrystalLight.setLightEnabled(false);
23797
23798// Renable the light
23799CrystalLight.setLightEnabled(true);
23800@endtsexample*/
23801void setLightEnabled( bool state );
23802/*!
23803@brief Stops the light animation.
23804
23805*/
23806void pauseAnimation();
23807
23808/*! @name Callbacks
23809@{ */
23810/// @}
23811
23812/*!
23813@brief Disables rendering of all instances of this type.
23814
23815
23816@ingroup UNDOCUMENTED
23817*/
23818static bool isRenderable;
23819/*!
23820@brief Disables selection of all instances of this type.
23821
23822
23823@ingroup UNDOCUMENTED
23824*/
23825static bool isSelectable;
23826
23827/*! @name Light
23828@{ */
23829/*!
23830@brief Enables/Disables the object rendering and functionality in the scene.
23831*/
23832bool isEnabled;
23833/*!
23834@brief Changes the base color hue of the light.
23835*/
23836LinearColorF color;
23837/*!
23838@brief Adjusts the lights power, 0 being off completely.
23839*/
23840float brightness;
23841/*!
23842@brief Enables/disabled shadow casts by this light.
23843*/
23844bool castShadows;
23845/*!
23846@brief Used for sorting of lights by the light manager. Priority determines if a light has a stronger effect than, those with a lower value
23847*/
23848float priority;
23849/// @}
23850
23851
23852/*! @name Light Animation
23853@{ */
23854/*!
23855@brief Toggles animation for the light on and off
23856*/
23857bool animate;
23858/*!
23859@brief Datablock containing light animation information (LightAnimData)
23860*/
23861LightAnimData animationType;
23862/*!
23863@brief The length of time in seconds for a single playback of the light animation (must be > 0)
23864*/
23865float animationPeriod;
23866/*!
23867@brief The phase used to offset the animation start time to vary the animation of nearby lights.
23868*/
23869float animationPhase;
23870/// @}
23871
23872
23873/*! @name Misc
23874@{ */
23875/*!
23876@brief Datablock containing light flare information (LightFlareData)
23877*/
23878LightFlareData flareType;
23879/*!
23880@brief Globally scales all features of the light flare
23881*/
23882float flareScale;
23883/// @}
23884
23885
23886/*! @name Advanced Lighting
23887@{ */
23888/*!
23889@brief The proportions of constant, linear, and quadratic attenuation to use for the falloff for point and spot lights.
23890*/
23891Point3F attenuationRatio;
23892/*!
23893@brief The type of shadow to use on this light.
23894*/
23895ShadowType shadowType;
23896/*!
23897@brief A custom pattern texture which is projected from the light.
23898*/
23899filename cookie;
23900/*!
23901@brief The texture size of the shadow map.
23902*/
23903int texSize;
23904/*!
23905@brief The ESM shadow darkening factor
23906*/
23907Point4F overDarkFactor;
23908/*!
23909@brief The distance from the camera to extend the PSSM shadow.
23910*/
23911float shadowDistance;
23912/*!
23913*/
23914float shadowSoftness;
23915/*!
23916@brief The logrithmic PSSM split distance factor.
23917*/
23918int numSplits;
23919/*!
23920@brief The logrithmic PSSM split distance factor.
23921*/
23922float logWeight;
23923/*!
23924@brief Start fading shadows out at this distance.  0 = auto calculate this distance.
23925*/
23926float fadeStartDistance;
23927/*!
23928@brief This toggles only terrain being rendered to the last split of a PSSM shadow map.
23929*/
23930bool lastSplitTerrainOnly;
23931/// @}
23932
23933
23934/*! @name Advanced Lighting Lightmap
23935@{ */
23936/*!
23937@brief This light is represented in lightmaps (static light, default: false)
23938*/
23939bool representedInLightmap;
23940/*!
23941@brief The color that should be used to multiply-blend dynamic shadows onto lightmapped geometry (ignored if 'representedInLightmap' is false)
23942*/
23943LinearColorF shadowDarkenColor;
23944/*!
23945@brief This light should render lightmapped geometry during its shadow-map update (ignored if 'representedInLightmap' is false)
23946*/
23947bool includeLightmappedGeometryInShadow;
23948/// @}
23949
23950
23951/*! @name GameObject
23952@{ */
23953/// @}
23954
23955
23956/*! @name Transform
23957@{ */
23958/// @}
23959
23960
23961/*! @name Editing
23962@{ */
23963/// @}
23964
23965
23966/*! @name Mounting
23967@{ */
23968/// @}
23969
23970
23971/*! @name Ungrouped
23972@{ */
23973/// @}
23974
23975
23976/*! @name Object
23977@{ */
23978/// @}
23979
23980
23981/*! @name Editing
23982@{ */
23983/// @}
23984
23985
23986/*! @name Persistence
23987@{ */
23988/// @}
23989
23990};
23991
23992/*!
23993@brief Lighting object that radiates light in all directions.
23994
23995PointLight is one of the two types of lighting objects that can be added to a Torque 3D level, the other being SpotLight. Unlike directional or conical light, the PointLight emits lighting in all directions. The attenuation is controlled by a single variable: LightObject::radius.
23996
23997@tsexample
23998// Declaration of a point light in script, or created by World Editor
23999new PointLight(CrystalLight)
24000{
24001   radius = "10";
24002   isEnabled = "1";
24003   color = "1 0.905882 0 1";
24004   brightness = "0.5";
24005   castShadows = "1";
24006   priority = "1";
24007   animate = "1";
24008   animationType = "SubtlePulseLightAnim";
24009   animationPeriod = "3";
24010   animationPhase = "3";
24011   flareScale = "1";
24012   attenuationRatio = "0 1 1";
24013   shadowType = "DualParaboloidSinglePass";
24014   texSize = "512";
24015   overDarkFactor = "2000 1000 500 100";
24016   shadowDistance = "400";
24017   shadowSoftness = "0.15";
24018   numSplits = "1";
24019   logWeight = "0.91";
24020   fadeStartDistance = "0";
24021   lastSplitTerrainOnly = "0";
24022   splitFadeDistances = "10 20 30 40";
24023   representedInLightmap = "0";
24024   shadowDarkenColor = "0 0 0 -1";
24025   includeLightmappedGeometryInShadow = "1";
24026   position = "-61.3866 1.69186 5.1464";
24027   rotation = "1 0 0 0";
24028};
24029@endtsexample
24030
24031@see LightBase
24032
24033@see SpotLight
24034
24035@ingroup Lighting
24036
24037*/
24038class PointLight : public LightBase {
24039public:
24040
24041/*! @name Callbacks
24042@{ */
24043/// @}
24044
24045/*!
24046@brief Disables rendering of all instances of this type.
24047
24048
24049@ingroup UNDOCUMENTED
24050*/
24051static bool isRenderable;
24052/*!
24053@brief Disables selection of all instances of this type.
24054
24055
24056@ingroup UNDOCUMENTED
24057*/
24058static bool isSelectable;
24059
24060/*! @name Light
24061@{ */
24062/*!
24063@brief Controls the falloff of the light emission
24064*/
24065float radius;
24066/// @}
24067
24068
24069/*! @name Light
24070@{ */
24071/// @}
24072
24073
24074/*! @name Light Animation
24075@{ */
24076/// @}
24077
24078
24079/*! @name Misc
24080@{ */
24081/// @}
24082
24083
24084/*! @name Advanced Lighting
24085@{ */
24086/// @}
24087
24088
24089/*! @name Advanced Lighting Lightmap
24090@{ */
24091/// @}
24092
24093
24094/*! @name GameObject
24095@{ */
24096/// @}
24097
24098
24099/*! @name Transform
24100@{ */
24101/// @}
24102
24103
24104/*! @name Editing
24105@{ */
24106/// @}
24107
24108
24109/*! @name Mounting
24110@{ */
24111/// @}
24112
24113
24114/*! @name Ungrouped
24115@{ */
24116/// @}
24117
24118
24119/*! @name Object
24120@{ */
24121/// @}
24122
24123
24124/*! @name Editing
24125@{ */
24126/// @}
24127
24128
24129/*! @name Persistence
24130@{ */
24131/// @}
24132
24133};
24134
24135/*!
24136@brief The most basic 3D shape with a datablock available in Torque 3D.
24137
24138When it comes to placing 3D objects in the scene, you technically have two options:
24139
241401. TSStatic objects
24141
241422. ShapeBase derived objects
24143
24144Since ShapeBase and ShapeBaseData are not meant to be instantiated in script, you will use one of its child classes instead. Several game related objects are derived from ShapeBase: Player, Vehicle, Item, and so on.
24145
24146When you need a 3D object with datablock capabilities, you will use an object derived from ShapeBase. When you need an object with extremely low overhead, and with no other purpose than to be a 3D object in the scene, you will use TSStatic.
24147
24148The most basic child of ShapeBase is StaticShape. It does not introduce any of the additional functionality you see in Player, Item, Vehicle or the other game play heavy classes. At its core, it is comparable to a TSStatic, but with a datbalock.  Having a datablock provides a location for common variables as well as having access to various ShapeBaseData, GameBaseData and SimDataBlock callbacks.
24149
24150@tsexample
24151// Create a StaticShape using a datablock
24152datablock StaticShapeData(BasicShapeData)
24153{
24154  shapeFile = "art/shapes/items/kit/healthkit.dts";
24155  testVar = "Simple string, not a stock variable";
24156};
24157
24158new StaticShape()
24159{
24160  dataBlock = "BasicShapeData";
24161  position = "0.0 0.0 0.0";
24162  rotation = "1 0 0 0";
24163  scale = "1 1 1";
24164};
24165@endtsexample
24166
24167@see StaticShapeData
24168@see ShapeBase
24169@see TSStatic
24170
24171@ingroup gameObjects
24172
24173*/
24174class StaticShape : public ShapeBase {
24175public:
24176
24177/*! @name Callbacks
24178@{ */
24179/// @}
24180
24181/*!
24182@brief Disables rendering of all instances of this type.
24183
24184
24185@ingroup UNDOCUMENTED
24186*/
24187static bool isRenderable;
24188/*!
24189@brief Disables selection of all instances of this type.
24190
24191
24192@ingroup UNDOCUMENTED
24193*/
24194static bool isSelectable;
24195
24196/*! @name Game
24197@{ */
24198/// @}
24199
24200
24201/*! @name GameObject
24202@{ */
24203/// @}
24204
24205
24206/*! @name Transform
24207@{ */
24208/// @}
24209
24210
24211/*! @name Editing
24212@{ */
24213/// @}
24214
24215
24216/*! @name Mounting
24217@{ */
24218/// @}
24219
24220
24221/*! @name Ungrouped
24222@{ */
24223/// @}
24224
24225
24226/*! @name Object
24227@{ */
24228/// @}
24229
24230
24231/*! @name Editing
24232@{ */
24233/// @}
24234
24235
24236/*! @name Persistence
24237@{ */
24238/// @}
24239
24240};
24241
24242/*!
24243@brief Lighting object which emits conical light in a direction.
24244
24245SpotLight is one of the two types of lighting objects that can be added to a Torque 3D level, the other being PointLight. Unlike directional or point lights, the SpotLights emits lighting in a specific direction within a cone. The distance of the cone is controlled by the SpotLight::range variable.
24246
24247@tsexample
24248// Declaration of a point light in script, or created by World Editor
24249new SpotLight(SampleSpotLight)
24250{
24251   range = "10";
24252   innerAngle = "40";
24253   outerAngle = "45";
24254   isEnabled = "1";
24255   color = "1 1 1 1";
24256   brightness = "1";
24257   castShadows = "0";
24258   priority = "1";
24259   animate = "1";
24260   animationPeriod = "1";
24261   animationPhase = "1";
24262   flareType = "LightFlareExample0";
24263   flareScale = "1";
24264   attenuationRatio = "0 1 1";
24265   shadowType = "Spot";
24266   texSize = "512";
24267   overDarkFactor = "2000 1000 500 100";
24268   shadowDistance = "400";
24269   shadowSoftness = "0.15";
24270   numSplits = "1";
24271   logWeight = "0.91";
24272   fadeStartDistance = "0";
24273   lastSplitTerrainOnly = "0";
24274   representedInLightmap = "0";
24275   shadowDarkenColor = "0 0 0 -1";
24276   includeLightmappedGeometryInShadow = "0";
24277   position = "-29.4362 -5.86289 5.58602";
24278   rotation = "1 0 0 0";
24279};
24280@endtsexample
24281
24282@see LightBase
24283
24284@see PointLight
24285
24286@ingroup Lighting
24287
24288*/
24289class SpotLight : public LightBase {
24290public:
24291
24292/*! @name Callbacks
24293@{ */
24294/// @}
24295
24296/*!
24297@brief Disables rendering of all instances of this type.
24298
24299
24300@ingroup UNDOCUMENTED
24301*/
24302static bool isRenderable;
24303/*!
24304@brief Disables selection of all instances of this type.
24305
24306
24307@ingroup UNDOCUMENTED
24308*/
24309static bool isSelectable;
24310
24311/*! @name Light
24312@{ */
24313/*!
24314*/
24315float range;
24316/*!
24317*/
24318float innerAngle;
24319/*!
24320*/
24321float outerAngle;
24322/// @}
24323
24324
24325/*! @name Light
24326@{ */
24327/// @}
24328
24329
24330/*! @name Light Animation
24331@{ */
24332/// @}
24333
24334
24335/*! @name Misc
24336@{ */
24337/// @}
24338
24339
24340/*! @name Advanced Lighting
24341@{ */
24342/// @}
24343
24344
24345/*! @name Advanced Lighting Lightmap
24346@{ */
24347/// @}
24348
24349
24350/*! @name GameObject
24351@{ */
24352/// @}
24353
24354
24355/*! @name Transform
24356@{ */
24357/// @}
24358
24359
24360/*! @name Editing
24361@{ */
24362/// @}
24363
24364
24365/*! @name Mounting
24366@{ */
24367/// @}
24368
24369
24370/*! @name Ungrouped
24371@{ */
24372/// @}
24373
24374
24375/*! @name Object
24376@{ */
24377/// @}
24378
24379
24380/*! @name Editing
24381@{ */
24382/// @}
24383
24384
24385/*! @name Persistence
24386@{ */
24387/// @}
24388
24389};
24390
24391/*!
24392@brief An example scene object which renders using a callback.
24393
24394This class implements a basic SceneObject that can exist in the world at a 3D position and render itself. Note that RenderObjectExample handles its own rendering by submitting itself as an ObjectRenderInst (see renderInstance
24395enderPassmanager.h) along with a delegate for its render() function. However, the preffered rendering method in the engine is to submit a MeshRenderInst along with a Material, vertex buffer, primitive buffer, and transform and allow the RenderMeshMgr handle the actual rendering. You can see this implemented in RenderMeshExample.
24396
24397See the C++ code for implementation details.
24398
24399@ingroup Examples
24400
24401*/
24402class RenderObjectExample : public SceneObject {
24403public:
24404
24405/*! @name Callbacks
24406@{ */
24407/// @}
24408
24409/*!
24410@brief Disables rendering of all instances of this type.
24411
24412
24413@ingroup UNDOCUMENTED
24414*/
24415static bool isRenderable;
24416/*!
24417@brief Disables selection of all instances of this type.
24418
24419
24420@ingroup UNDOCUMENTED
24421*/
24422static bool isSelectable;
24423
24424/*! @name GameObject
24425@{ */
24426/// @}
24427
24428
24429/*! @name Transform
24430@{ */
24431/// @}
24432
24433
24434/*! @name Editing
24435@{ */
24436/// @}
24437
24438
24439/*! @name Mounting
24440@{ */
24441/// @}
24442
24443
24444/*! @name Ungrouped
24445@{ */
24446/// @}
24447
24448
24449/*! @name Object
24450@{ */
24451/// @}
24452
24453
24454/*! @name Editing
24455@{ */
24456/// @}
24457
24458
24459/*! @name Persistence
24460@{ */
24461/// @}
24462
24463};
24464
24465/*!
24466@brief An example scene object which renders a DTS.
24467
24468This class implements a basic SceneObject that can exist in the world at a 3D position and render itself. There are several valid ways to render an object in Torque. This class makes use of the 'TS' (three space) shape system. TS manages loading the various mesh formats supported by Torque as well was rendering those meshes (including LOD and animation...though this example doesn't include any animation over time).
24469
24470See the C++ code for implementation details.
24471
24472@ingroup Examples
24473
24474*/
24475class RenderShapeExample : public SceneObject {
24476public:
24477
24478/*! @name Callbacks
24479@{ */
24480/// @}
24481
24482/*!
24483@brief Disables rendering of all instances of this type.
24484
24485
24486@ingroup UNDOCUMENTED
24487*/
24488static bool isRenderable;
24489/*!
24490@brief Disables selection of all instances of this type.
24491
24492
24493@ingroup UNDOCUMENTED
24494*/
24495static bool isSelectable;
24496
24497/*! @name Rendering
24498@{ */
24499/*!
24500@brief The path to the DTS shape file.
24501*/
24502filename shapeFile;
24503/// @}
24504
24505
24506/*! @name GameObject
24507@{ */
24508/// @}
24509
24510
24511/*! @name Transform
24512@{ */
24513/// @}
24514
24515
24516/*! @name Editing
24517@{ */
24518/// @}
24519
24520
24521/*! @name Mounting
24522@{ */
24523/// @}
24524
24525
24526/*! @name Ungrouped
24527@{ */
24528/// @}
24529
24530
24531/*! @name Object
24532@{ */
24533/// @}
24534
24535
24536/*! @name Editing
24537@{ */
24538/// @}
24539
24540
24541/*! @name Persistence
24542@{ */
24543/// @}
24544
24545};
24546
24547/*!
24548@brief Basic cross hair hud. Reacts to state of control object. Also displays health bar for named objects under the cross hair.
24549
24550Uses the base bitmap control to render a bitmap, and decides whether to draw or not depending on the current control object and it's state. If there is ShapeBase object under the cross hair and it's named, then a small health bar is displayed.
24551
24552@tsexample
24553
24554 new GuiCrossHairHud(){
24555   damageFillColor = "1.0 0.0 0.0 1.0"; // Fills with a solid red color
24556   damageFrameColor = "1.0 1.0 1.0 1.0"; // Solid white frame color
24557   damageRect = "15 5";
24558   damageOffset = "0 -10";
24559};
24560@endtsexample
24561@ingroup GuiGame
24562
24563*/
24564class GuiCrossHairHud : public GuiBitmapCtrl {
24565public:
24566
24567/*! @name Callbacks
24568@{ */
24569/// @}
24570
24571
24572/*! @name Damage
24573@{ */
24574/*!
24575@brief As the health bar depletes, this color will represent the health loss amount.
24576*/
24577LinearColorF damageFillColor;
24578/*!
24579@brief Color for the health bar's frame.
24580*/
24581LinearColorF damageFrameColor;
24582/*!
24583@brief Size for the health bar portion of the control.
24584*/
24585Point2I damageRect;
24586/*!
24587@brief Offset for drawing the damage portion of the health control.
24588*/
24589Point2I damageOffset;
24590/// @}
24591
24592
24593/*! @name Bitmap
24594@{ */
24595/// @}
24596
24597
24598/*! @name Layout
24599@{ */
24600/// @}
24601
24602
24603/*! @name Control
24604@{ */
24605/// @}
24606
24607
24608/*! @name ToolTip
24609@{ */
24610/// @}
24611
24612
24613/*! @name Editing
24614@{ */
24615/// @}
24616
24617
24618/*! @name Localization
24619@{ */
24620/// @}
24621
24622
24623/*! @name Ungrouped
24624@{ */
24625/// @}
24626
24627
24628/*! @name Object
24629@{ */
24630/// @}
24631
24632
24633/*! @name Editing
24634@{ */
24635/// @}
24636
24637
24638/*! @name Persistence
24639@{ */
24640/// @}
24641
24642};
24643
24644/*!
24645@brief A basic health bar. Shows the damage value of the current PlayerObjectType control object.
24646
24647This gui displays the damage value of the current PlayerObjectType control object. The gui can be set to pulse if the health value drops below a set value. This control only works if a server connection exists and it's control object is a PlayerObjectType. If either of these requirements is false, the control is not rendered.
24648
24649@tsexample
24650
24651 new GuiHealthBarHud(){
24652   fillColor = "0.0 1.0 0.0 1.0"; // Fills with a solid green color
24653   frameColor = "1.0 1.0 1.0 1.0"; // Solid white frame color
24654   damageFillColor = "1.0 0.0 0.0 1.0"; // Fills with a solid red color
24655   pulseRate = "500";
24656   pulseThreshold = "0.25";
24657   showFill = "true";
24658   showFrame = "true";
24659   displayEnergy = "false";
24660};
24661@endtsexample
24662
24663@ingroup GuiGame
24664
24665*/
24666class GuiHealthBarHud : public GuiControl {
24667public:
24668
24669/*! @name Callbacks
24670@{ */
24671/// @}
24672
24673
24674/*! @name Colors
24675@{ */
24676/*!
24677@brief Standard color for the background of the control.
24678*/
24679LinearColorF fillColor;
24680/*!
24681@brief Color for the control's frame.
24682*/
24683LinearColorF frameColor;
24684/*!
24685@brief As the health bar depletes, this color will represent the health loss amount.
24686*/
24687LinearColorF damageFillColor;
24688/// @}
24689
24690
24691/*! @name Pulse
24692@{ */
24693/*!
24694@brief Speed at which the control will pulse.
24695*/
24696int pulseRate;
24697/*!
24698@brief Health level the control must be under before the control will pulse.
24699*/
24700float pulseThreshold;
24701/// @}
24702
24703
24704/*! @name Misc
24705@{ */
24706/*!
24707@brief If true, we draw the background color of the control.
24708*/
24709bool showFill;
24710/*!
24711@brief If true, we draw the frame of the control.
24712*/
24713bool showFrame;
24714/*!
24715@brief If true, display the energy value rather than the damage value.
24716*/
24717bool displayEnergy;
24718/*!
24719@brief If true, will fill bar in opposite direction.
24720*/
24721bool flip;
24722/// @}
24723
24724
24725/*! @name Layout
24726@{ */
24727/// @}
24728
24729
24730/*! @name Control
24731@{ */
24732/// @}
24733
24734
24735/*! @name ToolTip
24736@{ */
24737/// @}
24738
24739
24740/*! @name Editing
24741@{ */
24742/// @}
24743
24744
24745/*! @name Localization
24746@{ */
24747/// @}
24748
24749
24750/*! @name Ungrouped
24751@{ */
24752/// @}
24753
24754
24755/*! @name Object
24756@{ */
24757/// @}
24758
24759
24760/*! @name Editing
24761@{ */
24762/// @}
24763
24764
24765/*! @name Persistence
24766@{ */
24767/// @}
24768
24769};
24770
24771/*!
24772@brief Shows the health or energy value of the current PlayerObjectType control object.
24773
24774This gui can be configured to display either the health or energy value of the current Player Object. It can use an alternate display color if the health or drops below a set value. It can also be set to pulse if the health or energy drops below a set value. This control only works if a server connection exists and it's control object is a PlayerObjectType. If either of these requirements is false, the control is not rendered.
24775
24776@tsexample
24777
24778 new GuiHealthTextHud(){
24779   fillColor = "0.0 0.0 0.0 0.5"; // Fills with a transparent black color
24780   frameColor = "1.0 1.0 1.0 1.0"; // Solid white frame color
24781   textColor = "0.0 1.0 0.0 1.0" // Solid green text color
24782   warningColor = "1.0 0.0 0.0 1.0"; // Solid red color, used when damaged
24783   showFill = "true";
24784   showFrame = "true";
24785   showTrueValue = "false";
24786   showEnergy = "false";
24787   warnThreshold = "50";
24788   pulseThreshold = "25";
24789   pulseRate = "500";
24790   profile = "GuiBigTextProfile";
24791};
24792@endtsexample
24793
24794@ingroup GuiGame
24795
24796*/
24797class GuiHealthTextHud : public GuiControl {
24798public:
24799
24800/*! @name Callbacks
24801@{ */
24802/// @}
24803
24804
24805/*! @name Colors
24806@{ */
24807/*!
24808@brief Color for the background of the control.
24809*/
24810LinearColorF fillColor;
24811/*!
24812@brief Color for the control's frame.
24813*/
24814LinearColorF frameColor;
24815/*!
24816@brief Color for the text on this control.
24817*/
24818LinearColorF textColor;
24819/*!
24820@brief Color for the text when health is low.
24821*/
24822LinearColorF warningColor;
24823/// @}
24824
24825
24826/*! @name View
24827@{ */
24828/*!
24829@brief If true, draw the background.
24830*/
24831bool showFill;
24832/*!
24833@brief If true, draw the frame.
24834*/
24835bool showFrame;
24836/*!
24837@brief If true, we don't hardcode maxHealth to 100.
24838*/
24839bool showTrueValue;
24840/*!
24841@brief If true, display the energy value rather than the damage value.
24842*/
24843bool showEnergy;
24844/// @}
24845
24846
24847/*! @name Alert
24848@{ */
24849/*!
24850@brief The health level at which to use the warningColor.
24851*/
24852float warnThreshold;
24853/*!
24854@brief Health level at which to begin pulsing.
24855*/
24856float pulseThreshold;
24857/*!
24858@brief Speed at which the control will pulse.
24859*/
24860int pulseRate;
24861/// @}
24862
24863
24864/*! @name Layout
24865@{ */
24866/// @}
24867
24868
24869/*! @name Control
24870@{ */
24871/// @}
24872
24873
24874/*! @name ToolTip
24875@{ */
24876/// @}
24877
24878
24879/*! @name Editing
24880@{ */
24881/// @}
24882
24883
24884/*! @name Localization
24885@{ */
24886/// @}
24887
24888
24889/*! @name Ungrouped
24890@{ */
24891/// @}
24892
24893
24894/*! @name Object
24895@{ */
24896/// @}
24897
24898
24899/*! @name Editing
24900@{ */
24901/// @}
24902
24903
24904/*! @name Persistence
24905@{ */
24906/// @}
24907
24908};
24909
24910/*!
24911@brief Displays name and damage of ShapeBase objects in its bounds. Must be a child of a GuiTSCtrl and a server connection must be present.
24912
24913This control displays the name and damage value of all named ShapeBase objects on the client. The name and damage of objects within the control's display area are overlayed above the object.
24914
24915This GUI control must be a child of a TSControl, and a server connection and control object must be present. This is a stand-alone control and relies only on the standard base GuiControl.
24916
24917@tsexample
24918
24919 new GuiShapeNameHud(){
24920   fillColor = "0.0 1.0 0.0 1.0"; // Fills with a solid green color
24921   frameColor = "1.0 1.0 1.0 1.0"; // Solid white frame color
24922   textColor = "1.0 1.0 1.0 1.0"; // Solid white text Color
24923   showFill = "true";
24924   showFrame = "true";
24925   labelFillColor = "0.0 1.0 0.0 1.0"; // Fills with a solid green color
24926   labelFrameColor = "1.0 1.0 1.0 1.0"; // Solid white frame color
24927   showLabelFill = "true";
24928   showLabelFrame = "true";
24929   verticalOffset = "0.15";
24930   distanceFade = "15.0";
24931};
24932@endtsexample
24933
24934@ingroup GuiGame
24935
24936*/
24937class GuiShapeNameHud : public GuiControl {
24938public:
24939
24940/*! @name Callbacks
24941@{ */
24942/// @}
24943
24944
24945/*! @name Colors
24946@{ */
24947/*!
24948@brief Standard color for the background of the control.
24949*/
24950LinearColorF fillColor;
24951/*!
24952@brief Color for the control's frame.
24953*/
24954LinearColorF frameColor;
24955/*!
24956@brief Color for the text on this control.
24957*/
24958LinearColorF textColor;
24959/*!
24960@brief Color for the background of each shape name label.
24961*/
24962LinearColorF labelFillColor;
24963/*!
24964@brief Color for the frames around each shape name label.
24965*/
24966LinearColorF labelFrameColor;
24967/// @}
24968
24969
24970/*! @name Misc
24971@{ */
24972/*!
24973@brief If true, we draw the background color of the control.
24974*/
24975bool showFill;
24976/*!
24977@brief If true, we draw the frame of the control.
24978*/
24979bool showFrame;
24980/*!
24981@brief If true, we draw a background for each shape name label.
24982*/
24983bool showLabelFill;
24984/*!
24985@brief If true, we draw a frame around each shape name label.
24986*/
24987bool showLabelFrame;
24988/*!
24989@brief The padding (in pixels) between the label text and the frame.
24990*/
24991Point2I labelPadding;
24992/*!
24993@brief Amount to vertically offset the control in relation to the ShapeBase object in focus.
24994*/
24995float verticalOffset;
24996/*!
24997@brief Visibility distance (how far the player must be from the ShapeBase object in focus) for this control to render.
24998*/
24999float distanceFade;
25000/// @}
25001
25002
25003/*! @name Layout
25004@{ */
25005/// @}
25006
25007
25008/*! @name Control
25009@{ */
25010/// @}
25011
25012
25013/*! @name ToolTip
25014@{ */
25015/// @}
25016
25017
25018/*! @name Editing
25019@{ */
25020/// @}
25021
25022
25023/*! @name Localization
25024@{ */
25025/// @}
25026
25027
25028/*! @name Ungrouped
25029@{ */
25030/// @}
25031
25032
25033/*! @name Object
25034@{ */
25035/// @}
25036
25037
25038/*! @name Editing
25039@{ */
25040/// @}
25041
25042
25043/*! @name Persistence
25044@{ */
25045/// @}
25046
25047};
25048
25049/*!
25050@brief The emitter for an explosion effect, with properties defined by a ExplosionData object.
25051
25052@ingroup FX
25053The object will initiate the explosion effects automatically after being added to the simulation.
25054@tsexample
25055datablock ExplosionData( GrenadeSubExplosion )
25056{
25057   offset = 0.25;
25058   emitter[0] = GrenadeExpSparkEmitter;
25059
25060   lightStartRadius = 4.0;
25061   lightEndRadius = 0.0;
25062   lightStartColor = "0.9 0.7 0.7";
25063   lightEndColor = "0.9 0.7 0.7";
25064   lightStartBrightness = 2.0;
25065   lightEndBrightness = 0.0;
25066};
25067
25068datablock ExplosionData( GrenadeLauncherExplosion )
25069{
25070   soundProfile = GrenadeLauncherExplosionSound;
25071   lifeTimeMS = 400; // Quick flash, short burn, and moderate dispersal
25072
25073   // Volume particles
25074   particleEmitter = GrenadeExpFireEmitter;
25075   particleDensity = 75;
25076   particleRadius = 2.25;
25077
25078   // Point emission
25079   emitter[0] = GrenadeExpDustEmitter;
25080   emitter[1] = GrenadeExpSparksEmitter;
25081   emitter[2] = GrenadeExpSmokeEmitter;
25082
25083   // Sub explosion objects
25084   subExplosion[0] = GrenadeSubExplosion;
25085
25086   // Camera Shaking
25087   shakeCamera = true;
25088   camShakeFreq = "10.0 11.0 9.0";
25089   camShakeAmp = "15.0 15.0 15.0";
25090   camShakeDuration = 1.5;
25091   camShakeRadius = 20;
25092
25093   // Exploding debris
25094   debris = GrenadeDebris;
25095   debrisThetaMin = 10;
25096   debrisThetaMax = 60;
25097   debrisNum = 4;
25098   debrisNumVariance = 2;
25099   debrisVelocity = 25;
25100   debrisVelocityVariance = 5;
25101
25102   lightStartRadius = 4.0;
25103   lightEndRadius = 0.0;
25104   lightStartColor = "1.0 1.0 1.0";
25105   lightEndColor = "1.0 1.0 1.0";
25106   lightStartBrightness = 4.0;
25107   lightEndBrightness = 0.0;
25108   lightNormalOffset = 2.0;
25109};
25110
25111function ServerPlayExplosion(%position, %datablock)
25112{
25113   // Play the given explosion on every client.
25114   // The explosion will be transmitted as an event, not attached to any object.
25115   for(%idx = 0; %idx < ClientGroup.getCount(); %idx++)
25116   {
25117      %client = ClientGroup.getObject(%idx);
25118      commandToClient(%client, 'PlayExplosion', %position, %datablock.getId());
25119   }
25120}
25121
25122function clientCmdPlayExplosion(%position, %effectDataBlock)
25123{
25124   // Play an explosion sent by the server. Make sure this function is defined
25125   // on the client.
25126   if (isObject(%effectDataBlock))
25127   {
25128      new Explosion()
25129      {
25130         position = %position;
25131         dataBlock = %effectDataBlock;
25132      };
25133   }
25134}
25135
25136// schedule an explosion
25137schedule(1000, 0, ServerPlayExplosion, "0 0 0", GrenadeLauncherExplosion);
25138@endtsexample
25139*/
25140class Explosion : public GameBase {
25141public:
25142
25143/*! @name Callbacks
25144@{ */
25145/// @}
25146
25147/*!
25148@brief Disables rendering of all instances of this type.
25149
25150
25151@ingroup UNDOCUMENTED
25152*/
25153static bool isRenderable;
25154/*!
25155@brief Disables selection of all instances of this type.
25156
25157
25158@ingroup UNDOCUMENTED
25159*/
25160static bool isSelectable;
25161
25162/*! @name Game
25163@{ */
25164/// @}
25165
25166
25167/*! @name GameObject
25168@{ */
25169/// @}
25170
25171
25172/*! @name Transform
25173@{ */
25174/// @}
25175
25176
25177/*! @name Editing
25178@{ */
25179/// @}
25180
25181
25182/*! @name Mounting
25183@{ */
25184/// @}
25185
25186
25187/*! @name Ungrouped
25188@{ */
25189/// @}
25190
25191
25192/*! @name Object
25193@{ */
25194/// @}
25195
25196
25197/*! @name Editing
25198@{ */
25199/// @}
25200
25201
25202/*! @name Persistence
25203@{ */
25204/// @}
25205
25206/*!
25207@brief Initial starting Normal.
25208*/
25209Point3F initialNormal;
25210};
25211
25212/*!
25213@brief Defines the attributes of an Explosion: particleEmitters, debris, lighting and camera shake effects.
25214@ingroup FX
25215
25216*/
25217class ExplosionData : public GameBaseData {
25218public:
25219
25220/*! @name Callbacks
25221@{ */
25222/// @}
25223
25224/*!
25225@brief @brief Optional DTS or DAE shape to place at the center of the explosion.
25226
25227
25228The <i>ambient</i> animation of this model will be played automatically at the start of the explosion.
25229*/
25230filename explosionShape;
25231/*!
25232@brief "X Y Z" scale factor applied to the explosionShape model at the start of the explosion.
25233*/
25234Point3F explosionScale;
25235/*!
25236@brief Time scale at which to play the explosionShape <i>ambient</i> sequence.
25237*/
25238float playSpeed;
25239/*!
25240@brief Non-looping sound effect that will be played at the start of the explosion.
25241*/
25242SFXTrack soundProfile;
25243/*!
25244@brief Controls whether the visual effects of the explosion always face the camera.
25245*/
25246bool faceViewer;
25247/*!
25248@brief @brief Emitter used to generate a cloud of particles at the start of the explosion.
25249
25250
25251Explosions can generate two different particle effects. The first is a single burst of particles at the start of the explosion emitted in a spherical cloud using particleEmitter.
25252
25253The second effect spawns the list of ParticleEmitters given by the emitter[] field. These emitters generate particles in the normal way throughout the lifetime of the explosion.
25254*/
25255ParticleEmitterData ParticleEmitter;
25256/*!
25257@brief @brief Density of the particle cloud created at the start of the explosion.
25258
25259
25260@see particleEmitter
25261*/
25262int particleDensity;
25263/*!
25264@brief @brief Radial distance from the explosion center at which cloud particles are emitted.
25265
25266
25267@see particleEmitter
25268*/
25269float particleRadius;
25270/*!
25271@brief @brief List of additional ParticleEmitterData objects to spawn with this explosion.
25272
25273
25274@see particleEmitter
25275*/
25276ParticleEmitterData emitter[ 4 ];
25277/*!
25278@brief List of DebrisData objects to spawn with this explosion.
25279*/
25280DebrisData Debris;
25281/*!
25282@brief Minimum angle, from the horizontal plane, to eject debris from.
25283*/
25284float debrisThetaMin;
25285/*!
25286@brief Maximum angle, from the horizontal plane, to eject debris from.
25287*/
25288float debrisThetaMax;
25289/*!
25290@brief Minimum reference angle, from the vertical plane, to eject debris from.
25291*/
25292float debrisPhiMin;
25293/*!
25294@brief Maximum reference angle, from the vertical plane, to eject debris from.
25295*/
25296float debrisPhiMax;
25297/*!
25298@brief Number of debris objects to create.
25299*/
25300int debrisNum;
25301/*!
25302@brief Variance in the number of debris objects to create (must be from 0 - debrisNum).
25303*/
25304int debrisNumVariance;
25305/*!
25306@brief Velocity to toss debris at.
25307*/
25308float debrisVelocity;
25309/*!
25310@brief Variance in the debris initial velocity (must be >= 0).
25311*/
25312float debrisVelocityVariance;
25313/*!
25314@brief List of additional ExplosionData objects to create at the start of the explosion.
25315*/
25316ExplosionData subExplosion[ 5 ];
25317/*!
25318@brief Amount of time, in milliseconds, to delay the start of the explosion effect from the creation of the Explosion object.
25319*/
25320int delayMS;
25321/*!
25322@brief Variance, in milliseconds, of delayMS.
25323*/
25324int delayVariance;
25325/*!
25326@brief @brief Lifetime, in milliseconds, of the Explosion object.
25327
25328
25329@note If explosionShape is defined and contains an <i>ambient</i> animation, this field is ignored, and the playSpeed scaled duration of the animation is used instead.
25330*/
25331int lifetimeMS;
25332/*!
25333@brief Variance, in milliseconds, of the lifetimeMS of the Explosion object.
25334
25335
25336*/
25337int lifetimeVariance;
25338/*!
25339@brief @brief Offset distance (in a random direction) of the center of the explosion from the Explosion object position.
25340
25341
25342Most often used to create some variance in position for subExplosion effects.
25343*/
25344float offset;
25345/*!
25346@brief @brief Time keyframes used to scale the explosionShape model.
25347
25348
25349Values should be in increasing order from 0.0 - 1.0, and correspond to the life of the Explosion where 0 is the beginning and 1 is the end of the explosion lifetime.
25350@see lifetimeMS
25351*/
25352float times[ 4 ];
25353/*!
25354@brief @brief "X Y Z" size keyframes used to scale the explosionShape model.
25355
25356
25357The explosionShape (if defined) will be scaled using the times/sizes keyframes over the lifetime of the explosion.
25358@see lifetimeMS
25359*/
25360Point3F sizes[ 4 ];
25361/*!
25362@brief Controls whether the camera shakes during this explosion.
25363*/
25364bool ShakeCamera;
25365/*!
25366@brief Frequency of camera shaking, defined in the "X Y Z" axes.
25367*/
25368Point3F camShakeFreq;
25369/*!
25370@brief @brief Amplitude of camera shaking, defined in the "X Y Z" axes.
25371
25372
25373Set any value to 0 to disable shaking in that axis.
25374*/
25375Point3F camShakeAmp;
25376/*!
25377@brief Duration (in seconds) to shake the camera.
25378*/
25379float camShakeDuration;
25380/*!
25381@brief Radial distance that a camera's position must be within relative to the center of the explosion to be shaken.
25382*/
25383float camShakeRadius;
25384/*!
25385@brief Falloff value for the camera shake.
25386*/
25387float camShakeFalloff;
25388/*!
25389@brief @brief Initial radius of the PointLight created by this explosion.
25390
25391
25392Radius is linearly interpolated from lightStartRadius to lightEndRadius over the lifetime of the explosion.
25393@see lifetimeMS
25394*/
25395float lightStartRadius;
25396/*!
25397@brief @brief Final radius of the PointLight created by this explosion.
25398
25399
25400@see lightStartRadius
25401*/
25402float lightEndRadius;
25403/*!
25404@brief @brief Initial color of the PointLight created by this explosion.
25405
25406
25407Color is linearly interpolated from lightStartColor to lightEndColor over the lifetime of the explosion.
25408@see lifetimeMS
25409*/
25410LinearColorF lightStartColor;
25411/*!
25412@brief @brief Final color of the PointLight created by this explosion.
25413
25414
25415@see lightStartColor
25416*/
25417LinearColorF lightEndColor;
25418/*!
25419@brief @brief Initial brightness of the PointLight created by this explosion.
25420
25421
25422Brightness is linearly interpolated from lightStartBrightness to lightEndBrightness over the lifetime of the explosion.
25423@see lifetimeMS
25424*/
25425float lightStartBrightness;
25426/*!
25427@brief @brief Final brightness of the PointLight created by this explosion.
25428
25429
25430@see lightStartBrightness
25431*/
25432float lightEndBrightness;
25433/*!
25434@brief Distance (in the explosion normal direction) of the PointLight position from the explosion center.
25435*/
25436float lightNormalOffset;
25437
25438/*! @name Scripting
25439@{ */
25440/// @}
25441
25442
25443/*! @name Ungrouped
25444@{ */
25445/// @}
25446
25447
25448/*! @name Object
25449@{ */
25450/// @}
25451
25452
25453/*! @name Editing
25454@{ */
25455/// @}
25456
25457
25458/*! @name Persistence
25459@{ */
25460/// @}
25461
25462};
25463
25464/*!
25465@brief An emitter to replicate fxFoliageItem objects across an area.
25466@ingroup Foliage
25467
25468*/
25469class fxFoliageReplicator : public SceneObject {
25470public:
25471
25472/*! @name Callbacks
25473@{ */
25474/// @}
25475
25476/*!
25477@brief Disables rendering of all instances of this type.
25478
25479
25480@ingroup UNDOCUMENTED
25481*/
25482static bool isRenderable;
25483/*!
25484@brief Disables selection of all instances of this type.
25485
25486
25487@ingroup UNDOCUMENTED
25488*/
25489static bool isSelectable;
25490
25491/*! @name Debugging
25492@{ */
25493/*!
25494@brief Culling bins are drawn when set to true.
25495*/
25496bool UseDebugInfo;
25497/*!
25498@brief Height multiplier for drawn culling bins.
25499*/
25500float DebugBoxHeight;
25501/*!
25502@brief Foliage is hidden when set to true.
25503*/
25504bool HideFoliage;
25505/*!
25506@brief Draw placement rings when set to true.
25507*/
25508bool ShowPlacementArea;
25509/*!
25510@brief Height of the placement ring in world units.
25511*/
25512int PlacementAreaHeight;
25513/*!
25514@brief Color of the placement ring.
25515*/
25516LinearColorF PlacementColour;
25517/// @}
25518
25519
25520/*! @name Media
25521@{ */
25522/*!
25523@brief Random seed for foliage placement.
25524*/
25525int seed;
25526/*!
25527@brief Image file for the foliage texture.
25528*/
25529filename FoliageFile;
25530/*!
25531@brief Maximum foliage instance count.
25532*/
25533int FoliageCount;
25534/*!
25535@brief Number of times to try placing a foliage instance before giving up.
25536*/
25537int FoliageRetries;
25538/// @}
25539
25540
25541/*! @name Area
25542@{ */
25543/*!
25544@brief Placement area inner radius on the X axis
25545*/
25546int InnerRadiusX;
25547/*!
25548@brief Placement area inner radius on the Y axis
25549*/
25550int InnerRadiusY;
25551/*!
25552@brief Placement area outer radius on the X axis
25553*/
25554int OuterRadiusX;
25555/*!
25556@brief Placement area outer radius on the Y axis
25557*/
25558int OuterRadiusY;
25559/// @}
25560
25561
25562/*! @name Dimensions
25563@{ */
25564/*!
25565@brief Minimum width of foliage billboards
25566*/
25567float MinWidth;
25568/*!
25569@brief Maximum width of foliage billboards
25570*/
25571float MaxWidth;
25572/*!
25573@brief Minimum height of foliage billboards
25574*/
25575float MinHeight;
25576/*!
25577@brief Maximum height of foliage billboards
25578*/
25579float MaxHeight;
25580/*!
25581@brief Maintain aspect ratio of image if true. This option ignores MaxWidth.
25582*/
25583bool FixAspectRatio;
25584/*!
25585@brief Use only MaxWidth and MaxHeight for billboard size. Ignores MinWidth and MinHeight.
25586*/
25587bool FixSizeToMax;
25588/*!
25589@brief Offset billboards by this amount vertically.
25590*/
25591float OffsetZ;
25592/*!
25593@brief Randomly flip billboards left-to-right.
25594*/
25595bool RandomFlip;
25596/*!
25597@brief Use camera facing billboards ( including the z axis ).
25598*/
25599bool useTrueBillboards;
25600/// @}
25601
25602
25603/*! @name Culling
25604@{ */
25605/*!
25606@brief Use culling bins when enabled.
25607*/
25608bool UseCulling;
25609/*!
25610@brief Minimum size of culling bins.  Must be >= 8 and <= OuterRadius.
25611*/
25612int CullResolution;
25613/*!
25614@brief Maximum distance from camera where foliage appears.
25615*/
25616float ViewDistance;
25617/*!
25618@brief Minimum distance from camera where foliage appears.
25619*/
25620float ViewClosest;
25621/*!
25622@brief Region beyond ViewDistance where foliage fades in/out.
25623*/
25624float FadeInRegion;
25625/*!
25626@brief Region before ViewClosest where foliage fades in/out.
25627*/
25628float FadeOutRegion;
25629/*!
25630@brief Minimum alpha value allowed on foliage instances.
25631*/
25632float AlphaCutoff;
25633/*!
25634@brief Alpha of the foliage at ground level. 0 = transparent, 1 = opaque.
25635*/
25636float GroundAlpha;
25637/// @}
25638
25639
25640/*! @name Animation
25641@{ */
25642/*!
25643@brief Foliage should sway randomly when true.
25644*/
25645bool SwayOn;
25646/*!
25647@brief Foliage instances should sway together when true and SwayOn is enabled.
25648*/
25649bool SwaySync;
25650/*!
25651@brief Left-to-right sway magnitude.
25652*/
25653float SwayMagSide;
25654/*!
25655@brief Front-to-back sway magnitude.
25656*/
25657float SwayMagFront;
25658/*!
25659@brief Minumum sway cycle time in seconds.
25660*/
25661float MinSwayTime;
25662/*!
25663@brief Maximum sway cycle time in seconds.
25664*/
25665float MaxSwayTime;
25666/// @}
25667
25668
25669/*! @name Lighting
25670@{ */
25671/*!
25672@brief Foliage should be illuminated with changing lights when true.
25673*/
25674bool LightOn;
25675/*!
25676@brief Foliage instances have the same lighting when set and LightOn is set.
25677*/
25678bool LightSync;
25679/*!
25680@brief Minimum luminance for foliage instances.
25681*/
25682float MinLuminance;
25683/*!
25684@brief Maximum luminance for foliage instances.
25685*/
25686float MaxLuminance;
25687/*!
25688@brief Time before foliage illumination cycle repeats.
25689*/
25690float lightTime;
25691/// @}
25692
25693
25694/*! @name Restrictions
25695@{ */
25696/*!
25697@brief Foliage will be placed on terrain when set.
25698*/
25699bool AllowOnTerrain;
25700/*!
25701@brief Foliage will be placed on Static shapes when set.
25702*/
25703bool AllowOnStatics;
25704/*!
25705@brief Foliage will be placed on/under water when set.
25706*/
25707bool AllowOnWater;
25708/*!
25709@brief Foliage will be placed on water when set. Requires AllowOnWater.
25710*/
25711bool AllowWaterSurface;
25712/*!
25713@brief Maximum surface angle allowed for foliage instances.
25714*/
25715int AllowedTerrainSlope;
25716/// @}
25717
25718
25719/*! @name AFX
25720@{ */
25721/*!
25722@brief Multiplier controling amount foliage is modulated by sun's ambient.
25723*/
25724float AmbientModulationBias;
25725/// @}
25726
25727
25728/*! @name GameObject
25729@{ */
25730/// @}
25731
25732
25733/*! @name Transform
25734@{ */
25735/// @}
25736
25737
25738/*! @name Editing
25739@{ */
25740/// @}
25741
25742
25743/*! @name Mounting
25744@{ */
25745/// @}
25746
25747
25748/*! @name Ungrouped
25749@{ */
25750/// @}
25751
25752
25753/*! @name Object
25754@{ */
25755/// @}
25756
25757
25758/*! @name Editing
25759@{ */
25760/// @}
25761
25762
25763/*! @name Persistence
25764@{ */
25765/// @}
25766
25767};
25768
25769/*!
25770@brief An emitter for objects to replicate across an area.
25771@ingroup Foliage
25772
25773*/
25774class fxShapeReplicator : public SceneObject {
25775public:
25776
25777/*! @name Callbacks
25778@{ */
25779/// @}
25780
25781/*!
25782@brief Disables rendering of all instances of this type.
25783
25784
25785@ingroup UNDOCUMENTED
25786*/
25787static bool isRenderable;
25788/*!
25789@brief Disables selection of all instances of this type.
25790
25791
25792@ingroup UNDOCUMENTED
25793*/
25794static bool isSelectable;
25795
25796/*! @name Debugging
25797@{ */
25798/*!
25799@brief Replicated shapes are hidden when set to true.
25800*/
25801bool HideReplications;
25802/*!
25803@brief Draw placement rings when set to true.
25804*/
25805bool ShowPlacementArea;
25806/*!
25807@brief Height of the placement ring in world units.
25808*/
25809int PlacementAreaHeight;
25810/*!
25811@brief Color of the placement ring.
25812*/
25813LinearColorF PlacementColour;
25814/// @}
25815
25816
25817/*! @name Media
25818@{ */
25819/*!
25820@brief Filename of shape to replicate.
25821*/
25822filename shapeFile;
25823/// @}
25824
25825
25826/*! @name Replications
25827@{ */
25828/*!
25829@brief Random seed for shape placement.
25830*/
25831int seed;
25832/*!
25833@brief Maximum shape instance count.
25834*/
25835int ShapeCount;
25836/*!
25837@brief Number of times to try placing a shape instance before giving up.
25838*/
25839int ShapeRetries;
25840/// @}
25841
25842
25843/*! @name Placement Radius
25844@{ */
25845/*!
25846@brief Placement area inner radius on the X axis
25847*/
25848int InnerRadiusX;
25849/*!
25850@brief Placement area inner radius on the Y axis
25851*/
25852int InnerRadiusY;
25853/*!
25854@brief Placement area outer radius on the X axis
25855*/
25856int OuterRadiusX;
25857/*!
25858@brief Placement area outer radius on the Y axis
25859*/
25860int OuterRadiusY;
25861/// @}
25862
25863
25864/*! @name Restraints
25865@{ */
25866/*!
25867@brief Shapes will be placed on terrain when set.
25868*/
25869bool AllowOnTerrain;
25870/*!
25871@brief Shapes will be placed on Static shapes when set.
25872*/
25873bool AllowOnStatics;
25874/*!
25875@brief Shapes will be placed on/under water when set.
25876*/
25877bool AllowOnWater;
25878/*!
25879@brief Shapes will be placed on water when set. Requires AllowOnWater.
25880*/
25881bool AllowWaterSurface;
25882/*!
25883@brief Align shapes to surface normal when set.
25884*/
25885bool AlignToTerrain;
25886/*!
25887@brief Allow physics interactions with shapes.
25888*/
25889bool Interactions;
25890/*!
25891@brief Maximum surface angle allowed for shape instances.
25892*/
25893int AllowedTerrainSlope;
25894/*!
25895@brief Surface normals will be multiplied by these values when AlignToTerrain is enabled.
25896*/
25897Point3F TerrainAlignment;
25898/// @}
25899
25900
25901/*! @name Object Transforms
25902@{ */
25903/*!
25904@brief Minimum shape scale.
25905*/
25906Point3F ShapeScaleMin;
25907/*!
25908@brief Maximum shape scale.
25909*/
25910Point3F ShapeScaleMax;
25911/*!
25912@brief Minimum shape rotation angles.
25913*/
25914Point3F ShapeRotateMin;
25915/*!
25916@brief Maximum shape rotation angles.
25917*/
25918Point3F ShapeRotateMax;
25919/*!
25920@brief Offset shapes by this amount vertically.
25921*/
25922int OffsetZ;
25923/// @}
25924
25925
25926/*! @name GameObject
25927@{ */
25928/// @}
25929
25930
25931/*! @name Transform
25932@{ */
25933/// @}
25934
25935
25936/*! @name Editing
25937@{ */
25938/// @}
25939
25940
25941/*! @name Mounting
25942@{ */
25943/// @}
25944
25945
25946/*! @name Ungrouped
25947@{ */
25948/// @}
25949
25950
25951/*! @name Object
25952@{ */
25953/// @}
25954
25955
25956/*! @name Editing
25957@{ */
25958/// @}
25959
25960
25961/*! @name Persistence
25962@{ */
25963/// @}
25964
25965};
25966
25967/*!
25968@brief The object definition for shapes that will be replicated across an area using an fxShapeReplicator.
25969@ingroup Foliage
25970
25971*/
25972class fxShapeReplicatedStatic : public SceneObject {
25973public:
25974
25975/*! @name Callbacks
25976@{ */
25977/// @}
25978
25979/*!
25980@brief Disables rendering of all instances of this type.
25981
25982
25983@ingroup UNDOCUMENTED
25984*/
25985static bool isRenderable;
25986/*!
25987@brief Disables selection of all instances of this type.
25988
25989
25990@ingroup UNDOCUMENTED
25991*/
25992static bool isSelectable;
25993/*!
25994@brief Percent Animation Offset.
25995*/
25996float AnimOffset;
25997/*!
25998@brief Percent Animation Speed.
25999*/
26000float AnimSpeed;
26001
26002/*! @name Shape
26003@{ */
26004/*!
26005@brief The source shape asset.
26006*/
26007assetIdString ShapeAsset;
26008/*!
26009@brief %Path and filename of the model file (.DTS, .DAE) to use for this TSStatic. Legacy field. Any loose files assigned here will attempt to be auto-imported in as an asset.
26010*/
26011filename shapeName;
26012/// @}
26013
26014
26015/*! @name Materials
26016@{ */
26017/*!
26018@brief @brief The skin applied to the shape.
26019
26020
26021'Skinning' the shape effectively renames the material targets, allowing different materials to be used on different instances of the same model.
26022
26023Any material targets that start with the old skin name have that part of the name replaced with the new skin name. The initial old skin name is "base". For example, if a new skin of "blue" was applied to a model that had material targets <i>base_body</i> and <i>face</i>, the new targets would be <i>blue_body</i> and <i>face</i>. Note that <i>face</i> was not renamed since it did not start with the old skin name of "base".
26024
26025To support models that do not use the default "base" naming convention, you can also specify the part of the name to replace in the skin field itself. For example, if a model had a material target called <i>shapemat</i>, we could apply a new skin "shape=blue", and the material target would be renamed to <i>bluemat</i> (note "shape" has been replaced with "blue").
26026
26027Multiple skin updates can also be applied at the same time by separating them with a semicolon. For example: "base=blue;face=happy_face".
26028
26029Material targets are only renamed if an existing Material maps to that name, or if there is a diffuse texture in the model folder with the same name as the new target.
26030
26031
26032*/
26033string skin;
26034/// @}
26035
26036
26037/*! @name Rendering
26038@{ */
26039/*!
26040@brief Enables automatic playing of the animation sequence named "ambient" (if it exists) when the TSStatic is loaded.
26041*/
26042bool playAmbient;
26043/*!
26044@brief Enables detailed culling of meshes within the TSStatic. Should only be used with large complex shapes like buildings which contain many submeshes.
26045*/
26046bool meshCulling;
26047/*!
26048@brief Enables translucent sorting of the TSStatic by its origin instead of the bounds.
26049*/
26050bool originSort;
26051/// @}
26052
26053
26054/*! @name Reflection
26055@{ */
26056/*!
26057@brief References a ReflectorDesc datablock that defines performance and quality properties for dynamic reflections.
26058
26059
26060*/
26061string cubeReflectorDesc;
26062/// @}
26063
26064
26065/*! @name Collision
26066@{ */
26067/*!
26068@brief The type of mesh data to use for collision queries.
26069*/
26070TSMeshType collisionType;
26071/*!
26072@brief The type of mesh data used to clip decal polygons against.
26073*/
26074TSMeshType decalType;
26075/*!
26076@brief @brief Allow a Player to walk up sloping polygons in the TSStatic (based on the collisionType).
26077
26078
26079When set to false, the slightest bump will stop the player from walking on top of the object.
26080
26081*/
26082bool allowPlayerStep;
26083/// @}
26084
26085
26086/*! @name AlphaFade
26087@{ */
26088/*!
26089@brief Turn on/off Alpha Fade
26090*/
26091bool alphaFadeEnable;
26092/*!
26093@brief Distance of start Alpha Fade
26094*/
26095float alphaFadeStart;
26096/*!
26097@brief Distance of end Alpha Fade
26098*/
26099float alphaFadeEnd;
26100/*!
26101@brief Invert Alpha Fade's Start & End Distance
26102*/
26103bool alphaFadeInverse;
26104/// @}
26105
26106
26107/*! @name Debug
26108@{ */
26109/*!
26110@brief Debug rendering mode shows the normals for each point in the TSStatic's mesh.
26111*/
26112float renderNormals;
26113/*!
26114@brief Forces rendering to a particular detail level.
26115*/
26116int forceDetail;
26117/// @}
26118
26119
26120/*! @name AFX
26121@{ */
26122/*!
26123*/
26124bool ignoreZodiacs;
26125/*!
26126*/
26127bool useGradientRange;
26128/*!
26129*/
26130Point2F gradientRange;
26131/*!
26132*/
26133bool invertGradientRange;
26134/// @}
26135
26136
26137/*! @name GameObject
26138@{ */
26139/// @}
26140
26141
26142/*! @name Transform
26143@{ */
26144/// @}
26145
26146
26147/*! @name Editing
26148@{ */
26149/// @}
26150
26151
26152/*! @name Mounting
26153@{ */
26154/// @}
26155
26156
26157/*! @name Ungrouped
26158@{ */
26159/// @}
26160
26161
26162/*! @name Object
26163@{ */
26164/// @}
26165
26166
26167/*! @name Editing
26168@{ */
26169/// @}
26170
26171
26172/*! @name Persistence
26173@{ */
26174/// @}
26175
26176};
26177
26178/*!
26179@brief Covers the ground in a field of objects (IE: Grass, Flowers, etc).@ingroup Foliage
26180
26181*/
26182class GroundCover : public SceneObject {
26183public:
26184
26185/*! @name Callbacks
26186@{ */
26187/// @}
26188
26189/*!
26190@brief Stat for number of rendered cells.
26191
26192@ingroup Foliage
26193*/
26194static int renderedCells;
26195/*!
26196@brief Stat for number of rendered billboards.
26197
26198@ingroup Foliage
26199*/
26200static int renderedBillboards;
26201/*!
26202@brief Stat for number of rendered billboard batches.
26203
26204@ingroup Foliage
26205*/
26206static int renderedBatches;
26207/*!
26208@brief Stat for number of rendered shapes.
26209
26210@ingroup Foliage
26211*/
26212static int renderedShapes;
26213/*!
26214@brief Disables rendering of all instances of this type.
26215
26216
26217@ingroup UNDOCUMENTED
26218*/
26219static bool isRenderable;
26220/*!
26221@brief Disables selection of all instances of this type.
26222
26223
26224@ingroup UNDOCUMENTED
26225*/
26226static bool isSelectable;
26227
26228/*! @name GroundCover General
26229@{ */
26230/*!
26231@brief  ¨ç
26232*/
26233string MaterialFile;
26234/*!
26235@brief ðŒE 
26236*/
26237assetIdString MaterialAsset;
26238/*!
26239@brief Outer generation radius from the current camera position.
26240*/
26241float radius;
26242/*!
26243@brief This is less than or equal to radius and defines when fading of cover elements begins.
26244*/
26245float dissolveRadius;
26246/*!
26247@brief Scales the various culling radii when rendering a reflection. Typically for water.
26248*/
26249float reflectScale;
26250/*!
26251@brief The number of cells per axis in the grid.
26252*/
26253int gridSize;
26254/*!
26255@brief Offset along the Z axis to render the ground cover.
26256*/
26257float zOffset;
26258/*!
26259@brief This RNG seed is saved and sent to clients for generating the same cover.
26260*/
26261int seed;
26262/*!
26263@brief The maximum amount of cover elements to include in the grid at any one time.
26264*/
26265int maxElements;
26266/*!
26267@brief The maximum amout of degrees the billboard will tilt down to match the camera.
26268*/
26269float maxBillboardTiltAngle;
26270/*!
26271@brief This is the distance at which DTS elements are  completely culled out.
26272*/
26273float shapeCullRadius;
26274/*!
26275@brief Whether DTS elements should cast shadows or not.
26276*/
26277bool shapesCastShadows;
26278/*!
26279@brief Subset material UV coordinates for this cover billboard.
26280*/
26281RectF billboardUVs[ 8 ];
26282/*!
26283@brief The cover shape filename. [Optional]
26284*/
26285filename shapeFilename[ 8 ];
26286/*!
26287@brief Terrain material name to limit coverage to, or blank to not limit.
26288*/
26289string layer[ 8 ];
26290/*!
26291@brief Indicates that the terrain material index given in 'layer' is an exclusion mask.
26292*/
26293bool invertLayer[ 8 ];
26294/*!
26295@brief The probability of one cover type verses another (relative to all cover types).
26296*/
26297float probability[ 8 ];
26298/*!
26299@brief The minimum random size for each cover type.
26300*/
26301float sizeMin[ 8 ];
26302/*!
26303@brief The maximum random size of this cover type.
26304*/
26305float sizeMax[ 8 ];
26306/*!
26307@brief An exponent used to bias between the minimum and maximum random sizes.
26308*/
26309float sizeExponent[ 8 ];
26310/*!
26311@brief The wind effect scale.
26312*/
26313float windScale[ 8 ];
26314/*!
26315@brief The minimum slope angle in degrees for placement.
26316*/
26317float minSlope[ 8 ];
26318/*!
26319@brief The maximum slope angle in degrees for placement.
26320*/
26321float maxSlope[ 8 ];
26322/*!
26323@brief Use the terrain's slope for angle
26324*/
26325bool conformToNormal[ 8 ];
26326/*!
26327@brief minumum amount of rotation along the X axis to add
26328*/
26329float minRotX[ 8 ];
26330/*!
26331@brief maximum amount of rotation along the X axis to add
26332*/
26333float maxRotX[ 8 ];
26334/*!
26335@brief minumum amount of rotation along the Y axis to add
26336*/
26337float minRotY[ 8 ];
26338/*!
26339@brief maximum amount of rotation along the Y axis to add
26340*/
26341float maxRotY[ 8 ];
26342/*!
26343@brief The minimum world space elevation for placement.
26344*/
26345float minElevation[ 8 ];
26346/*!
26347@brief The maximum world space elevation for placement.
26348*/
26349float maxElevation[ 8 ];
26350/*!
26351@brief The minimum amount of elements in a clump.
26352*/
26353int minClumpCount[ 8 ];
26354/*!
26355@brief The maximum amount of elements in a clump.
26356*/
26357int maxClumpCount[ 8 ];
26358/*!
26359@brief An exponent used to bias between the minimum and maximum clump counts for a particular clump.
26360*/
26361float clumpExponent[ 8 ];
26362/*!
26363@brief The maximum clump radius.
26364*/
26365float clumpRadius[ 8 ];
26366/// @}
26367
26368
26369/*! @name GroundCover Wind
26370@{ */
26371/*!
26372@brief The direction of the wind.
26373*/
26374Point2F windDirection;
26375/*!
26376@brief The length in meters between peaks in the wind gust.
26377*/
26378float windGustLength;
26379/*!
26380@brief Controls how often the wind gust peaks per second.
26381*/
26382float windGustFrequency;
26383/*!
26384@brief The maximum distance in meters that the peak wind  gust will displace an element.
26385*/
26386float windGustStrength;
26387/*!
26388@brief Controls the overall rapidity of the wind turbulence.
26389*/
26390float windTurbulenceFrequency;
26391/*!
26392@brief The maximum distance in meters that the turbulence can displace a ground cover element.
26393*/
26394float windTurbulenceStrength;
26395/// @}
26396
26397
26398/*! @name GroundCover Debug
26399@{ */
26400/*!
26401@brief Debug parameter for locking the culling frustum which will freeze the cover generation.
26402*/
26403bool lockFrustum;
26404/*!
26405@brief Debug parameter for displaying the grid cells.
26406*/
26407bool renderCells;
26408/*!
26409@brief Debug parameter for turning off billboard rendering.
26410*/
26411bool noBillboards;
26412/*!
26413@brief Debug parameter for turning off shape rendering.
26414*/
26415bool noShapes;
26416/// @}
26417
26418
26419/*! @name GameObject
26420@{ */
26421/// @}
26422
26423
26424/*! @name Transform
26425@{ */
26426/// @}
26427
26428
26429/*! @name Editing
26430@{ */
26431/// @}
26432
26433
26434/*! @name Mounting
26435@{ */
26436/// @}
26437
26438
26439/*! @name Ungrouped
26440@{ */
26441/// @}
26442
26443
26444/*! @name Object
26445@{ */
26446/// @}
26447
26448
26449/*! @name Editing
26450@{ */
26451/// @}
26452
26453
26454/*! @name Persistence
26455@{ */
26456/// @}
26457
26458};
26459
26460/*!
26461@brief Common data for a Lightning emitter object.
26462@see Lightning
26463@ingroup FX
26464@ingroup Atmosphere
26465@ingroup Datablocks
26466
26467*/
26468class LightningData : public GameBaseData {
26469public:
26470
26471/*! @name Callbacks
26472@{ */
26473/// @}
26474
26475/*!
26476@brief Sound profile to play when a lightning strike occurs.
26477*/
26478SFXTrack strikeSound;
26479/*!
26480@brief @brief List of thunder sound effects to play.
26481
26482
26483A random one of these sounds will be played shortly after each strike occurs.
26484*/
26485SFXTrack thunderSounds[ 8 ];
26486/*!
26487@brief List of textures to use to render lightning strikes.
26488*/
26489string strikeTextures[ 8 ];
26490
26491/*! @name Scripting
26492@{ */
26493/// @}
26494
26495
26496/*! @name Ungrouped
26497@{ */
26498/// @}
26499
26500
26501/*! @name Object
26502@{ */
26503/// @}
26504
26505
26506/*! @name Editing
26507@{ */
26508/// @}
26509
26510
26511/*! @name Persistence
26512@{ */
26513/// @}
26514
26515};
26516
26517/*!
26518@brief Network event that triggers a lightning strike on the client when it is received.
26519
26520This event is sent to all clients when the warningFlashes(), strikeRandomPoint() or strikeObject() methods are invoked on the Lightning object on the server.
26521@see Lightning, LightningData
26522@ingroup FX
26523@ingroup Atmosphere
26524
26525*/
26526class LightningStrikeEvent {
26527public:
26528
26529/*! @name Callbacks
26530@{ */
26531/// @}
26532
26533};
26534
26535/*!
26536@brief This object is responsible for spawning particles.
26537
26538@note This class is not normally instantiated directly - to place a simple particle emitting object in the scene, use a ParticleEmitterNode instead.
26539
26540This class is the main interface for creating particles - though it is usually only accessed from within another object like ParticleEmitterNode or WheeledVehicle. If using this object class (via C++) directly, be aware that it does <b>not</b> track changes in source axis or velocity over the course of a single update, so emitParticles should be called at a fairly fine grain.  The emitter will potentially track the last particle to be created into the next call to this function in order to create a uniformly random time distribution of the particles.
26541
26542If the object to which the emitter is attached is in motion, it should try to ensure that for call (n+1) to this function, start is equal to the end from call (n). This will ensure a uniform spatial distribution.
26543
26544@ingroup FX
26545@see ParticleEmitterData
26546@see ParticleEmitterNode
26547
26548*/
26549class ParticleEmitter : public GameBase {
26550public:
26551
26552/*! @name Callbacks
26553@{ */
26554/// @}
26555
26556/*!
26557@brief Disables rendering of all instances of this type.
26558
26559
26560@ingroup UNDOCUMENTED
26561*/
26562static bool isRenderable;
26563/*!
26564@brief Disables selection of all instances of this type.
26565
26566
26567@ingroup UNDOCUMENTED
26568*/
26569static bool isSelectable;
26570
26571/*! @name Game
26572@{ */
26573/// @}
26574
26575
26576/*! @name GameObject
26577@{ */
26578/// @}
26579
26580
26581/*! @name Transform
26582@{ */
26583/// @}
26584
26585
26586/*! @name Editing
26587@{ */
26588/// @}
26589
26590
26591/*! @name Mounting
26592@{ */
26593/// @}
26594
26595
26596/*! @name Ungrouped
26597@{ */
26598/// @}
26599
26600
26601/*! @name Object
26602@{ */
26603/// @}
26604
26605
26606/*! @name Editing
26607@{ */
26608/// @}
26609
26610
26611/*! @name Persistence
26612@{ */
26613/// @}
26614
26615};
26616
26617/*!
26618@brief Contains additional data to be associated with a ParticleEmitterNode.@ingroup FX
26619
26620*/
26621class ParticleEmitterNodeData : public GameBaseData {
26622public:
26623
26624/*! @name Callbacks
26625@{ */
26626/// @}
26627
26628/*!
26629@brief @brief Time multiplier for particle emitter nodes.
26630
26631
26632Increasing timeMultiple is like running the emitter at a faster rate - single-shot emitters will complete in a shorter time, and continuous emitters will generate particles more quickly.
26633
26634Valid range is 0.01 - 100.
26635*/
26636float timeMultiple;
26637
26638/*! @name Scripting
26639@{ */
26640/// @}
26641
26642
26643/*! @name Ungrouped
26644@{ */
26645/// @}
26646
26647
26648/*! @name Object
26649@{ */
26650/// @}
26651
26652
26653/*! @name Editing
26654@{ */
26655/// @}
26656
26657
26658/*! @name Persistence
26659@{ */
26660/// @}
26661
26662};
26663
26664/*!
26665@brief Defines the droplets used in a storm (raindrops, snowflakes, etc).
26666
26667@tsexample
26668datablock PrecipitationData( HeavyRain )
26669{
26670   soundProfile = "HeavyRainSound";
26671   dropTexture = "art/environment/precipitation/rain";
26672   splashTexture = "art/environment/precipitation/water_splash";
26673   dropsPerSide = 4;
26674   splashesPerSide = 2;
26675};
26676@endtsexample
26677@ingroup FX
26678@ingroup Atmosphere
26679@see Precipitation
26680
26681*/
26682class PrecipitationData : public GameBaseData {
26683public:
26684
26685/*! @name Callbacks
26686@{ */
26687/// @}
26688
26689/*!
26690@brief Looping SFXProfile effect to play while Precipitation is active.
26691*/
26692SFXTrack soundProfile;
26693/*!
26694@brief @brief Texture filename for drop particles.
26695
26696
26697The drop texture can contain several different drop sub-textures arranged in a grid. There must be the same number of rows as columns. A random frame will be chosen for each drop.
26698*/
26699filename dropTexture;
26700/*!
26701@brief The name of the shader used for raindrops.
26702*/
26703string dropShader;
26704/*!
26705@brief @brief Texture filename for splash particles.
26706
26707
26708The splash texture can contain several different splash sub-textures arranged in a grid. There must be the same number of rows as columns. A random frame will be chosen for each splash.
26709*/
26710filename splashTexture;
26711/*!
26712@brief The name of the shader used for splashes.
26713*/
26714string splashShader;
26715/*!
26716@brief @brief How many rows and columns are in the raindrop texture.
26717
26718
26719For example, if the texture has 16 raindrops arranged in a grid, this field should be set to 4.
26720*/
26721int dropsPerSide;
26722/*!
26723@brief @brief How many rows and columns are in the splash texture.
26724
26725
26726For example, if the texture has 9 splashes arranged in a grid, this field should be set to 3.
26727*/
26728int splashesPerSide;
26729
26730/*! @name Scripting
26731@{ */
26732/// @}
26733
26734
26735/*! @name Ungrouped
26736@{ */
26737/// @}
26738
26739
26740/*! @name Object
26741@{ */
26742/// @}
26743
26744
26745/*! @name Editing
26746@{ */
26747/// @}
26748
26749
26750/*! @name Persistence
26751@{ */
26752/// @}
26753
26754};
26755
26756/*! UNDOCUMENTED!
26757@ingroup UNDOCUMENTED
26758 */
26759class RibbonData : public GameBaseData {
26760public:
26761
26762/*! @name Callbacks
26763@{ */
26764/// @}
26765
26766
26767/*! @name Scripting
26768@{ */
26769/// @}
26770
26771
26772/*! @name Ungrouped
26773@{ */
26774/// @}
26775
26776
26777/*! @name Object
26778@{ */
26779/// @}
26780
26781
26782/*! @name Editing
26783@{ */
26784/// @}
26785
26786
26787/*! @name Persistence
26788@{ */
26789/// @}
26790
26791
26792/*! @name Ribbon
26793@{ */
26794/*!
26795@brief The size of the ribbon at the specified keyframe.
26796*/
26797float size[ 4 ];
26798/*!
26799@brief The colour of the ribbon at the specified keyframe.
26800*/
26801LinearColorF color[ 4 ];
26802/*!
26803@brief The position of the keyframe along the lifetime of the ribbon.
26804*/
26805float position[ 4 ];
26806/*!
26807@brief The amount of segments the Ribbon can maximally have in length.
26808*/
26809int ribbonLength;
26810/*!
26811@brief How many segments to add each update.
26812*/
26813int segmentsPerUpdate;
26814/*!
26815@brief The amount of segments to skip each update.
26816*/
26817int skipAmount;
26818/*!
26819@brief If true, the ribbon will fade away after deletion.
26820*/
26821bool useFadeOut;
26822/*!
26823@brief How much to fade the ribbon with each update, after deletion.
26824*/
26825float fadeAwayStep;
26826/*!
26827@brief The material the ribbon uses for rendering.
26828*/
26829string ribbonMaterial;
26830/*!
26831@brief How much to scale each 'tile' with, where 1 means the material is stretchedacross the whole ribbon. (If TexcoordsRelativeToDistance is true, this is in meters.)
26832*/
26833float tileScale;
26834/*!
26835@brief If true, this prevents 'floating' texture coordinates.
26836*/
26837bool fixedTexcoords;
26838/*!
26839@brief If true, texture coordinates are scaled relative to distance, this prevents'stretched' textures.
26840*/
26841bool texcoordsRelativeToDistance;
26842/// @}
26843
26844};
26845
26846/*! UNDOCUMENTED!
26847@ingroup UNDOCUMENTED
26848 */
26849class Ribbon : public GameBase {
26850public:
26851
26852/*! @name Callbacks
26853@{ */
26854/// @}
26855
26856/*!
26857@brief Disables rendering of all instances of this type.
26858
26859
26860@ingroup UNDOCUMENTED
26861*/
26862static bool isRenderable;
26863/*!
26864@brief Disables selection of all instances of this type.
26865
26866
26867@ingroup UNDOCUMENTED
26868*/
26869static bool isSelectable;
26870
26871/*! @name Game
26872@{ */
26873/// @}
26874
26875
26876/*! @name GameObject
26877@{ */
26878/// @}
26879
26880
26881/*! @name Transform
26882@{ */
26883/// @}
26884
26885
26886/*! @name Editing
26887@{ */
26888/// @}
26889
26890
26891/*! @name Mounting
26892@{ */
26893/// @}
26894
26895
26896/*! @name Ungrouped
26897@{ */
26898/// @}
26899
26900
26901/*! @name Object
26902@{ */
26903/// @}
26904
26905
26906/*! @name Editing
26907@{ */
26908/// @}
26909
26910
26911/*! @name Persistence
26912@{ */
26913/// @}
26914
26915};
26916
26917/*!
26918@brief Contains additional data to be associated with a RibbonNode.@ingroup FX
26919
26920*/
26921class RibbonNodeData : public GameBaseData {
26922public:
26923
26924/*! @name Callbacks
26925@{ */
26926/// @}
26927
26928
26929/*! @name Scripting
26930@{ */
26931/// @}
26932
26933
26934/*! @name Ungrouped
26935@{ */
26936/// @}
26937
26938
26939/*! @name Object
26940@{ */
26941/// @}
26942
26943
26944/*! @name Editing
26945@{ */
26946/// @}
26947
26948
26949/*! @name Persistence
26950@{ */
26951/// @}
26952
26953};
26954
26955/*!
26956@brief Acts as the physical point in space in white a Splash is created from.
26957@ingroup FX
26958
26959*/
26960class SplashData : public GameBaseData {
26961public:
26962
26963/*! @name Callbacks
26964@{ */
26965/// @}
26966
26967/*!
26968@brief SFXProfile effect to play.
26969
26970
26971*/
26972SFXProfile soundProfile;
26973/*!
26974@brief The scale of this splashing effect, defined as the F32 points X, Y, Z.
26975
26976
26977*/
26978Point3F scale;
26979/*!
26980@brief List of particle emitters to create at the point of this Splash effect.
26981
26982
26983*/
26984ParticleEmitterData emitter[ 3 ];
26985/*!
26986@brief Time to delay, in milliseconds, before actually starting this effect.
26987
26988
26989*/
26990int delayMS;
26991/*!
26992@brief Time variance for delayMS.
26993
26994
26995*/
26996int delayVariance;
26997/*!
26998@brief Lifetime for this effect, in milliseconds.
26999
27000
27001*/
27002int lifetimeMS;
27003/*!
27004@brief Time variance for lifetimeMS.
27005
27006
27007*/
27008int lifetimeVariance;
27009/*!
27010@brief Width for the X and Y coordinates to create this effect within.
27011*/
27012float width;
27013/*!
27014@brief Number of ejection points in the splash ring.
27015
27016
27017*/
27018int numSegments;
27019/*!
27020@brief Velocity for the splash effect to travel.
27021
27022
27023*/
27024float velocity;
27025/*!
27026@brief Height for the splash to reach.
27027
27028
27029*/
27030float height;
27031/*!
27032@brief Constant acceleration value to place upon the splash effect.
27033
27034
27035*/
27036float acceleration;
27037/*!
27038@brief Times to transition through the splash effect. Up to 4 allowed. Values are 0.0 - 1.0, and corrispond to the life of the particle where 0 is first created and 1 is end of lifespace.
27039
27040
27041*/
27042float times[ 4 ];
27043/*!
27044@brief Color values to set the splash effect, rgba. Up to 4 allowed. Will transition through colors based on values set in the times value. Example: colors[0] = "0.6 1.0 1.0 0.5".
27045
27046
27047*/
27048LinearColorF colors[ 4 ];
27049/*!
27050@brief Imagemap file to use as the texture for the splash effect.
27051
27052
27053*/
27054filename texture[ 2 ];
27055/*!
27056@brief Amount to wrap the texture around the splash ring, 0.0f - 1.0f.
27057
27058
27059*/
27060float texWrap;
27061/*!
27062@brief Factor in which to apply the texture to the splash ring, 0.0f - 1.0f.
27063
27064
27065*/
27066float texFactor;
27067/*!
27068@brief Frequency in which to emit splash rings.
27069
27070
27071*/
27072float ejectionFreq;
27073/*!
27074@brief Rotational angle to create a splash ring.
27075
27076
27077*/
27078float ejectionAngle;
27079/*!
27080@brief Lifetime, in milliseconds, for a splash ring.
27081
27082
27083*/
27084float ringLifetime;
27085/*!
27086@brief Starting radius size of a splash ring.
27087
27088
27089*/
27090float startRadius;
27091/*!
27092@brief ExplosionData object to create at the creation position of this splash effect.
27093
27094
27095*/
27096ExplosionData Explosion;
27097
27098/*! @name Scripting
27099@{ */
27100/// @}
27101
27102
27103/*! @name Ungrouped
27104@{ */
27105/// @}
27106
27107
27108/*! @name Object
27109@{ */
27110/// @}
27111
27112
27113/*! @name Editing
27114@{ */
27115/// @}
27116
27117
27118/*! @name Persistence
27119@{ */
27120/// @}
27121
27122};
27123
27124/*!
27125@brief Manages the ring used for a Splash effect.
27126@ingroup FX
27127
27128*/
27129class Splash : public GameBase {
27130public:
27131
27132/*! @name Callbacks
27133@{ */
27134/// @}
27135
27136/*!
27137@brief Disables rendering of all instances of this type.
27138
27139
27140@ingroup UNDOCUMENTED
27141*/
27142static bool isRenderable;
27143/*!
27144@brief Disables selection of all instances of this type.
27145
27146
27147@ingroup UNDOCUMENTED
27148*/
27149static bool isSelectable;
27150
27151/*! @name Game
27152@{ */
27153/// @}
27154
27155
27156/*! @name GameObject
27157@{ */
27158/// @}
27159
27160
27161/*! @name Transform
27162@{ */
27163/// @}
27164
27165
27166/*! @name Editing
27167@{ */
27168/// @}
27169
27170
27171/*! @name Mounting
27172@{ */
27173/// @}
27174
27175
27176/*! @name Ungrouped
27177@{ */
27178/// @}
27179
27180
27181/*! @name Object
27182@{ */
27183/// @}
27184
27185
27186/*! @name Editing
27187@{ */
27188/// @}
27189
27190
27191/*! @name Persistence
27192@{ */
27193/// @}
27194
27195};
27196
27197/*!
27198@brief Defines the physics properties for an individual RigidShapeData physics object.
27199
27200@tsexample
27201   datablock RigidShapeData( BouncingBoulder )
27202   {
27203      category = "RigidShape";
27204
27205      shapeFile = "~/data/shapes/boulder/boulder.dts";
27206      emap = true;
27207
27208      // Rigid Body
27209      mass = 500;
27210      massCenter = "0 0 0";    // Center of mass for rigid body
27211      massBox = "0 0 0";         // Size of box used for moment of inertia,
27212                          // if zero it defaults to object bounding box
27213      drag = 0.2;                // Drag coefficient
27214      bodyFriction = 0.2;
27215      bodyRestitution = 0.1;
27216      minImpactSpeed = 5;        // Impacts over this invoke the script callback
27217      softImpactSpeed = 5;       // Play SoftImpact Sound
27218      hardImpactSpeed = 15;      // Play HardImpact Sound
27219      integration = 4;           // Physics integration: TickSec/Rate
27220      collisionTol = 0.1;        // Collision distance tolerance
27221      contactTol = 0.1;          // Contact velocity tolerance
27222
27223      minRollSpeed = 10;
27224
27225      maxDrag = 0.5;
27226      minDrag = 0.01;
27227
27228      dustHeight = 10;
27229
27230      dragForce = 0.05;
27231      vertFactor = 0.05;
27232   };
27233@endtsexample
27234
27235@see RigidShape
27236@see ShapeBase
27237
27238@ingroup Physics
27239
27240*/
27241class RigidShapeData : public ShapeBaseData {
27242public:
27243
27244/*! @name Callbacks
27245@{ */
27246/*!
27247@brief Called when the vehicle enters liquid.
27248
27249@param obj the Vehicle object
27250@param coverage percentage of the vehicle's bounding box covered by the liquid
27251@param type type of liquid the vehicle has entered
27252*/
27253void onEnterLiquid( RigidShape obj, float coverage, string type );
27254/*!
27255@brief Called when the vehicle leaves liquid.
27256
27257@param obj the Vehicle object
27258@param type type of liquid the vehicle has left
27259*/
27260void onLeaveLiquid( RigidShape obj, string type );
27261/// @}
27262
27263
27264/*! @name Physics
27265@{ */
27266/*!
27267@brief @brief Creates a representation of the object in the physics plugin.
27268
27269
27270*/
27271bool enablePhysicsRep;
27272/// @}
27273
27274/*!
27275@brief Center of mass for rigid body.
27276*/
27277Point3F massCenter;
27278/*!
27279@brief Size of inertial box.
27280*/
27281Point3F massBox;
27282/*!
27283@brief The percentage of kinetic energy kept by this object in a collision.
27284*/
27285float bodyRestitution;
27286/*!
27287@brief How much friction this object has. Lower values will cause the object to appear to be more slippery.
27288*/
27289float bodyFriction;
27290/*!
27291@brief Minimum collision speed to classify collision as impact (triggers onImpact on server object).
27292*/
27293float minImpactSpeed;
27294/*!
27295@brief Minimum speed at which this object must be travelling for the soft impact sound to be played.
27296*/
27297float softImpactSpeed;
27298/*!
27299@brief Minimum speed at which the object must be travelling for the hard impact sound to be played.
27300*/
27301float hardImpactSpeed;
27302/*!
27303*/
27304float minRollSpeed;
27305/*!
27306@brief Maximum drag available to this object.
27307*/
27308float maxDrag;
27309/*!
27310@brief Minimum drag available to this object.
27311*/
27312float minDrag;
27313/*!
27314@brief Number of physics steps to process per tick.
27315*/
27316int integration;
27317/*!
27318@brief Collision distance tolerance.
27319*/
27320float collisionTol;
27321/*!
27322@brief Contact velocity tolerance.
27323*/
27324float contactTol;
27325
27326/*! @name Forces
27327@{ */
27328/*!
27329@brief Used to simulate the constant drag acting on the object
27330*/
27331float dragForce;
27332/*!
27333@brief The scalar applied to the vertical portion of the velocity drag acting on a object.
27334*/
27335float vertFactor;
27336/// @}
27337
27338
27339/*! @name Particle Effects
27340@{ */
27341/*!
27342@brief Array of pointers to ParticleEmitterData datablocks which will be used to emit particles at object/terrain contact point.
27343
27344
27345*/
27346ParticleEmitterData dustEmitter;
27347/*!
27348@brief Maximum height from the ground at which the object will generate dust.
27349
27350
27351*/
27352float triggerDustHeight;
27353/*!
27354@brief Height of dust effects.
27355
27356
27357*/
27358float dustHeight;
27359/*!
27360@brief Particle emitter used to create a dust trail for the moving object.
27361
27362
27363*/
27364ParticleEmitterData dustTrailEmitter;
27365/*!
27366@brief Array of pointers to ParticleEmitterData datablocks which will generate splash effects.
27367
27368
27369*/
27370ParticleEmitterData splashEmitter[ 2 ];
27371/*!
27372@brief The simulated frequency modulation of a splash generated by this object. Multiplied along with speed and time elapsed when determining splash emition rate.
27373
27374
27375*/
27376float splashFreqMod;
27377/*!
27378@brief The threshold speed at which we consider the object's movement to have stopped when updating splash effects.
27379
27380
27381*/
27382float splashVelEpsilon;
27383/// @}
27384
27385
27386/*! @name Sounds
27387@{ */
27388/*!
27389@brief Sound to play when body impacts with at least softImageSpeed but less than hardImpactSpeed.
27390*/
27391SFXTrack softImpactSound;
27392/*!
27393@brief Sound to play when body impacts with at least hardImpactSpeed.
27394*/
27395SFXTrack hardImpactSound;
27396/*!
27397@brief The minimum velocity at which the exit splash sound will be played when emerging from water.
27398
27399
27400*/
27401float exitSplashSoundVelocity;
27402/*!
27403@brief The minimum velocity at which the soft splash sound will be played when impacting water.
27404
27405
27406*/
27407float softSplashSoundVelocity;
27408/*!
27409@brief The minimum velocity at which the medium splash sound will be played when impacting water.
27410
27411
27412*/
27413float mediumSplashSoundVelocity;
27414/*!
27415@brief The minimum velocity at which the hard splash sound will be played when impacting water.
27416
27417
27418*/
27419float hardSplashSoundVelocity;
27420/*!
27421@brief The AudioProfile will be used to produce sounds when emerging from water.
27422
27423
27424*/
27425SFXTrack exitingWater;
27426/*!
27427@brief The AudioProfile will be used to produce sounds when a soft impact with water occurs.
27428
27429
27430*/
27431SFXTrack impactWaterEasy;
27432/*!
27433@brief The AudioProfile will be used to produce sounds when a medium impact with water occurs.
27434
27435
27436*/
27437SFXTrack impactWaterMedium;
27438/*!
27439@brief The AudioProfile will be used to produce sounds when a hard impact with water occurs.
27440
27441
27442*/
27443SFXTrack impactWaterHard;
27444/*!
27445@brief The AudioProfile will be used to produce sounds when a water wake is displayed.
27446
27447
27448*/
27449SFXTrack waterWakeSound;
27450/// @}
27451
27452
27453/*! @name Camera
27454@{ */
27455/*!
27456@brief Specifies whether the camera's rotation matrix, and the render eye transform are multiplied during camera updates.
27457
27458
27459*/
27460bool cameraRoll;
27461/*!
27462@brief Scalar amount by which the third person camera lags the object, relative to the object's linear velocity.
27463
27464
27465*/
27466float cameraLag;
27467/*!
27468@brief Scalar rate at which the third person camera offset decays, per tick.
27469
27470
27471*/
27472float cameraDecay;
27473/*!
27474@brief The vertical offset of the object's camera.
27475
27476
27477*/
27478float cameraOffset;
27479/// @}
27480
27481
27482/*! @name Shadows
27483@{ */
27484/// @}
27485
27486
27487/*! @name Render
27488@{ */
27489/// @}
27490
27491
27492/*! @name Destruction
27493Parameters related to the destruction effects of this object.
27494@{ */
27495/// @}
27496
27497
27498/*! @name Physics
27499@{ */
27500/// @}
27501
27502
27503/*! @name Damage/Energy
27504@{ */
27505/// @}
27506
27507
27508/*! @name Camera
27509The settings used by the shape when it is the camera.
27510@{ */
27511/// @}
27512
27513
27514/*! @name Misc
27515@{ */
27516/// @}
27517
27518
27519/*! @name Reflection
27520@{ */
27521/// @}
27522
27523
27524/*! @name Scripting
27525@{ */
27526/// @}
27527
27528
27529/*! @name Ungrouped
27530@{ */
27531/// @}
27532
27533
27534/*! @name Object
27535@{ */
27536/// @}
27537
27538
27539/*! @name Editing
27540@{ */
27541/// @}
27542
27543
27544/*! @name Persistence
27545@{ */
27546/// @}
27547
27548};
27549
27550/*!
27551@brief Base properties shared by all Vehicles (FlyingVehicle, HoverVehicle, WheeledVehicle).
27552
27553This datablock defines properties shared by all Vehicle types, but should not be instantiated directly. Instead, set the desired properties in the FlyingVehicleData, HoverVehicleData or WheeledVehicleData datablock.
27554@section VehicleData_damage Damage
27555
27556The VehicleData class extends the basic energy/damage functionality provided by ShapeBaseData to include damage from collisions, as well as particle emitters activated automatically when damage levels reach user specified thresholds.
27557
27558The example below shows how to setup a Vehicle to:
27559<ul>
27560  <li>take damage when colliding with another object
27561  <li>emit gray smoke particles from two locations on the Vehicle when damaged above 50%</li>
27562  <li>emit black smoke particles from two locations on the Vehicle when damaged above 85%</li>
27563  <li>emit bubbles when any active damage emitter point is underwater</li>
27564</ul>
27565
27566@tsexample
27567// damage from collisions
27568collDamageMultiplier = 0.05;
27569collDamageThresholdVel = 15;
27570
27571// damage levels
27572damageLevelTolerance[0] = 0.5;
27573damageEmitter[0] = GraySmokeEmitter;     // emitter used when damage is >= 50%
27574damageLevelTolerance[1] = 0.85;
27575damageEmitter[1] = BlackSmokeEmitter;    // emitter used when damage is >= 85%
27576damageEmitter[2] = DamageBubbleEmitter;  // emitter used instead of damageEmitter[0:1]
27577                                         // when offset point is underwater
27578// emit offsets (used for all active damage level emitters)
27579damageEmitterOffset[0] = "0.5 3 1";
27580damageEmitterOffset[1] = "-0.5 3 1";
27581numDmgEmitterAreas = 2;
27582@endtsexample
27583@ingroup Vehicles
27584
27585*/
27586class VehicleData : public RigidShapeData {
27587public:
27588
27589/*! @name Callbacks
27590@{ */
27591/// @}
27592
27593
27594/*! @name Physics
27595@{ */
27596/// @}
27597
27598/*!
27599@brief @brief Additional force applied to the vehicle when it is jetting.
27600
27601
27602For WheeledVehicles, the force is applied in the forward direction. For FlyingVehicles, the force is applied in the thrust direction.
27603*/
27604float jetForce;
27605/*!
27606@brief @brief Energy amount to drain for each tick the vehicle is jetting.
27607
27608
27609Once the vehicle's energy level reaches 0, it will no longer be able to jet.
27610*/
27611float jetEnergyDrain;
27612/*!
27613@brief Minimum vehicle energy level to begin jetting.
27614*/
27615float minJetEnergy;
27616/*!
27617@brief Rate at which the vehicle's steering returns to forwards when it is moving.
27618*/
27619float steeringReturn;
27620/*!
27621@brief Amount of effect the vehicle's speed has on its rate of steering return.
27622*/
27623float steeringReturnSpeedScale;
27624/*!
27625@brief If true, steering does not auto-centre while the vehicle is being steered by its driver.
27626*/
27627bool powerSteering;
27628/*!
27629@brief Maximum yaw (horizontal) and pitch (vertical) steering angle in radians.
27630*/
27631float maxSteeringAngle;
27632/*!
27633@brief @brief Array of particle emitters used to generate damage (dust, smoke etc) effects.
27634
27635
27636Currently, the first two emitters (indices 0 and 1) are used when the damage level exceeds the associated damageLevelTolerance. The 3rd emitter is used when the emitter point is underwater.
27637
27638@see damageEmitterOffset
27639*/
27640ParticleEmitterData damageEmitter[ 3 ];
27641/*!
27642@brief @brief Object space "x y z" offsets used to emit particles for the active damageEmitter.
27643
27644
27645@tsexample
27646// damage levels
27647damageLevelTolerance[0] = 0.5;
27648damageEmitter[0] = SmokeEmitter;
27649// emit offsets (used for all active damage level emitters)
27650damageEmitterOffset[0] = "0.5 3 1";
27651damageEmitterOffset[1] = "-0.5 3 1";
27652numDmgEmitterAreas = 2;
27653@endtsexample
27654
27655*/
27656Point3F damageEmitterOffset[ 2 ];
27657/*!
27658@brief @brief Damage levels (as a percentage of maxDamage) above which to begin emitting particles from the associated damageEmitter.
27659
27660
27661Levels should be in order of increasing damage.
27662
27663@see damageEmitterOffset
27664*/
27665float damageLevelTolerance[ 2 ];
27666/*!
27667@brief Number of damageEmitterOffset values to use for each damageEmitter.
27668
27669
27670@see damageEmitterOffset
27671*/
27672float numDmgEmitterAreas;
27673/*!
27674@brief Minimum collision velocity to cause damage to this vehicle.
27675
27676Currently unused.
27677*/
27678float collDamageThresholdVel;
27679/*!
27680@brief @brief Damage to this vehicle after a collision (multiplied by collision velocity).
27681
27682
27683Currently unused.
27684*/
27685float collDamageMultiplier;
27686
27687/*! @name Physics
27688@{ */
27689/// @}
27690
27691
27692/*! @name Forces
27693@{ */
27694/// @}
27695
27696
27697/*! @name Particle Effects
27698@{ */
27699/// @}
27700
27701
27702/*! @name Sounds
27703@{ */
27704/// @}
27705
27706
27707/*! @name Camera
27708@{ */
27709/// @}
27710
27711
27712/*! @name Shadows
27713@{ */
27714/// @}
27715
27716
27717/*! @name Render
27718@{ */
27719/// @}
27720
27721
27722/*! @name Destruction
27723Parameters related to the destruction effects of this object.
27724@{ */
27725/// @}
27726
27727
27728/*! @name Physics
27729@{ */
27730/// @}
27731
27732
27733/*! @name Damage/Energy
27734@{ */
27735/// @}
27736
27737
27738/*! @name Camera
27739The settings used by the shape when it is the camera.
27740@{ */
27741/// @}
27742
27743
27744/*! @name Misc
27745@{ */
27746/// @}
27747
27748
27749/*! @name Reflection
27750@{ */
27751/// @}
27752
27753
27754/*! @name Scripting
27755@{ */
27756/// @}
27757
27758
27759/*! @name Ungrouped
27760@{ */
27761/// @}
27762
27763
27764/*! @name Object
27765@{ */
27766/// @}
27767
27768
27769/*! @name Editing
27770@{ */
27771/// @}
27772
27773
27774/*! @name Persistence
27775@{ */
27776/// @}
27777
27778};
27779
27780/*!
27781@brief Defines the properties of a FlyingVehicle.
27782
27783@ingroup Vehicles
27784
27785*/
27786class FlyingVehicleData : public VehicleData {
27787public:
27788
27789/*! @name Callbacks
27790@{ */
27791/// @}
27792
27793/*!
27794@brief Looping sound to play while the vehicle is jetting.
27795*/
27796SFXProfile jetSound;
27797/*!
27798@brief Looping engine sound.
27799*/
27800SFXProfile engineSound;
27801/*!
27802@brief @brief Maximum X and Y (horizontal plane) maneuvering force.
27803
27804
27805The actual force applied depends on the current thrust.
27806*/
27807float maneuveringForce;
27808/*!
27809@brief @brief Damping force in the opposite direction to sideways velocity.
27810
27811
27812Provides "bite" into the wind for climbing/diving and turning).
27813*/
27814float horizontalSurfaceForce;
27815/*!
27816@brief @brief Damping force in the opposite direction to vertical velocity.
27817
27818
27819Controls side slip; lower numbers give more slide.
27820*/
27821float verticalSurfaceForce;
27822/*!
27823@brief Multiplier applied to the jetForce (defined in VehicleData) when thrusting vertically.
27824*/
27825float vertThrustMultiple;
27826/*!
27827@brief @brief Maximum X and Z (sideways and vertical) steering force.
27828
27829
27830The actual force applied depends on the current steering input.
27831*/
27832float steeringForce;
27833/*!
27834@brief Roll force induced by sideways steering input value (controls how much the vehicle rolls when turning).
27835*/
27836float steeringRollForce;
27837/*!
27838@brief @brief Damping torque against rolling maneuvers (rotation about the y-axis), proportional to linear velocity.
27839
27840
27841Acts to adjust roll to a stable position over time as the vehicle moves.
27842*/
27843float rollForce;
27844/*!
27845@brief Rotational drag factor (slows vehicle rotation speed in all axes).
27846*/
27847float rotationalDrag;
27848/*!
27849@brief Maximum speed for automatic vehicle control assistance - vehicles travelling at speeds above this value do not get control assitance.
27850*/
27851float maxAutoSpeed;
27852/*!
27853@brief @brief Scale factor applied to steering input if speed is less than maxAutoSpeed to.improve handling at very low speeds.
27854
27855
27856Smaller values make steering less sensitive.
27857*/
27858float autoInputDamping;
27859/*!
27860@brief @brief Corrective force applied to slow the vehicle when moving at less than maxAutoSpeed.
27861
27862
27863The force is inversely proportional to vehicle speed.
27864*/
27865float autoLinearForce;
27866/*!
27867@brief @brief Corrective torque applied to level out the vehicle when moving at less than maxAutoSpeed.
27868
27869
27870The torque is inversely proportional to vehicle speed.
27871*/
27872float autoAngularForce;
27873/*!
27874@brief The vehicle's height off the ground when at rest.
27875*/
27876float hoverHeight;
27877/*!
27878@brief @brief The vehicle's height off the ground when useCreateHeight is active.
27879
27880
27881This can help avoid problems with spawning the vehicle.
27882*/
27883float createHoverHeight;
27884/*!
27885@brief @brief Emitter to generate particles for forward jet thrust.
27886
27887
27888Forward jet thrust particles are emitted from model nodes JetNozzle0 and JetNozzle1.
27889*/
27890ParticleEmitterData forwardJetEmitter;
27891/*!
27892@brief @brief Emitter to generate particles for backward jet thrust.
27893
27894
27895Backward jet thrust particles are emitted from model nodes JetNozzleX and JetNozzleY.
27896*/
27897ParticleEmitterData backwardJetEmitter;
27898/*!
27899@brief @brief Emitter to generate particles for downward jet thrust.
27900
27901
27902Downward jet thrust particles are emitted from model nodes JetNozzle2 and JetNozzle3.
27903*/
27904ParticleEmitterData downJetEmitter;
27905/*!
27906@brief Emitter to generate contrail particles from model nodes contrail0 - contrail3.
27907*/
27908ParticleEmitterData trailEmitter;
27909/*!
27910@brief Minimum speed at which to start generating contrail particles.
27911*/
27912float minTrailSpeed;
27913
27914/*! @name Physics
27915@{ */
27916/// @}
27917
27918
27919/*! @name Physics
27920@{ */
27921/// @}
27922
27923
27924/*! @name Forces
27925@{ */
27926/// @}
27927
27928
27929/*! @name Particle Effects
27930@{ */
27931/// @}
27932
27933
27934/*! @name Sounds
27935@{ */
27936/// @}
27937
27938
27939/*! @name Camera
27940@{ */
27941/// @}
27942
27943
27944/*! @name Shadows
27945@{ */
27946/// @}
27947
27948
27949/*! @name Render
27950@{ */
27951/// @}
27952
27953
27954/*! @name Destruction
27955Parameters related to the destruction effects of this object.
27956@{ */
27957/// @}
27958
27959
27960/*! @name Physics
27961@{ */
27962/// @}
27963
27964
27965/*! @name Damage/Energy
27966@{ */
27967/// @}
27968
27969
27970/*! @name Camera
27971The settings used by the shape when it is the camera.
27972@{ */
27973/// @}
27974
27975
27976/*! @name Misc
27977@{ */
27978/// @}
27979
27980
27981/*! @name Reflection
27982@{ */
27983/// @}
27984
27985
27986/*! @name Scripting
27987@{ */
27988/// @}
27989
27990
27991/*! @name Ungrouped
27992@{ */
27993/// @}
27994
27995
27996/*! @name Object
27997@{ */
27998/// @}
27999
28000
28001/*! @name Editing
28002@{ */
28003/// @}
28004
28005
28006/*! @name Persistence
28007@{ */
28008/// @}
28009
28010};
28011
28012/*!
28013@brief Displays the speed of the current Vehicle based control object.
28014
28015This control only works if a server connection exists, and its control object is a Vehicle derived class. If either of these requirements is false, the control is not rendered.<br>The control renders the speedometer needle as a colored quad, rotated to indicate the Vehicle speed as determined by the <i>minAngle</i>, <i>maxAngle</i>, and <i>maxSpeed</i> properties. This control is normally placed on top of a GuiBitmapCtrl representing the speedometer dial.
28016
28017@tsexample
28018new GuiSpeedometerHud()
28019{
28020   maxSpeed = "100";
28021   minAngle = "215";
28022   maxAngle = "0";
28023   color = "1 0.3 0.3 1";
28024   center = "130 123";
28025   length = "100";
28026   width = "2";
28027   tail = "0";
28028   //Properties not specific to this control have been omitted from this example.
28029};
28030@endtsexample
28031
28032@ingroup GuiContainers
28033*/
28034class GuiSpeedometerHud : public GuiBitmapCtrl {
28035public:
28036
28037/*! @name Callbacks
28038@{ */
28039/// @}
28040
28041
28042/*! @name Needle
28043@{ */
28044/*!
28045@brief Maximum Vehicle speed (in Torque units per second) to represent on the speedo (Vehicle speeds greater than this are clamped to maxSpeed).
28046*/
28047float maxSpeed;
28048/*!
28049@brief Angle (in radians) of the needle when the Vehicle speed is 0. An angle of 0 points right, 90 points up etc).
28050*/
28051float minAngle;
28052/*!
28053@brief Angle (in radians) of the needle when the Vehicle speed is >= maxSpeed. An angle of 0 points right, 90 points up etc).
28054*/
28055float maxAngle;
28056/*!
28057@brief Center of the needle, offset from the GuiSpeedometerHud control top left corner
28058*/
28059Point2F center;
28060/*!
28061@brief Length of the needle from center to end
28062*/
28063float length;
28064/*!
28065@brief Width of the needle
28066*/
28067float width;
28068/*!
28069@brief Length of the needle from center to tail
28070*/
28071float tail;
28072/// @}
28073
28074
28075/*! @name Bitmap
28076@{ */
28077/// @}
28078
28079
28080/*! @name Layout
28081@{ */
28082/// @}
28083
28084
28085/*! @name Control
28086@{ */
28087/// @}
28088
28089
28090/*! @name ToolTip
28091@{ */
28092/// @}
28093
28094
28095/*! @name Editing
28096@{ */
28097/// @}
28098
28099
28100/*! @name Localization
28101@{ */
28102/// @}
28103
28104
28105/*! @name Ungrouped
28106@{ */
28107/// @}
28108
28109
28110/*! @name Object
28111@{ */
28112/// @}
28113
28114
28115/*! @name Editing
28116@{ */
28117/// @}
28118
28119
28120/*! @name Persistence
28121@{ */
28122/// @}
28123
28124};
28125
28126/*!
28127@brief Defines the properties of a HoverVehicle.
28128
28129@ingroup Vehicles
28130
28131*/
28132class HoverVehicleData : public VehicleData {
28133public:
28134
28135/*! @name Callbacks
28136@{ */
28137/// @}
28138
28139/*!
28140@brief Scalar applied to the vehicle's thrust force when the vehicle is floating.
28141
28142@note The floatingThrustFactor must be between 0.0 and 1.0 (inclusive).
28143*/
28144float floatingThrustFactor;
28145/*!
28146@brief Force generated by thrusting the vehicle forward.
28147
28148Also used to determine the maxThrustSpeed:
28149
28150@tsexample
28151maxThrustSpeed = (mainThrustForce + strafeThrustForce) / dragForce;
28152@endtsexample
28153
28154*/
28155float mainThrustForce;
28156/*!
28157@brief Force generated by thrusting the vehicle backward.
28158*/
28159float reverseThrustForce;
28160/*!
28161@brief Force generated by thrusting the vehicle to one side.
28162
28163Also used to determine the vehicle's maxThrustSpeed.
28164@see mainThrustForce
28165*/
28166float strafeThrustForce;
28167/*!
28168@brief Scale factor applied to the vehicle's thrust force when jetting.
28169*/
28170float turboFactor;
28171/*!
28172@brief Length of the base stabalizer when travelling at minimum speed (0).
28173
28174Each tick, the vehicle performs 2 raycasts (from the center back and center front of the vehicle) to check for contact with the ground. The base stabalizer length determines the length of that raycast; if neither raycast hit the ground, the vehicle is floating, stabalizer spring and ground normal forces are not applied.
28175
28176<img src="images/hoverVehicle_forces.png">
28177@see stabSpringConstant
28178*/
28179float stabLenMin;
28180/*!
28181@brief Length of the base stabalizer when travelling at maximum speed (maxThrustSpeed).
28182
28183
28184@see stabLenMin
28185
28186@see mainThrustForce
28187*/
28188float stabLenMax;
28189/*!
28190@brief Value used to generate stabalizer spring force. The force generated depends on stabilizer compression, that is how close the vehicle is to the ground proportional to current stabalizer length.
28191
28192
28193@see stabLenMin
28194*/
28195float stabSpringConstant;
28196/*!
28197@brief Damping spring force acting against changes in the stabalizer length.
28198
28199
28200@see stabLenMin
28201*/
28202float stabDampingConstant;
28203/*!
28204@brief Damping torque that acts against the vehicle's current angular momentum.
28205*/
28206float gyroDrag;
28207/*!
28208@brief Force generated in the ground normal direction when the vehicle is not floating (within stabalizer length from the ground).
28209
28210
28211@see stabLenMin
28212*/
28213float normalForce;
28214/*!
28215@brief Force generated to stabalize the vehicle (return it to neutral pitch/roll) when the vehicle is floating (more than stabalizer length from the ground.
28216
28217
28218@see stabLenMin
28219*/
28220float restorativeForce;
28221/*!
28222@brief Yaw (rotation about the Z-axis) force applied when steering in the x-axis direction.about the vehicle's Z-axis)
28223*/
28224float steeringForce;
28225/*!
28226@brief Roll (rotation about the Y-axis) force applied when steering in the x-axis direction.
28227*/
28228float rollForce;
28229/*!
28230@brief Pitch (rotation about the X-axis) force applied when steering in the y-axis direction.
28231*/
28232float pitchForce;
28233/*!
28234@brief Looping sound played when the vehicle is jetting.
28235*/
28236SFXProfile jetSound;
28237/*!
28238@brief Looping engine sound.
28239
28240The volume is dynamically adjusted based on the current thrust level.
28241*/
28242SFXProfile engineSound;
28243/*!
28244@brief Looping sound played while the vehicle is floating.
28245
28246
28247@see stabMinLen
28248*/
28249SFXProfile floatSound;
28250/*!
28251@brief "X Y Z" offset from the vehicle's origin from which to generate dust trail particles.
28252
28253By default particles are emitted directly beneath the origin of the vehicle model.
28254*/
28255Point3F dustTrailOffset;
28256/*!
28257@brief Maximum height above surface to emit dust trail particles.
28258
28259If the vehicle is less than triggerTrailHeight above a static surface with a material that has 'showDust' set to true, the vehicle will emit particles from the dustTrailEmitter.
28260*/
28261float triggerTrailHeight;
28262/*!
28263@brief Number of dust trail particles to generate based on vehicle speed.
28264
28265The vehicle's speed is divided by this value to determine how many particles to generate each frame. Lower values give a more dense trail, higher values a more sparse trail.
28266*/
28267float dustTrailFreqMod;
28268/*!
28269@brief Scale factor applied to the vehicle gravitational force when the vehicle is floating.
28270
28271
28272@see stabLenMin
28273*/
28274float floatingGravMag;
28275/*!
28276@brief Force generated by braking.
28277
28278The vehicle is considered to be braking if it is moving, but the throttle is off, and no left or right thrust is being applied. This force is only applied when the vehicle's velocity is less than brakingActivationSpeed.
28279*/
28280float brakingForce;
28281/*!
28282@brief Maximum speed below which a braking force is applied.
28283
28284
28285@see brakingForce
28286*/
28287float brakingActivationSpeed;
28288/*!
28289@brief Emitter to generate particles for forward jet thrust.
28290
28291Forward jet thrust particles are emitted from model nodes JetNozzle0 and JetNozzle1.
28292*/
28293ParticleEmitterData forwardJetEmitter;
28294
28295/*! @name Physics
28296@{ */
28297/// @}
28298
28299
28300/*! @name Physics
28301@{ */
28302/// @}
28303
28304
28305/*! @name Forces
28306@{ */
28307/// @}
28308
28309
28310/*! @name Particle Effects
28311@{ */
28312/// @}
28313
28314
28315/*! @name Sounds
28316@{ */
28317/// @}
28318
28319
28320/*! @name Camera
28321@{ */
28322/// @}
28323
28324
28325/*! @name Shadows
28326@{ */
28327/// @}
28328
28329
28330/*! @name Render
28331@{ */
28332/// @}
28333
28334
28335/*! @name Destruction
28336Parameters related to the destruction effects of this object.
28337@{ */
28338/// @}
28339
28340
28341/*! @name Physics
28342@{ */
28343/// @}
28344
28345
28346/*! @name Damage/Energy
28347@{ */
28348/// @}
28349
28350
28351/*! @name Camera
28352The settings used by the shape when it is the camera.
28353@{ */
28354/// @}
28355
28356
28357/*! @name Misc
28358@{ */
28359/// @}
28360
28361
28362/*! @name Reflection
28363@{ */
28364/// @}
28365
28366
28367/*! @name Scripting
28368@{ */
28369/// @}
28370
28371
28372/*! @name Ungrouped
28373@{ */
28374/// @}
28375
28376
28377/*! @name Object
28378@{ */
28379/// @}
28380
28381
28382/*! @name Editing
28383@{ */
28384/// @}
28385
28386
28387/*! @name Persistence
28388@{ */
28389/// @}
28390
28391};
28392
28393/*!
28394@brief The RigidShape class implements rigid-body physics for DTS objects in the world.
28395
28396"Rigid body physics" refers to a system whereby objects are assumed to have a finite size,
28397equally distributed masses, and where deformations of the objects themselves are not accounted for.
28398Uses the RigidShape class to control its physics.
28399
28400@tsexample
28401   datablock RigidShapeData( BouncingBoulder )
28402   {
28403      category = "RigidShape";
28404
28405      shapeFile = "~/data/shapes/boulder/boulder.dts";
28406      emap = true;
28407
28408      // Rigid Body
28409      mass = 500;
28410      massCenter = "0 0 0";    // Center of mass for rigid body
28411      massBox = "0 0 0";         // Size of box used for moment of inertia,
28412                          // if zero it defaults to object bounding box
28413      drag = 0.2;                // Drag coefficient
28414      bodyFriction = 0.2;
28415      bodyRestitution = 0.1;
28416      minImpactSpeed = 5;        // Impacts over this invoke the script callback
28417      softImpactSpeed = 5;       // Play SoftImpact Sound
28418      hardImpactSpeed = 15;      // Play HardImpact Sound
28419      integration = 4;           // Physics integration: TickSec/Rate
28420      collisionTol = 0.1;        // Collision distance tolerance
28421      contactTol = 0.1;          // Contact velocity tolerance
28422
28423      minRollSpeed = 10;
28424
28425      maxDrag = 0.5;
28426      minDrag = 0.01;
28427
28428      dustHeight = 10;
28429
28430      dragForce = 0.05;
28431      vertFactor = 0.05;
28432   };
28433
28434 new RigidShape()
28435   {
28436      dataBlock = "BouncingBoulder";
28437      parentGroup = EWCreatorWindow.objectGroup;
28438   };
28439@endtsexample
28440
28441@see RigidShapeData
28442@see ShapeBase
28443
28444@ingroup Physics
28445
28446*/
28447class RigidShape : public ShapeBase {
28448public:
28449/*!
28450@brief Clears physic forces from the shape and sets it at rest.
28451
28452@tsexample
28453// Inform the RigidShape object to reset.
28454%thisRigidShape.reset();
28455@endtsexample
28456
28457@see ShapeBaseData*/
28458void reset();
28459/*!
28460@brief Enables or disables the physics simulation on the RigidShape object.
28461
28462@param isFrozen Boolean frozen state to set the object.
28463@tsexample
28464// Define the frozen state.
28465%isFrozen = "true";
28466
28467// Inform the object of the defined frozen state
28468%thisRigidShape.freezeSim(%isFrozen);
28469@endtsexample
28470
28471@see ShapeBaseData*/
28472void freezeSim( bool isFrozen );
28473/*!
28474@brief Forces the client to jump to the RigidShape's transform rather then warp to it.*/
28475void forceClientTransform();
28476
28477/*! @name Callbacks
28478@{ */
28479/// @}
28480
28481/*!
28482@brief Disables rendering of all instances of this type.
28483
28484
28485@ingroup UNDOCUMENTED
28486*/
28487static bool isRenderable;
28488/*!
28489@brief Disables selection of all instances of this type.
28490
28491
28492@ingroup UNDOCUMENTED
28493*/
28494static bool isSelectable;
28495
28496/*! @name Game
28497@{ */
28498/// @}
28499
28500
28501/*! @name GameObject
28502@{ */
28503/// @}
28504
28505
28506/*! @name Transform
28507@{ */
28508/// @}
28509
28510
28511/*! @name Editing
28512@{ */
28513/// @}
28514
28515
28516/*! @name Mounting
28517@{ */
28518/// @}
28519
28520
28521/*! @name Ungrouped
28522@{ */
28523/// @}
28524
28525
28526/*! @name Object
28527@{ */
28528/// @}
28529
28530
28531/*! @name Editing
28532@{ */
28533/// @}
28534
28535
28536/*! @name Persistence
28537@{ */
28538/// @}
28539
28540};
28541
28542/*!
28543@brief Base functionality shared by all Vehicles (FlyingVehicle, HoverVehicle, WheeledVehicle).
28544
28545This object implements functionality shared by all Vehicle types, but should not be instantiated directly. Create a FlyingVehicle, HoverVehicle, or WheeledVehicle instead.
28546@note The model used for any Vehicle must include a collision mesh at detail size -1.
28547@ingroup Vehicles
28548
28549*/
28550class Vehicle : public RigidShape {
28551public:
28552
28553/*! @name Callbacks
28554@{ */
28555/// @}
28556
28557/*!
28558@brief Disables rendering of all instances of this type.
28559
28560
28561@ingroup UNDOCUMENTED
28562*/
28563static bool isRenderable;
28564/*!
28565@brief Disables selection of all instances of this type.
28566
28567
28568@ingroup UNDOCUMENTED
28569*/
28570static bool isSelectable;
28571/*!
28572@brief The maximum number of ticks that go by before the mWorkingQueryBox is considered stale and needs updating.
28573
28574Other factors can cause the collision working query box to become invalidated, such as the vehicle moving far enough outside of this cached box.  The smaller this number, the more times the working list of triangles that are considered for collision is refreshed.  This has the greatest impact with colliding with high triangle count meshes.
28575
28576@note Set to -1 to disable any time-based forced check.
28577
28578@ingroup GameObjects
28579*/
28580static int workingQueryBoxStaleThreshold;
28581/*!
28582@brief How much larger the mWorkingQueryBox should be made when updating the working collision list.
28583
28584The larger this number the less often the working list will be updated due to motion, but any non-static shape that moves into the query box will not be noticed.
28585
28586@ingroup GameObjects
28587*/
28588static float workingQueryBoxSizeMultiplier;
28589/*!
28590@brief When this flag is set, the vehicle will ignore throttle changes.
28591*/
28592bool disableMove;
28593
28594/*! @name Game
28595@{ */
28596/// @}
28597
28598
28599/*! @name GameObject
28600@{ */
28601/// @}
28602
28603
28604/*! @name Transform
28605@{ */
28606/// @}
28607
28608
28609/*! @name Editing
28610@{ */
28611/// @}
28612
28613
28614/*! @name Mounting
28615@{ */
28616/// @}
28617
28618
28619/*! @name Ungrouped
28620@{ */
28621/// @}
28622
28623
28624/*! @name Object
28625@{ */
28626/// @}
28627
28628
28629/*! @name Editing
28630@{ */
28631/// @}
28632
28633
28634/*! @name Persistence
28635@{ */
28636/// @}
28637
28638};
28639
28640/*!
28641@brief A hovering vehicle.
28642
28643A hover vehicle is a vehicle that maintains a specific distance between the vehicle and the ground at all times; unlike a flying vehicle which is free to ascend and descend at will.The model used for the HoverVehicle has the following requirements:
28644<dl><dt>Collision mesh</dt><dd>A convex collision mesh at detail size -1.</dd><dt>JetNozzle0-1 nodes</dt><dd>Particle emitter nodes used when thrusting forward.</dd><dt>JetNozzle2-3 nodes</dt><dd>Particle emitter nodes used when thrusting downward.</dd><dt>JetNozzleX node</dt><dd>Particle emitter node used when thrusting backward.</dd><dt>activateBack animation</dt><dd>Non-cyclic animation sequence played when the vehicle begins thrusting forwards.</dd><dt>maintainBack animation</dt><dd>Cyclic animation sequence played after activateBack when the vehicle continues thrusting forwards.</dd></dl>@ingroup Vehicles
28645
28646*/
28647class HoverVehicle : public Vehicle {
28648public:
28649
28650/*! @name Callbacks
28651@{ */
28652/// @}
28653
28654/*!
28655@brief Disables rendering of all instances of this type.
28656
28657
28658@ingroup UNDOCUMENTED
28659*/
28660static bool isRenderable;
28661/*!
28662@brief Disables selection of all instances of this type.
28663
28664
28665@ingroup UNDOCUMENTED
28666*/
28667static bool isSelectable;
28668
28669/*! @name Game
28670@{ */
28671/// @}
28672
28673
28674/*! @name GameObject
28675@{ */
28676/// @}
28677
28678
28679/*! @name Transform
28680@{ */
28681/// @}
28682
28683
28684/*! @name Editing
28685@{ */
28686/// @}
28687
28688
28689/*! @name Mounting
28690@{ */
28691/// @}
28692
28693
28694/*! @name Ungrouped
28695@{ */
28696/// @}
28697
28698
28699/*! @name Object
28700@{ */
28701/// @}
28702
28703
28704/*! @name Editing
28705@{ */
28706/// @}
28707
28708
28709/*! @name Persistence
28710@{ */
28711/// @}
28712
28713};
28714
28715/*!
28716@brief Defines the properties of a WheeledVehicle tire.
28717
28718Tires act as springs and generate lateral and longitudinal forces to move the vehicle. These distortion/spring forces are what convert wheel angular velocity into forces that act on the rigid body.
28719@ingroup Vehicles
28720
28721*/
28722class WheeledVehicleTire : public SimDataBlock {
28723public:
28724
28725/*! @name Callbacks
28726@{ */
28727/// @}
28728
28729/*!
28730@brief The path to the shape to use for the wheel.
28731*/
28732filename shapeFile;
28733/*!
28734@brief The mass of the wheel.
28735
28736Currently unused.
28737*/
28738float mass;
28739/*!
28740@brief @brief The radius of the wheel.
28741
28742
28743The radius is determined from the bounding box of the shape provided in the shapefile field, and does not need to be specified in script. The tire should be built with its hub axis along the object's Y-axis.
28744*/
28745float radius;
28746/*!
28747@brief Tire friction when the wheel is not slipping (has traction).
28748*/
28749float staticFriction;
28750/*!
28751@brief Tire friction when the wheel is slipping (no traction).
28752*/
28753float kineticFriction;
28754/*!
28755@brief Tire restitution.
28756
28757Currently unused.
28758*/
28759float restitution;
28760/*!
28761@brief @brief Tire force perpendicular to the direction of movement.
28762
28763
28764Lateral force can in simple terms be considered left/right steering force. WheeledVehicles are acted upon by forces generated by their tires and the lateralForce measures the magnitude of the force exerted on the vehicle when the tires are deformed along the x-axis. With real wheeled vehicles, tires are constantly being deformed and it is the interplay of deformation forces which determines how a vehicle moves. In Torque's simulation of vehicle physics, tire deformation obviously can't be handled with absolute realism, but the interplay of a vehicle's velocity, its engine's torque and braking forces, and its wheels' friction, lateral deformation, lateralDamping, lateralRelaxation, longitudinal deformation, longitudinalDamping, and longitudinalRelaxation forces, along with its wheels' angular velocity are combined to create a robust real-time physical simulation.
28765
28766For this field, the larger the value supplied for the lateralForce, the larger the effect steering maneuvers can have. In Torque tire forces are applied at a vehicle's wheel hubs.
28767*/
28768float lateralForce;
28769/*!
28770@brief Damping force applied against lateral forces generated by the tire.
28771
28772
28773@see lateralForce
28774*/
28775float lateralDamping;
28776/*!
28777@brief @brief Relaxing force applied against lateral forces generated by the tire.
28778
28779
28780The lateralRelaxation force measures how strongly the tire effectively un-deforms.
28781
28782@see lateralForce
28783*/
28784float lateralRelaxation;
28785/*!
28786@brief @brief Tire force in the direction of movement.
28787
28788
28789Longitudinal force can in simple terms be considered forward/backward movement force. WheeledVehicles are acted upon by forces generated by their tires and the longitudinalForce measures the magnitude of the force exerted on the vehicle when the tires are deformed along the y-axis.
28790
28791For this field, the larger the value, the larger the effect acceleration/deceleration inputs have.
28792
28793@see lateralForce
28794*/
28795float longitudinalForce;
28796/*!
28797@brief Damping force applied against longitudinal forces generated by the tire.
28798
28799
28800@see longitudinalForce
28801*/
28802float longitudinalDamping;
28803/*!
28804@brief @brief Relaxing force applied against longitudinal forces generated by the tire.
28805
28806
28807The longitudinalRelaxation force measures how strongly the tire effectively un-deforms.
28808
28809@see longitudinalForce
28810*/
28811float longitudinalRelaxation;
28812
28813/*! @name Ungrouped
28814@{ */
28815/// @}
28816
28817
28818/*! @name Object
28819@{ */
28820/// @}
28821
28822
28823/*! @name Editing
28824@{ */
28825/// @}
28826
28827
28828/*! @name Persistence
28829@{ */
28830/// @}
28831
28832};
28833
28834/*!
28835@brief Defines the properties of a WheeledVehicle spring.
28836
28837@ingroup Vehicles
28838
28839*/
28840class WheeledVehicleSpring : public SimDataBlock {
28841public:
28842
28843/*! @name Callbacks
28844@{ */
28845/// @}
28846
28847/*!
28848@brief @brief Maximum spring length. ie. how far the wheel can extend from the root hub position.
28849
28850
28851This should be set to the vertical (Z) distance the hub travels in the associated spring animation.
28852*/
28853float length;
28854/*!
28855@brief @brief Maximum spring force (when compressed to minimum length, 0).
28856
28857
28858Increasing this will make the vehicle suspension ride higher (for a given vehicle mass), and also make the vehicle more bouncy when landing jumps.
28859*/
28860float force;
28861/*!
28862@brief @brief Force applied to slow changes to the extension of this spring.
28863
28864
28865Increasing this makes the suspension stiffer which can help stabilise bouncy vehicles.
28866*/
28867float damping;
28868/*!
28869@brief @brief Force applied to equalize extension of the spring on the opposite wheel.
28870
28871
28872This force helps to keep the suspension balanced when opposite wheels are at different heights.
28873*/
28874float antiSwayForce;
28875
28876/*! @name Ungrouped
28877@{ */
28878/// @}
28879
28880
28881/*! @name Object
28882@{ */
28883/// @}
28884
28885
28886/*! @name Editing
28887@{ */
28888/// @}
28889
28890
28891/*! @name Persistence
28892@{ */
28893/// @}
28894
28895};
28896
28897/*!
28898@brief Defines the properties of a WheeledVehicle.
28899
28900@ingroup Vehicles
28901
28902*/
28903class WheeledVehicleData : public VehicleData {
28904public:
28905
28906/*! @name Callbacks
28907@{ */
28908/// @}
28909
28910/*!
28911@brief Looping sound played when the vehicle is jetting.
28912*/
28913SFXTrack jetSound;
28914/*!
28915@brief @brief Looping engine sound.
28916
28917
28918The pitch is dynamically adjusted based on the current engine RPM
28919*/
28920SFXTrack engineSound;
28921/*!
28922@brief @brief Looping sound played while any of the wheels is slipping.
28923
28924
28925The volume is dynamically adjusted based on how much the wheels are slipping.
28926*/
28927SFXTrack squealSound;
28928/*!
28929@brief Sound played when the wheels impact the ground.
28930
28931Currently unused.
28932*/
28933SFXTrack WheelImpactSound;
28934/*!
28935@brief ParticleEmitterData datablock used to generate particles from each wheel when the vehicle is moving and the wheel is in contact with the ground.
28936*/
28937ParticleEmitterData tireEmitter;
28938/*!
28939@brief @brief Maximum linear velocity of each wheel.
28940
28941
28942This caps the maximum speed of the vehicle.
28943*/
28944float maxWheelSpeed;
28945/*!
28946@brief @brief Torque available from the engine at 100% throttle.
28947
28948
28949This controls vehicle acceleration. ie. how fast it will reach maximum speed.
28950*/
28951float engineTorque;
28952/*!
28953@brief @brief Braking torque applied by the engine when the throttle and brake are both 0.
28954
28955
28956This controls how quickly the vehicle will coast to a stop.
28957*/
28958float engineBrake;
28959/*!
28960@brief @brief Torque applied when braking.
28961
28962
28963This controls how fast the vehicle will stop when the brakes are applied.
28964*/
28965float brakeTorque;
28966
28967/*! @name Physics
28968@{ */
28969/// @}
28970
28971
28972/*! @name Physics
28973@{ */
28974/// @}
28975
28976
28977/*! @name Forces
28978@{ */
28979/// @}
28980
28981
28982/*! @name Particle Effects
28983@{ */
28984/// @}
28985
28986
28987/*! @name Sounds
28988@{ */
28989/// @}
28990
28991
28992/*! @name Camera
28993@{ */
28994/// @}
28995
28996
28997/*! @name Shadows
28998@{ */
28999/// @}
29000
29001
29002/*! @name Render
29003@{ */
29004/// @}
29005
29006
29007/*! @name Destruction
29008Parameters related to the destruction effects of this object.
29009@{ */
29010/// @}
29011
29012
29013/*! @name Physics
29014@{ */
29015/// @}
29016
29017
29018/*! @name Damage/Energy
29019@{ */
29020/// @}
29021
29022
29023/*! @name Camera
29024The settings used by the shape when it is the camera.
29025@{ */
29026/// @}
29027
29028
29029/*! @name Misc
29030@{ */
29031/// @}
29032
29033
29034/*! @name Reflection
29035@{ */
29036/// @}
29037
29038
29039/*! @name Scripting
29040@{ */
29041/// @}
29042
29043
29044/*! @name Ungrouped
29045@{ */
29046/// @}
29047
29048
29049/*! @name Object
29050@{ */
29051/// @}
29052
29053
29054/*! @name Editing
29055@{ */
29056/// @}
29057
29058
29059/*! @name Persistence
29060@{ */
29061/// @}
29062
29063};
29064
29065/*!
29066@brief Represents one or more rigid bodies defined in a single mesh file with a limited lifetime.
29067
29068A PhysicsDebris object can be viewed as a single system capable of generating multiple @link PhysicsBody PhysicsBodies@endlink as debris when triggered. Vaguely similar to how a ParticleEmitter is capable of creating Particles, but isn't a particle in itself. After it's lifetime has elapsed, the object will be deleted.
29069
29070%PhysicsDebris loads a standard .DAE or .DTS file and creates a rigid body for each defined collision node.
29071
29072For collision nodes to work correctly, they must be setup as follows:
29073 - Visible mesh nodes are siblings of the collision node under a common parent dummy node.
29074 -  Collision node is a child of its visible mesh node.
29075
29076Colmesh type nodes are NOT supported; physx and most standard rigid body simulations do not support arbitrary triangle meshs for dynamics do to the computational expense.
29077
29078Therefore, collision nodes must be one of the following:
29079 - Colbox
29080 - Colsphere
29081 - Colcapsule
29082 - Col (convex).
29083
29084%PhysicsDebris should NOT be created on the server.
29085
29086@ingroup Physics
29087*/
29088class PhysicsDebris : public GameBase {
29089public:
29090
29091/*! @name Callbacks
29092@{ */
29093/// @}
29094
29095/*!
29096@brief Disables rendering of all instances of this type.
29097
29098
29099@ingroup UNDOCUMENTED
29100*/
29101static bool isRenderable;
29102/*!
29103@brief Disables selection of all instances of this type.
29104
29105
29106@ingroup UNDOCUMENTED
29107*/
29108static bool isSelectable;
29109
29110/*! @name Game
29111@{ */
29112/// @}
29113
29114
29115/*! @name GameObject
29116@{ */
29117/// @}
29118
29119
29120/*! @name Transform
29121@{ */
29122/// @}
29123
29124
29125/*! @name Editing
29126@{ */
29127/// @}
29128
29129
29130/*! @name Mounting
29131@{ */
29132/// @}
29133
29134
29135/*! @name Ungrouped
29136@{ */
29137/// @}
29138
29139
29140/*! @name Object
29141@{ */
29142/// @}
29143
29144
29145/*! @name Editing
29146@{ */
29147/// @}
29148
29149
29150/*! @name Persistence
29151@{ */
29152/// @}
29153
29154};
29155
29156/*!
29157@brief Defines the properties of a PhysicsShape.
29158
29159@see PhysicsShape.
29160@ingroup Physics
29161*/
29162class PhysicsShapeData : public GameBaseData {
29163public:
29164
29165/*! @name Callbacks
29166@{ */
29167/// @}
29168
29169
29170/*! @name Scripting
29171@{ */
29172/// @}
29173
29174
29175/*! @name Ungrouped
29176@{ */
29177/// @}
29178
29179
29180/*! @name Object
29181@{ */
29182/// @}
29183
29184
29185/*! @name Editing
29186@{ */
29187/// @}
29188
29189
29190/*! @name Persistence
29191@{ */
29192/// @}
29193
29194
29195/*! @name Media
29196@{ */
29197/*!
29198@brief @brief Path to the .DAE or .DTS file to use for this shape.
29199
29200
29201Compatable with Live-Asset Reloading. 
29202*/
29203filename shapeName;
29204/*!
29205@brief @brief Name of a PhysicsDebrisData to spawn when this shape is destroyed (optional).
29206*/
29207PhysicsDebrisData Debris;
29208/*!
29209@brief @brief Name of an ExplosionData to spawn when this shape is destroyed (optional).
29210*/
29211ExplosionData Explosion;
29212/*!
29213@brief @brief Name of a PhysicsShapeData to spawn when this shape is destroyed (optional).
29214*/
29215PhysicsShapeData destroyedShape;
29216/// @}
29217
29218
29219/*! @name Physics
29220@{ */
29221/*!
29222@brief @brief Value representing the mass of the shape.
29223
29224
29225A shape's mass influences the magnitude of any force exerted on it. For example, a PhysicsShape with a large mass requires a much larger force to move than the same shape with a smaller mass.
29226@note A mass of zero will create a kinematic shape while anything greater will create a dynamic shape.
29227*/
29228float mass;
29229/*!
29230@brief @brief Coefficient of kinetic %friction to be applied to the shape.
29231
29232
29233Kinetic %friction reduces the velocity of a moving object while it is in contact with a surface. A higher coefficient will result in a larger velocity reduction. A shape's friction should be lower than it's staticFriction, but larger than 0.
29234
29235@note This value is only applied while an object is in motion. For an object starting at rest, see PhysicsShape::staticFriction
29236*/
29237float friction;
29238/*!
29239@brief @brief Coefficient of static %friction to be applied to the shape.
29240
29241
29242Static %friction determines the force needed to start moving an at-rest object in contact with a surface. If the force applied onto shape cannot overcome the force of static %friction, the shape will remain at rest. A larger coefficient will require a larger force to start motion. This value should be larger than zero and the physicsShape's friction.
29243
29244@note This value is only applied while an object is at rest. For an object in motion, see PhysicsShape::friction
29245*/
29246float staticFriction;
29247/*!
29248@brief @brief Coeffecient of a bounce applied to the shape in response to a collision.
29249
29250
29251Restitution is a ratio of a shape's velocity before and after a collision. A value of 0 will zero out a shape's post-collision velocity, making it stop on contact. Larger values will remove less velocity after a collision, making it 'bounce' with a greater force. Normal %restitution values range between 0 and 1.0.@note Values near or equaling 1.0 are likely to cause undesirable results in the physics simulation. Because of this it is reccomended to avoid values close to 1.0
29252*/
29253float restitution;
29254/*!
29255@brief @brief Value that reduces an object's linear velocity over time.
29256
29257
29258Larger values will cause velocity to decay quicker.
29259
29260
29261*/
29262float linearDamping;
29263/*!
29264@brief @brief Value that reduces an object's rotational velocity over time.
29265
29266
29267Larger values will cause velocity to decay quicker.
29268
29269
29270*/
29271float angularDamping;
29272/*!
29273@brief @brief Minimum linear velocity before the shape can be put to sleep.
29274
29275
29276This should be a positive value. Shapes put to sleep will not be simulated in order to save system resources.
29277
29278@note The shape must be dynamic.
29279*/
29280float linearSleepThreshold;
29281/*!
29282@brief @brief Minimum rotational velocity before the shape can be put to sleep.
29283
29284
29285This should be a positive value. Shapes put to sleep will not be simulated in order to save system resources.
29286
29287@note The shape must be dynamic.
29288*/
29289float angularSleepThreshold;
29290/*!
29291@brief @brief Scale to apply to linear and angular dampening while underwater.
29292
29293
29294 Used with the waterViscosity of the  @see angularDamping linearDamping
29295*/
29296float waterDampingScale;
29297/*!
29298@brief @brief The density of the shape for calculating buoyant forces.
29299
29300
29301The result of the calculated buoyancy is relative to the density of the WaterObject the PhysicsShape is within.
29302
29303@see WaterObject::density
29304*/
29305float buoyancyDensity;
29306/// @}
29307
29308
29309/*! @name Networking
29310@{ */
29311/*!
29312@brief @brief Controls whether this shape is simulated on the server, client, or both physics simulations.
29313
29314
29315
29316*/
29317PhysicsSimType simType;
29318/// @}
29319
29320};
29321
29322/*!
29323@brief The object that manages all of the decals in the active mission.
29324
29325@see Decals
29326@ingroup Decals
29327@ingroup FX
29328
29329*/
29330class DecalManager : public SceneObject {
29331public:
29332
29333/*! @name Callbacks
29334@{ */
29335/// @}
29336
29337/*!
29338@brief Disables rendering of all instances of this type.
29339
29340
29341@ingroup UNDOCUMENTED
29342*/
29343static bool isRenderable;
29344/*!
29345@brief Disables selection of all instances of this type.
29346
29347
29348@ingroup UNDOCUMENTED
29349*/
29350static bool isSelectable;
29351
29352/*! @name GameObject
29353@{ */
29354/// @}
29355
29356
29357/*! @name Transform
29358@{ */
29359/// @}
29360
29361
29362/*! @name Editing
29363@{ */
29364/// @}
29365
29366
29367/*! @name Mounting
29368@{ */
29369/// @}
29370
29371
29372/*! @name Ungrouped
29373@{ */
29374/// @}
29375
29376
29377/*! @name Object
29378@{ */
29379/// @}
29380
29381
29382/*! @name Editing
29383@{ */
29384/// @}
29385
29386
29387/*! @name Persistence
29388@{ */
29389/// @}
29390
29391};
29392
29393/*!
29394@brief A volume in space that defines an ambient sound zone.
29395
29396@ingroup SFX
29397*/
29398class SFXSpace : public SceneObject {
29399public:
29400
29401/*! @name Callbacks
29402@{ */
29403/// @}
29404
29405/*!
29406@brief Disables rendering of all instances of this type.
29407
29408
29409@ingroup UNDOCUMENTED
29410*/
29411static bool isRenderable;
29412/*!
29413@brief Disables selection of all instances of this type.
29414
29415
29416@ingroup UNDOCUMENTED
29417*/
29418static bool isSelectable;
29419
29420/*! @name Sound
29421@{ */
29422/*!
29423@brief Ambient sound environment for the space.
29424*/
29425SFXAmbience soundAmbience;
29426/// @}
29427
29428
29429/*! @name Internal
29430@{ */
29431/*!
29432@brief For internal use only.
29433*/
29434string plane;
29435/*!
29436@brief For internal use only.
29437*/
29438string point;
29439/*!
29440@brief For internal use only.
29441*/
29442string edge;
29443/// @}
29444
29445
29446/*! @name GameObject
29447@{ */
29448/// @}
29449
29450
29451/*! @name Transform
29452@{ */
29453/// @}
29454
29455
29456/*! @name Editing
29457@{ */
29458/// @}
29459
29460
29461/*! @name Mounting
29462@{ */
29463/// @}
29464
29465
29466/*! @name Ungrouped
29467@{ */
29468/// @}
29469
29470
29471/*! @name Object
29472@{ */
29473/// @}
29474
29475
29476/*! @name Editing
29477@{ */
29478/// @}
29479
29480
29481/*! @name Persistence
29482@{ */
29483/// @}
29484
29485};
29486
29487/*!
29488@brief Defines properties for a TurretShape object.
29489
29490@see TurretShape
29491@see TurretShapeData
29492@ingroup gameObjects
29493
29494*/
29495class TurretShapeData : public ItemData {
29496public:
29497
29498/*! @name Callbacks
29499@{ */
29500/*!
29501@brief Informs the TurretShapeData object that a player is mounting it.
29502
29503@param turret The TurretShape object.
29504@param obj The player that is mounting.
29505@param node The node the player is mounting to.
29506@note Server side only.*/
29507void onMountObject( SceneObject turret, SceneObject obj, int node );
29508/*!
29509@brief Informs the TurretShapeData object that a player is unmounting it.
29510
29511@param turret The TurretShape object.
29512@param obj The player that is unmounting.
29513@note Server side only.*/
29514void onUnmountObject( SceneObject turret, SceneObject obj );
29515/*!
29516@brief Informs the TurretData object that it is now sticking to another object.
29517
29518This callback is only called if the TurretData::sticky property for this Turret is true.
29519@param obj The Turret object that is colliding.
29520@note Server side only.
29521@see TurretShape, TurretData*/
29522void onStickyCollision( TurretShape obj );
29523/// @}
29524
29525/*!
29526@brief @brief Should the turret allow only z rotations.
29527
29528
29529True indicates that the turret may only be rotated on its z axis, just like the Item class.  This keeps the turret always upright regardless of the surface it lands on.
29530
29531*/
29532bool zRotOnly;
29533/*!
29534@brief @brief Set how the mounted weapons are linked and triggered.
29535
29536
29537<ul><li>FireTogether: All weapons fire under trigger 0.</li><li>GroupedFire: Weapon mounts 0,2 fire under trigger 0, mounts 1,3 fire under trigger 1.</li><li>IndividualFire: Each weapon mount fires under its own trigger 0-3.</li></ul>
29538@see TurretShapeFireLinkType
29539*/
29540TurretShapeFireLinkType weaponLinkType;
29541/*!
29542@brief @brief Does the turret's mounted weapon(s) start in a loaded state.
29543
29544
29545True indicates that all mounted weapons start in a loaded state.
29546@see ShapeBase::setImageLoaded()
29547*/
29548bool startLoaded;
29549/*!
29550@brief Vertical (Z axis) height of the camera above the turret.
29551*/
29552float cameraOffset;
29553/*!
29554@brief @brief Maximum number of degrees to rotate from center.
29555
29556
29557A value of 180 or more degrees indicates the turret may rotate completely around.
29558
29559*/
29560float maxHeading;
29561/*!
29562@brief @brief Minimum number of degrees to rotate down from straight ahead.
29563
29564
29565
29566*/
29567float minPitch;
29568/*!
29569@brief @brief Maximum number of degrees to rotate up from straight ahead.
29570
29571
29572
29573*/
29574float maxPitch;
29575/*!
29576@brief @brief Degrees per second rotation.
29577
29578
29579A value of 0 means no rotation is allowed.  A value less than 0 means the rotation is instantaneous.
29580
29581*/
29582float headingRate;
29583/*!
29584@brief @brief Degrees per second rotation.
29585
29586
29587A value of 0 means no rotation is allowed.  A value less than 0 means the rotation is instantaneous.
29588
29589*/
29590float pitchRate;
29591
29592/*! @name Shadows
29593@{ */
29594/// @}
29595
29596
29597/*! @name Render
29598@{ */
29599/// @}
29600
29601
29602/*! @name Destruction
29603Parameters related to the destruction effects of this object.
29604@{ */
29605/// @}
29606
29607
29608/*! @name Physics
29609@{ */
29610/// @}
29611
29612
29613/*! @name Damage/Energy
29614@{ */
29615/// @}
29616
29617
29618/*! @name Camera
29619The settings used by the shape when it is the camera.
29620@{ */
29621/// @}
29622
29623
29624/*! @name Misc
29625@{ */
29626/// @}
29627
29628
29629/*! @name Reflection
29630@{ */
29631/// @}
29632
29633
29634/*! @name Scripting
29635@{ */
29636/// @}
29637
29638
29639/*! @name Ungrouped
29640@{ */
29641/// @}
29642
29643
29644/*! @name Object
29645@{ */
29646/// @}
29647
29648
29649/*! @name Editing
29650@{ */
29651/// @}
29652
29653
29654/*! @name Persistence
29655@{ */
29656/// @}
29657
29658};
29659
29660/*!
29661@brief Defines properties for an AITurretShape object.
29662
29663@see AITurretShape
29664@see TurretShapeData
29665@ingroup gameObjects
29666
29667*/
29668class AITurretShapeData : public TurretShapeData {
29669public:
29670
29671/*! @name Callbacks
29672@{ */
29673/// @}
29674
29675/*!
29676@brief @brief Maximum number of degrees to scan left and right.
29677
29678
29679@note Maximum scan heading is 90 degrees.
29680
29681*/
29682float maxScanHeading;
29683/*!
29684@brief @brief Maximum number of degrees to scan up and down.
29685
29686
29687@note Maximum scan pitch is 90 degrees.
29688
29689*/
29690float maxScanPitch;
29691/*!
29692@brief @brief Maximum distance to scan.
29693
29694
29695When combined with maxScanHeading and maxScanPitch this forms a 3D scanning wedge used to initially locate a target.
29696
29697*/
29698float maxScanDistance;
29699/*!
29700@brief @brief How often should we perform a full scan when looking for a target.
29701
29702
29703Expressed as the number of ticks between full scans, but no less than 1.
29704
29705*/
29706int scanTickFrequency;
29707/*!
29708@brief @brief Random amount that should be added to the scan tick frequency each scan period.
29709
29710
29711Expressed as the number of ticks to randomly add, but no less than zero.
29712
29713*/
29714int scanTickFrequencyVariance;
29715/*!
29716@brief @brief How long after the turret has lost the target should it still track it.
29717
29718
29719Expressed in seconds.
29720
29721*/
29722float trackLostTargetTime;
29723/*!
29724@brief @brief Maximum distance that the weapon will fire upon a target.
29725
29726
29727
29728*/
29729float maxWeaponRange;
29730/*!
29731@brief @brief Velocity used to lead target.
29732
29733
29734If value <= 0, don't lead target.
29735
29736*/
29737float weaponLeadVelocity;
29738/*!
29739@brief Name of this state.
29740*/
29741caseString stateName[ 31 ];
29742/*!
29743@brief Name of the state to transition to when the turret is at rest (static).
29744*/
29745string stateTransitionOnAtRest[ 31 ];
29746/*!
29747@brief Name of the state to transition to when the turret is not at rest (not static).
29748*/
29749string stateTransitionOnNotAtRest[ 31 ];
29750/*!
29751@brief Name of the state to transition to when the turret gains a target.
29752*/
29753string stateTransitionOnTarget[ 31 ];
29754/*!
29755@brief Name of the state to transition to when the turret loses a target.
29756*/
29757string stateTransitionOnNoTarget[ 31 ];
29758/*!
29759@brief Name of the state to transition to when the turret goes from deactivated to activated.
29760*/
29761string stateTransitionOnActivated[ 31 ];
29762/*!
29763@brief Name of the state to transition to when the turret goes from activated to deactivated
29764*/
29765string stateTransitionOnDeactivated[ 31 ];
29766/*!
29767@brief Name of the state to transition to when we have been in this state for stateTimeoutValue seconds.
29768*/
29769string stateTransitionOnTimeout[ 31 ];
29770/*!
29771@brief Time in seconds to wait before transitioning to stateTransitionOnTimeout.
29772*/
29773float stateTimeoutValue[ 31 ];
29774/*!
29775@brief If false, this state ignores stateTimeoutValue and transitions immediately if other transition conditions are met.
29776*/
29777bool stateWaitForTimeout[ 31 ];
29778/*!
29779@brief The first state with this set to true is the state entered by the client when it receives the 'fire' event.
29780*/
29781bool stateFire[ 31 ];
29782/*!
29783@brief Indicates the turret should perform a continuous scan looking for targets.
29784*/
29785bool stateScan[ 31 ];
29786/*!
29787@brief @brief Direction of the animation to play in this state.
29788
29789
29790True is forward, false is backward.
29791*/
29792bool stateDirection[ 31 ];
29793/*!
29794@brief Name of the sequence to play on entry to this state.
29795*/
29796string stateSequence[ 31 ];
29797/*!
29798@brief If true, the timeScale of the stateSequence animation will be adjusted such that the sequence plays for stateTimeoutValue seconds. 
29799*/
29800bool stateScaleAnimation[ 31 ];
29801/*!
29802@brief @brief Method to execute on entering this state.
29803
29804
29805Scoped to AITurretShapeData.
29806*/
29807caseString stateScript[ 31 ];
29808
29809/*! @name Shadows
29810@{ */
29811/// @}
29812
29813
29814/*! @name Render
29815@{ */
29816/// @}
29817
29818
29819/*! @name Destruction
29820Parameters related to the destruction effects of this object.
29821@{ */
29822/// @}
29823
29824
29825/*! @name Physics
29826@{ */
29827/// @}
29828
29829
29830/*! @name Damage/Energy
29831@{ */
29832/// @}
29833
29834
29835/*! @name Camera
29836The settings used by the shape when it is the camera.
29837@{ */
29838/// @}
29839
29840
29841/*! @name Misc
29842@{ */
29843/// @}
29844
29845
29846/*! @name Reflection
29847@{ */
29848/// @}
29849
29850
29851/*! @name Scripting
29852@{ */
29853/// @}
29854
29855
29856/*! @name Ungrouped
29857@{ */
29858/// @}
29859
29860
29861/*! @name Object
29862@{ */
29863/// @}
29864
29865
29866/*! @name Editing
29867@{ */
29868/// @}
29869
29870
29871/*! @name Persistence
29872@{ */
29873/// @}
29874
29875};
29876
29877/*!
29878@brief An example scene object which renders a mesh.
29879
29880This class implements a basic SceneObject that can exist in the world at a 3D position and render itself. There are several valid ways to render an object in Torque. This class implements the preferred rendering method which is to submit a MeshRenderInst along with a Material, vertex buffer, primitive buffer, and transform and allow the RenderMeshMgr handle the actual setup and rendering for you.
29881
29882See the C++ code for implementation details.
29883
29884@ingroup Examples
29885
29886*/
29887class ReflectionProbe : public SceneObject {
29888public:
29889/*!
29890@brief A utility method for forcing a network update.
29891
29892*/
29893void postApply();
29894/*!
29895@brief Bakes the cubemaps for a reflection probe
29896
29897.*/
29898void Bake();
29899
29900/*! @name Callbacks
29901@{ */
29902/// @}
29903
29904/*!
29905@brief Disables rendering of all instances of this type.
29906
29907
29908@ingroup UNDOCUMENTED
29909*/
29910static bool isRenderable;
29911/*!
29912@brief Disables selection of all instances of this type.
29913
29914
29915@ingroup UNDOCUMENTED
29916*/
29917static bool isSelectable;
29918
29919/*! @name Rendering
29920@{ */
29921/*!
29922@brief Is the probe enabled or not
29923*/
29924bool Enabled;
29925/// @}
29926
29927
29928/*! @name Reflection
29929@{ */
29930/*!
29931@brief The name of the material used to render the mesh.
29932*/
29933float radius;
29934/*!
29935@brief Toggle Edit Pos Offset Mode
29936*/
29937bool EditPosOffset;
29938/*!
29939@brief The reference positional offset for the probe. This is used for adjusting the perceived center and area of influence.
29940
29941Helpful in adjusting parallax issues
29942*/
29943Point3F refOffset;
29944/*!
29945@brief The reference scale for the probe. This is used for adjusting the perceived center and area of influence.
29946
29947Helpful in adjusting parallax issues
29948*/
29949Point3F refScale;
29950/*!
29951@brief Used to dictate what sort of cubemap the probes use when using IBL.
29952*/
29953ReflectionModeEnum ReflectionMode;
29954/*!
29955@brief This is used when a static cubemap is used. The name of the cubemap is looked up and loaded for the IBL calculations.
29956*/
29957string StaticCubemap;
29958/*!
29959@brief Bake Probe Reflections
29960*/
29961bool Bake;
29962/// @}
29963
29964
29965/*! @name GameObject
29966@{ */
29967/// @}
29968
29969
29970/*! @name Transform
29971@{ */
29972/// @}
29973
29974
29975/*! @name Editing
29976@{ */
29977/// @}
29978
29979
29980/*! @name Mounting
29981@{ */
29982/// @}
29983
29984
29985/*! @name Ungrouped
29986@{ */
29987/// @}
29988
29989
29990/*! @name Object
29991@{ */
29992/// @}
29993
29994
29995/*! @name Editing
29996@{ */
29997/// @}
29998
29999
30000/*! @name Persistence
30001@{ */
30002/// @}
30003
30004};
30005
30006/*!
30007@brief An example scene object which renders a mesh.
30008
30009This class implements a basic SceneObject that can exist in the world at a 3D position and render itself. There are several valid ways to render an object in Torque. This class implements the preferred rendering method which is to submit a MeshRenderInst along with a Material, vertex buffer, primitive buffer, and transform and allow the RenderMeshMgr handle the actual setup and rendering for you.
30010
30011See the C++ code for implementation details.
30012
30013@ingroup Examples
30014
30015*/
30016class BoxEnvironmentProbe : public ReflectionProbe {
30017public:
30018
30019/*! @name Callbacks
30020@{ */
30021/// @}
30022
30023/*!
30024@brief Disables rendering of all instances of this type.
30025
30026
30027@ingroup UNDOCUMENTED
30028*/
30029static bool isRenderable;
30030/*!
30031@brief Disables selection of all instances of this type.
30032
30033
30034@ingroup UNDOCUMENTED
30035*/
30036static bool isSelectable;
30037
30038/*! @name Rendering
30039@{ */
30040/// @}
30041
30042
30043/*! @name Reflection
30044@{ */
30045/// @}
30046
30047
30048/*! @name GameObject
30049@{ */
30050/// @}
30051
30052
30053/*! @name Transform
30054@{ */
30055/// @}
30056
30057
30058/*! @name Editing
30059@{ */
30060/// @}
30061
30062
30063/*! @name Mounting
30064@{ */
30065/// @}
30066
30067
30068/*! @name Ungrouped
30069@{ */
30070/// @}
30071
30072
30073/*! @name Object
30074@{ */
30075/// @}
30076
30077
30078/*! @name Editing
30079@{ */
30080/// @}
30081
30082
30083/*! @name Persistence
30084@{ */
30085/// @}
30086
30087/*!
30088@brief falloff percent
30089*/
30090float attenuation;
30091};
30092
30093/*!
30094@brief An example scene object which renders a mesh.
30095
30096This class implements a basic SceneObject that can exist in the world at a 3D position and render itself. There are several valid ways to render an object in Torque. This class implements the preferred rendering method which is to submit a MeshRenderInst along with a Material, vertex buffer, primitive buffer, and transform and allow the RenderMeshMgr handle the actual setup and rendering for you.
30097
30098See the C++ code for implementation details.
30099
30100@ingroup Examples
30101
30102*/
30103class SphereEnvironmentProbe : public ReflectionProbe {
30104public:
30105
30106/*! @name Callbacks
30107@{ */
30108/// @}
30109
30110/*!
30111@brief Disables rendering of all instances of this type.
30112
30113
30114@ingroup UNDOCUMENTED
30115*/
30116static bool isRenderable;
30117/*!
30118@brief Disables selection of all instances of this type.
30119
30120
30121@ingroup UNDOCUMENTED
30122*/
30123static bool isSelectable;
30124
30125/*! @name Rendering
30126@{ */
30127/// @}
30128
30129
30130/*! @name Reflection
30131@{ */
30132/// @}
30133
30134
30135/*! @name GameObject
30136@{ */
30137/// @}
30138
30139
30140/*! @name Transform
30141@{ */
30142/// @}
30143
30144
30145/*! @name Editing
30146@{ */
30147/// @}
30148
30149
30150/*! @name Mounting
30151@{ */
30152/// @}
30153
30154
30155/*! @name Ungrouped
30156@{ */
30157/// @}
30158
30159
30160/*! @name Object
30161@{ */
30162/// @}
30163
30164
30165/*! @name Editing
30166@{ */
30167/// @}
30168
30169
30170/*! @name Persistence
30171@{ */
30172/// @}
30173
30174};
30175
30176/*! UNDOCUMENTED!
30177@ingroup UNDOCUMENTED
30178 */
30179class AutoloadAssets : public SimObject {
30180public:
30181
30182/*! @name Callbacks
30183@{ */
30184/// @}
30185
30186
30187/*! @name Ungrouped
30188@{ */
30189/// @}
30190
30191
30192/*! @name Object
30193@{ */
30194/// @}
30195
30196
30197/*! @name Editing
30198@{ */
30199/// @}
30200
30201
30202/*! @name Persistence
30203@{ */
30204/// @}
30205
30206/*!
30207*/
30208string Path;
30209/*!
30210*/
30211string assetType;
30212/*!
30213*/
30214bool Recurse;
30215};
30216
30217/*! UNDOCUMENTED!
30218@ingroup UNDOCUMENTED
30219 */
30220class DeclaredAssets : public SimObject {
30221public:
30222
30223/*! @name Callbacks
30224@{ */
30225/// @}
30226
30227
30228/*! @name Ungrouped
30229@{ */
30230/// @}
30231
30232
30233/*! @name Object
30234@{ */
30235/// @}
30236
30237
30238/*! @name Editing
30239@{ */
30240/// @}
30241
30242
30243/*! @name Persistence
30244@{ */
30245/// @}
30246
30247/*!
30248*/
30249string Path;
30250/*!
30251*/
30252string Extension;
30253/*!
30254*/
30255bool Recurse;
30256};
30257
30258/*! UNDOCUMENTED!
30259@ingroup UNDOCUMENTED
30260 */
30261class ReferencedAssets : public SimObject {
30262public:
30263
30264/*! @name Callbacks
30265@{ */
30266/// @}
30267
30268
30269/*! @name Ungrouped
30270@{ */
30271/// @}
30272
30273
30274/*! @name Object
30275@{ */
30276/// @}
30277
30278
30279/*! @name Editing
30280@{ */
30281/// @}
30282
30283
30284/*! @name Persistence
30285@{ */
30286/// @}
30287
30288/*!
30289*/
30290string Path;
30291/*!
30292*/
30293string Extension;
30294/*!
30295*/
30296bool Recurse;
30297};
30298
30299/*! UNDOCUMENTED!
30300@ingroup UNDOCUMENTED
30301 */
30302class ModuleMergeDefinition : public SimObject {
30303public:
30304
30305/*! @name Callbacks
30306@{ */
30307/// @}
30308
30309
30310/*! @name Ungrouped
30311@{ */
30312/// @}
30313
30314
30315/*! @name Object
30316@{ */
30317/// @}
30318
30319
30320/*! @name Editing
30321@{ */
30322/// @}
30323
30324
30325/*! @name Persistence
30326@{ */
30327/// @}
30328
30329/*!
30330@brief The path where the modules to be merged can be found.
30331*/
30332string MergePath;
30333};
30334
30335/*! UNDOCUMENTED!
30336@ingroup UNDOCUMENTED
30337 */
30338class AssetBase : public SimObject {
30339public:
30340/*!
30341@brief Refresh the asset.
30342
30343@return No return value.
30344*/
30345void refreshAsset();
30346/*!
30347@brief Gets the assets' Asset Id.  This is only available if the asset was acquired from the asset manager.
30348
30349@return The assets' Asset Id.
30350*/
30351String getAssetId();
30352/*!
30353@brief Gets the number of asset dependencies of a given field name.
30354
30355eg. Would return '2' if you searched for 'myDependencyField'
30356and the asset had myDependencyField0 and myDependencyField1
30357@param fieldName The name of the field to get a count of
30358@return The number of dependency fields matching the search name.
30359*/
30360int getAssetDependencyFieldCount( string pFieldName="" );
30361/*!
30362@brief Clears any asset dependency fields matching the name provided.
30363
30364@param fieldName The name of the fields to be cleared*/
30365void clearAssetDependencyFields( string pFieldName="" );
30366/*!
30367@brief Adds an asset dependency field to the asset definition.
30368
30369@param fieldName The name of the field. Will automatically increment the tailing number if the field is used multiple times
30370@param assetId The assetId to be marked as a dependency*/
30371void addAssetDependencyField( string pFieldName="", string pAssetId="" );
30372/*!
30373@brief Saves the asset definition.
30374
30375@return Whether the save was successful.
30376*/
30377bool saveAsset();
30378
30379/*! @name Callbacks
30380@{ */
30381/// @}
30382
30383
30384/*! @name Ungrouped
30385@{ */
30386/// @}
30387
30388
30389/*! @name Object
30390@{ */
30391/// @}
30392
30393
30394/*! @name Editing
30395@{ */
30396/// @}
30397
30398
30399/*! @name Persistence
30400@{ */
30401/// @}
30402
30403/*!
30404@brief The name of the asset.  The is not a unique identification like an asset Id.
30405*/
30406string AssetName;
30407/*!
30408@brief The simple description of the asset contents.
30409*/
30410string AssetDescription;
30411/*!
30412@brief An arbitrary category that can be used to categorized assets.
30413*/
30414string AssetCategory;
30415/*!
30416@brief Whether the asset is automatically unloaded when an asset is released and has no other acquisitions or not.
30417*/
30418bool AssetAutoUnload;
30419/*!
30420@brief Whether the asset is used internally only or not.
30421*/
30422bool AssetInternal;
30423/*!
30424@brief Whether the asset is private or not.
30425*/
30426bool AssetPrivate;
30427};
30428
30429/*! UNDOCUMENTED!
30430@ingroup UNDOCUMENTED
30431 */
30432class CppAsset : public AssetBase {
30433public:
30434
30435/*! @name Callbacks
30436@{ */
30437/// @}
30438
30439
30440/*! @name Ungrouped
30441@{ */
30442/// @}
30443
30444
30445/*! @name Object
30446@{ */
30447/// @}
30448
30449
30450/*! @name Editing
30451@{ */
30452/// @}
30453
30454
30455/*! @name Persistence
30456@{ */
30457/// @}
30458
30459/*!
30460@brief Path to the cpp file.
30461*/
30462assetLooseFilePath codeFile;
30463/*!
30464@brief Path to the h file.
30465*/
30466assetLooseFilePath headerFile;
30467};
30468
30469/*! UNDOCUMENTED!
30470@ingroup UNDOCUMENTED
30471 */
30472class CubemapAsset : public AssetBase {
30473public:
30474
30475/*! @name Callbacks
30476@{ */
30477/// @}
30478
30479
30480/*! @name Ungrouped
30481@{ */
30482/// @}
30483
30484
30485/*! @name Object
30486@{ */
30487/// @}
30488
30489
30490/*! @name Editing
30491@{ */
30492/// @}
30493
30494
30495/*! @name Persistence
30496@{ */
30497/// @}
30498
30499/*!
30500@brief Unique Name of the component. Defines the namespace of the scripts for the component.
30501*/
30502string componentName;
30503/*!
30504@brief Class of object this component uses.
30505*/
30506string componentClass;
30507/*!
30508@brief The human-readble name for the component.
30509*/
30510string friendlyName;
30511/*!
30512@brief The category of the component for organizing in the editor.
30513*/
30514string componentType;
30515/*!
30516@brief Simple description of the component.
30517*/
30518string description;
30519/*!
30520@brief A script file with additional scripted functionality for this component.
30521*/
30522assetLooseFilePath scriptFile;
30523};
30524
30525/*! UNDOCUMENTED!
30526@ingroup UNDOCUMENTED
30527 */
30528class ExampleAsset : public AssetBase {
30529public:
30530
30531/*! @name Callbacks
30532@{ */
30533/// @}
30534
30535
30536/*! @name Ungrouped
30537@{ */
30538/// @}
30539
30540
30541/*! @name Object
30542@{ */
30543/// @}
30544
30545
30546/*! @name Editing
30547@{ */
30548/// @}
30549
30550
30551/*! @name Persistence
30552@{ */
30553/// @}
30554
30555};
30556
30557/*! UNDOCUMENTED!
30558@ingroup UNDOCUMENTED
30559 */
30560class GUIAsset : public AssetBase {
30561public:
30562
30563/*! @name Callbacks
30564@{ */
30565/// @}
30566
30567
30568/*! @name Ungrouped
30569@{ */
30570/// @}
30571
30572
30573/*! @name Object
30574@{ */
30575/// @}
30576
30577
30578/*! @name Editing
30579@{ */
30580/// @}
30581
30582
30583/*! @name Persistence
30584@{ */
30585/// @}
30586
30587/*!
30588@brief Path to the script file for the gui
30589*/
30590assetLooseFilePath scriptFile;
30591/*!
30592@brief Path to the gui file
30593*/
30594assetLooseFilePath GUIFile;
30595};
30596
30597/*! UNDOCUMENTED!
30598@ingroup UNDOCUMENTED
30599 */
30600class ParticleAsset : public AssetBase {
30601public:
30602
30603/*! @name Callbacks
30604@{ */
30605/// @}
30606
30607
30608/*! @name Ungrouped
30609@{ */
30610/// @}
30611
30612
30613/*! @name Object
30614@{ */
30615/// @}
30616
30617
30618/*! @name Editing
30619@{ */
30620/// @}
30621
30622
30623/*! @name Persistence
30624@{ */
30625/// @}
30626
30627/*!
30628@brief Path to the script file for the particle effect
30629*/
30630string scriptFilePath;
30631/*!
30632@brief Path to the datablock file
30633*/
30634string DatablockFilePath;
30635};
30636
30637/*! UNDOCUMENTED!
30638@ingroup UNDOCUMENTED
30639 */
30640class PostEffectAsset : public AssetBase {
30641public:
30642
30643/*! @name Callbacks
30644@{ */
30645/// @}
30646
30647
30648/*! @name Ungrouped
30649@{ */
30650/// @}
30651
30652
30653/*! @name Object
30654@{ */
30655/// @}
30656
30657
30658/*! @name Editing
30659@{ */
30660/// @}
30661
30662
30663/*! @name Persistence
30664@{ */
30665/// @}
30666
30667/*!
30668@brief Path to the script file.
30669*/
30670assetLooseFilePath scriptFile;
30671/*!
30672@brief Path to the hlsl shader file.
30673*/
30674assetLooseFilePath hlslShader;
30675/*!
30676@brief Path to the glsl shader file.
30677*/
30678assetLooseFilePath glslShader;
30679};
30680
30681/*! UNDOCUMENTED!
30682@ingroup UNDOCUMENTED
30683 */
30684class TerrainAsset : public AssetBase {
30685public:
30686
30687/*! @name Callbacks
30688@{ */
30689/// @}
30690
30691
30692/*! @name Ungrouped
30693@{ */
30694/// @}
30695
30696
30697/*! @name Object
30698@{ */
30699/// @}
30700
30701
30702/*! @name Editing
30703@{ */
30704/// @}
30705
30706
30707/*! @name Persistence
30708@{ */
30709/// @}
30710
30711/*!
30712@brief Path to the file containing the terrain data.
30713*/
30714assetLooseFilePath terrainFile;
30715};
30716
30717/*!
30718@brief Defines properties for an AssetImportObject object.
30719@AssetImportObject is a SimObject derived object intended to act as a stand-in for the to-be imported objects.
30720@It contains important info such as dependencies, if it's been processed, any error/status issues and the originating file
30721@or if it's been programmatically generated as part of the import process.
30722
30723@ingroup Assets
30724
30725*/
30726class AssetImportObject : public SimObject {
30727public:
30728
30729/*! @name Callbacks
30730@{ */
30731/// @}
30732
30733
30734/*! @name Ungrouped
30735@{ */
30736/// @}
30737
30738
30739/*! @name Object
30740@{ */
30741/// @}
30742
30743
30744/*! @name Editing
30745@{ */
30746/// @}
30747
30748
30749/*! @name Persistence
30750@{ */
30751/// @}
30752
30753/*!
30754@brief What type is the importing asset
30755*/
30756string assetType;
30757/*!
30758@brief What is the source file path of the importing asset
30759*/
30760filename filePath;
30761/*!
30762@brief What is the asset's name
30763*/
30764string AssetName;
30765/*!
30766@brief What is the original, unmodified by processing, asset name
30767*/
30768string cleanAssetName;
30769/*!
30770@brief What is the current status of this asset item in it's import process
30771*/
30772string status;
30773/*!
30774@brief If there is a warning or error status, what type is the condition for this asset item
30775*/
30776string statusType;
30777/*!
30778@brief What is the articulated information of the status of the asset. Contains the error or warning log data
30779*/
30780string statusInfo;
30781/*!
30782@brief Is the asset item currently flagged as dirty
30783*/
30784bool dirty;
30785/*!
30786@brief Is this asset item marked to be skipped. If it is, it's usually due to being marked as deleted
30787*/
30788bool skip;
30789/*!
30790@brief Has the asset item been processed
30791*/
30792bool processed;
30793/*!
30794@brief Is this specific asset item generated as part of the import process of another item
30795*/
30796bool generatedAsset;
30797/*!
30798@brief What is the ultimate asset taml file path for this import item
30799*/
30800string tamlFilePath;
30801/*!
30802@brief Specific to ImageAsset type. What is the image asset's suffix type. Options are: Albedo, Normal, Roughness, AO, Metalness, ORMConfig
30803*/
30804string imageType;
30805/*!
30806@brief Specific to ShapeAsset type. Processed information about the shape file. Contains numbers and lists of meshes, materials and animations
30807*/
30808GuiTreeViewCtrl shapeInfo;
30809};
30810
30811/*!
30812@brief Rendering Manager responsible for lighting, shadows, and global variables affecing both.
30813
30814Should not be exposed to TorqueScript as a game object, meant for internal use only
30815
30816@ingroup Lighting
30817*/
30818class AdvancedLightBinManager : public RenderBinManager {
30819public:
30820
30821/*! @name Callbacks
30822@{ */
30823/// @}
30824
30825
30826/*! @name Ungrouped
30827@{ */
30828/// @}
30829
30830
30831/*! @name Object
30832@{ */
30833/// @}
30834
30835
30836/*! @name Editing
30837@{ */
30838/// @}
30839
30840
30841/*! @name Persistence
30842@{ */
30843/// @}
30844
30845};
30846
30847/*! UNDOCUMENTED!
30848@ingroup UNDOCUMENTED
30849 */
30850class EditorTool : public SimObject {
30851public:
30852
30853/*! @name Callbacks
30854@{ */
30855/// @}
30856
30857
30858/*! @name Ungrouped
30859@{ */
30860/// @}
30861
30862
30863/*! @name Object
30864@{ */
30865/// @}
30866
30867
30868/*! @name Editing
30869@{ */
30870/// @}
30871
30872
30873/*! @name Persistence
30874@{ */
30875/// @}
30876
30877};
30878
30879/*!
30880@brief Represents a type of ForestItem and parameters for how it is placed when painting with a ForestBrush that contains it.
30881
30882@ingroup Forest
30883*/
30884class ForestBrushElement : public SimObject {
30885public:
30886
30887/*! @name Callbacks
30888@{ */
30889/// @}
30890
30891
30892/*! @name Ungrouped
30893@{ */
30894/// @}
30895
30896
30897/*! @name Object
30898@{ */
30899/// @}
30900
30901
30902/*! @name Editing
30903@{ */
30904/// @}
30905
30906
30907/*! @name Persistence
30908@{ */
30909/// @}
30910
30911
30912/*! @name ForestBrushElement
30913@{ */
30914/*!
30915@brief The type of ForestItem this element holds placement parameters for.
30916*/
30917ForestItemData ForestItemData;
30918/*!
30919@brief The probability that this element will be created during an editor brush stroke is the sum of all element probabilities in the brush divided by the probability of this element.
30920*/
30921float probability;
30922/*!
30923@brief The max rotation in degrees that items will be placed.
30924*/
30925float rotationRange;
30926/*!
30927@brief The minimum random size for each item.
30928*/
30929float scaleMin;
30930/*!
30931@brief The maximum random size of each item.
30932*/
30933float scaleMax;
30934/*!
30935@brief An exponent used to bias between the minimum and maximum random sizes.
30936*/
30937float scaleExponent;
30938/*!
30939@brief Min variation in the sink radius.
30940*/
30941float sinkMin;
30942/*!
30943@brief Max variation in the sink radius.
30944*/
30945float sinkMax;
30946/*!
30947@brief This is the radius used to calculate how much to sink the trunk at its base and is used to sink the tree into the ground when its on a slope.
30948*/
30949float sinkRadius;
30950/*!
30951@brief The min surface slope in degrees this item will be placed on.
30952*/
30953float slopeMin;
30954/*!
30955@brief The max surface slope in degrees this item will be placed on.
30956*/
30957float slopeMax;
30958/*!
30959@brief The min world space elevation this item will be placed.
30960*/
30961float elevationMin;
30962/*!
30963@brief The max world space elevation this item will be placed.
30964*/
30965float elevationMax;
30966/// @}
30967
30968};
30969
30970/*!
30971@brief A control that renders a horizontal or vertical separator with an optional text label (horizontal only)
30972
30973@tsexample
30974new GuiSeparatorCtrl()
30975{
30976   profile = "GuiDefaultProfile";
30977   position = "505 0";
30978   extent = "10 17";
30979   minExtent = "10 17";
30980   canSave = "1";
30981   visible = "1";
30982   horizSizing = "left";
30983};
30984@endtsexample
30985
30986@ingroup GuiControls
30987
30988*/
30989class GuiSeparatorCtrl : public GuiControl {
30990public:
30991
30992/*! @name Callbacks
30993@{ */
30994/// @}
30995
30996/*!
30997@brief Optional text label to display.
30998*/
30999string caption;
31000/*!
31001@brief Orientation of separator.
31002*/
31003GuiSeparatorType type;
31004/*!
31005*/
31006int borderMargin;
31007/*!
31008*/
31009bool invisible;
31010/*!
31011@brief Left margin of text label.
31012*/
31013int leftMargin;
31014
31015/*! @name Layout
31016@{ */
31017/// @}
31018
31019
31020/*! @name Control
31021@{ */
31022/// @}
31023
31024
31025/*! @name ToolTip
31026@{ */
31027/// @}
31028
31029
31030/*! @name Editing
31031@{ */
31032/// @}
31033
31034
31035/*! @name Localization
31036@{ */
31037/// @}
31038
31039
31040/*! @name Ungrouped
31041@{ */
31042/// @}
31043
31044
31045/*! @name Object
31046@{ */
31047/// @}
31048
31049
31050/*! @name Editing
31051@{ */
31052/// @}
31053
31054
31055/*! @name Persistence
31056@{ */
31057/// @}
31058
31059};
31060
31061/*!
31062@brief A container that shows a single child with an optional header bar that can be used to collapse and expand the rollout.
31063
31064A rollout is a container that can be collapsed and expanded using smooth animation.  By default, rollouts will display a header with a caption along the top edge of the control which can be clicked by the user to toggle the collapse state of the rollout.
31065
31066Rollouts will automatically size themselves to exactly fit around their child control.  They will also automatically position their child control in their upper left corner below the header (if present).
31067
31068@note GuiRolloutCtrls will only work correctly with a single child control.  To put multiple controls in a rollout, put them in their own group using a new GuiControl which then can be put inside the rollout.
31069
31070@ingroup GuiContainers
31071*/
31072class GuiRolloutCtrl : public GuiControl {
31073public:
31074/*!
31075@brief Determine whether the rollout is currently expanded, i.e. whether the child control is visible.
31076
31077
31078@return True if the rollout is expanded, false if not.*/
31079bool isExpanded();
31080/*!
31081@brief Collapse the rollout if it is currently expanded.  This will make the rollout's child control invisible.
31082
31083
31084@note The rollout will animate to collapsed state.  To instantly collapse without animation, use instantCollapse().*/
31085void collapse();
31086/*!
31087@brief Expand the rollout if it is currently collapsed.  This will make the rollout's child control visible.
31088
31089
31090@note The rollout will animate to expanded state.  To instantly expand without animation, use instantExpand().*/
31091void expand();
31092/*!
31093@brief Toggle the current collapse state of the rollout.  If it is currently expanded, then collapse it.  If it is currently collapsed, then expand it.
31094
31095*/
31096void toggleCollapse();
31097/*!
31098@brief Toggle the current expansion state of the rollout  If it is currently expanded, then collapse it.  If it is currently collapsed, then expand it.
31099
31100
31101@param instant If true, the rollout will toggle its state without animation.  Otherwise, the rollout will smoothly slide into the opposite state.*/
31102void toggleExpanded( bool instantly=false );
31103/*!
31104@brief Instantly collapse the rollout without animation.  To smoothly slide the rollout to collapsed state, use collapse().
31105
31106*/
31107void instantCollapse();
31108/*!
31109@brief Instantly expand the rollout without animation.  To smoothly slide the rollout to expanded state, use expand().
31110
31111*/
31112void instantExpand();
31113/*!
31114@brief Resize the rollout to exactly fit around its child control.  This can be used to manually trigger a recomputation of the rollout size.
31115
31116*/
31117void sizeToContents();
31118
31119/*! @name Callbacks
31120@{ */
31121/*!
31122@brief Called when the user right-clicks on the rollout's header.  This is useful for implementing context menus for rollouts.
31123
31124*/
31125void onHeaderRightClick();
31126/*!
31127@brief Called when the rollout is expanded.
31128
31129*/
31130void onExpanded();
31131/*!
31132@brief Called when the rollout is collapsed.
31133
31134*/
31135void onCollapsed();
31136/// @}
31137
31138
31139/*! @name Rollout
31140@{ */
31141/*!
31142@brief Text label to display on the rollout header.
31143*/
31144string caption;
31145/*!
31146@brief Margin to put around child control.
31147*/
31148RectI margin;
31149/*!
31150@brief Default height of the client area.  This is used when no child control has been added to the rollout.
31151*/
31152int defaultHeight;
31153/*!
31154@brief The current rollout expansion state.
31155*/
31156bool expanded;
31157/*!
31158@brief Whether the rollout can be collapsed by clicking its header.
31159*/
31160bool clickCollapse;
31161/*!
31162@brief Whether to render the rollout header.
31163
31164
31165@note If this is false, the user cannot toggle the rollout state with the mouse.
31166*/
31167bool hideHeader;
31168/*!
31169@brief Whether to automatically collapse sibling rollouts.
31170
31171
31172If this is true, the rollout will automatically collapse all sibling rollout controls when it is expanded.  If this is false, the auto-collapse behavior can be triggered by CTRL (CMD on MAC) clicking the rollout header.  CTRL/CMD clicking also works if this is false, in which case the auto-collapsing of sibling controls will be temporarily deactivated.
31173*/
31174bool autoCollapseSiblings;
31175/// @}
31176
31177
31178/*! @name Layout
31179@{ */
31180/// @}
31181
31182
31183/*! @name Control
31184@{ */
31185/// @}
31186
31187
31188/*! @name ToolTip
31189@{ */
31190/// @}
31191
31192
31193/*! @name Editing
31194@{ */
31195/// @}
31196
31197
31198/*! @name Localization
31199@{ */
31200/// @}
31201
31202
31203/*! @name Ungrouped
31204@{ */
31205/// @}
31206
31207
31208/*! @name Object
31209@{ */
31210/// @}
31211
31212
31213/*! @name Editing
31214@{ */
31215/// @}
31216
31217
31218/*! @name Persistence
31219@{ */
31220/// @}
31221
31222};
31223
31224/*!
31225@brief A datablock that describes an afxCamera.
31226
31227@ingroup afxMisc
31228@ingroup AFX
31229@ingroup Datablocks
31230
31231*/
31232class afxCameraData : public ShapeBaseData {
31233public:
31234
31235/*! @name Callbacks
31236@{ */
31237/// @}
31238
31239
31240/*! @name Shadows
31241@{ */
31242/// @}
31243
31244
31245/*! @name Render
31246@{ */
31247/// @}
31248
31249
31250/*! @name Destruction
31251Parameters related to the destruction effects of this object.
31252@{ */
31253/// @}
31254
31255
31256/*! @name Physics
31257@{ */
31258/// @}
31259
31260
31261/*! @name Damage/Energy
31262@{ */
31263/// @}
31264
31265
31266/*! @name Camera
31267The settings used by the shape when it is the camera.
31268@{ */
31269/// @}
31270
31271
31272/*! @name Misc
31273@{ */
31274/// @}
31275
31276
31277/*! @name Reflection
31278@{ */
31279/// @}
31280
31281
31282/*! @name Scripting
31283@{ */
31284/// @}
31285
31286
31287/*! @name Ungrouped
31288@{ */
31289/// @}
31290
31291
31292/*! @name Object
31293@{ */
31294/// @}
31295
31296
31297/*! @name Editing
31298@{ */
31299/// @}
31300
31301
31302/*! @name Persistence
31303@{ */
31304/// @}
31305
31306};
31307
31308/*!
31309@brief Datablock base class used by choreographers.
31310
31311@ingroup afxChoreographers
31312@ingroup AFX
31313@ingroup Datablocks
31314
31315*/
31316class afxChoreographerData : public GameBaseData {
31317public:
31318
31319/*! @name Callbacks
31320@{ */
31321/// @}
31322
31323/*!
31324@brief ...
31325*/
31326bool execOnNewClients;
31327/*!
31328@brief ...
31329*/
31330char echoPacketUsage;
31331/*!
31332@brief ...
31333*/
31334filename clientScriptFile;
31335/*!
31336@brief ...
31337*/
31338string clientInitFunction;
31339
31340/*! @name Scripting
31341@{ */
31342/// @}
31343
31344
31345/*! @name Ungrouped
31346@{ */
31347/// @}
31348
31349
31350/*! @name Object
31351@{ */
31352/// @}
31353
31354
31355/*! @name Editing
31356@{ */
31357/// @}
31358
31359
31360/*! @name Persistence
31361@{ */
31362/// @}
31363
31364};
31365
31366/*!
31367@brief A datablock baseclass for afxEffectWrapperData and afxEffectGroupData.
31368
31369Not intended to be used directly, afxEffectBaseData exists to provide base member variables and generic functionality for the derived classes afxEffectWrapperData and afxEffectGroupData.
31370
31371@see afxEffectWrapperData
31372
31373@see afxEffectGroupData
31374
31375@ingroup afxEffects
31376@ingroup AFX
31377@ingroup Datablocks
31378
31379*/
31380class afxEffectBaseData : public GameBaseData {
31381public:
31382
31383/*! @name Callbacks
31384@{ */
31385/// @}
31386
31387
31388/*! @name Scripting
31389@{ */
31390/// @}
31391
31392
31393/*! @name Ungrouped
31394@{ */
31395/// @}
31396
31397
31398/*! @name Object
31399@{ */
31400/// @}
31401
31402
31403/*! @name Editing
31404@{ */
31405/// @}
31406
31407
31408/*! @name Persistence
31409@{ */
31410/// @}
31411
31412};
31413
31414/*!
31415@brief A datablock that describes an Effect Wrapper.
31416
31417Conceptually an effect wrapper encloses a building-block effect and acts as a handle for adding the effect to a choreographer. Effect wrapper fields primarily deal with effect timing, constraints, and conditional effect execution.
31418
31419@see afxEffectBaseData
31420
31421@see afxEffectGroupData
31422
31423@ingroup afxEffects
31424@ingroup AFX
31425@ingroup Datablocks
31426
31427*/
31428class afxEffectWrapperData : public afxEffectBaseData {
31429public:
31430
31431/*! @name Callbacks
31432@{ */
31433/// @}
31434
31435/*!
31436@brief ...
31437*/
31438SimDataBlock effect;
31439/*!
31440@brief ...
31441*/
31442string effectName;
31443/*!
31444@brief ...
31445*/
31446string constraint;
31447/*!
31448@brief ...
31449*/
31450string posConstraint;
31451/*!
31452@brief ...
31453*/
31454string posConstraint2;
31455/*!
31456@brief ...
31457*/
31458string orientConstraint;
31459/*!
31460@brief ...
31461*/
31462string lifeConstraint;
31463/*!
31464@brief ...
31465*/
31466bool isConstraintSrc;
31467/*!
31468@brief ...
31469*/
31470bool ghostIsConstraintSrc;
31471/*!
31472@brief ...
31473*/
31474float delay;
31475/*!
31476@brief ...
31477*/
31478float lifetime;
31479/*!
31480@brief ...
31481*/
31482float fadeInTime;
31483/*!
31484@brief ...
31485*/
31486float residueLifetime;
31487/*!
31488@brief ...
31489*/
31490Point2F fadeInEase;
31491/*!
31492@brief ...
31493*/
31494Point2F fadeOutEase;
31495/*!
31496@brief ...
31497*/
31498float lifetimeBias;
31499/*!
31500@brief ...
31501*/
31502float fadeOutTime;
31503/*!
31504@brief ...
31505*/
31506float rateFactor;
31507/*!
31508@brief ...
31509*/
31510float scaleFactor;
31511/*!
31512@brief ...
31513*/
31514bool isLooping;
31515/*!
31516@brief ...
31517*/
31518int LoopCount;
31519/*!
31520@brief ...
31521*/
31522float loopGapTime;
31523/*!
31524@brief ...
31525*/
31526bool ignoreTimeFactor;
31527/*!
31528@brief ...
31529*/
31530bool propagateTimeFactor;
31531/*!
31532@brief ...
31533*/
31534bool effectEnabled;
31535/*!
31536@brief ...
31537*/
31538ByteRange rankingRange;
31539/*!
31540@brief ...
31541*/
31542ByteRange levelOfDetailRange;
31543/*!
31544@brief ...
31545*/
31546int lifeConditions;
31547/*!
31548@brief ...
31549*/
31550int execConditions[ 4 ];
31551/*!
31552@brief ...
31553*/
31554int execOffConditions[ 4 ];
31555/*!
31556@brief ...
31557*/
31558afxXM_BaseData xfmModifiers[ 32 ];
31559/*!
31560@brief ...
31561*/
31562Box3F forcedBBox;
31563/*!
31564@brief ...
31565*/
31566bool updateForcedBBox;
31567/*!
31568@brief ...
31569*/
31570char sortPriority;
31571/*!
31572@brief ...
31573*/
31574Point3F direction;
31575/*!
31576@brief ...
31577*/
31578float speed;
31579/*!
31580@brief ...
31581*/
31582float mass;
31583/*!
31584@brief ...
31585*/
31586bool borrowAltitudes;
31587/*!
31588@brief ...
31589*/
31590string visibilityKeys;
31591/*!
31592@brief ...
31593*/
31594int groupIndex;
31595/*!
31596@brief ...
31597*/
31598int inheritGroupTiming;
31599
31600/*! @name Scripting
31601@{ */
31602/// @}
31603
31604
31605/*! @name Ungrouped
31606@{ */
31607/// @}
31608
31609
31610/*! @name Object
31611@{ */
31612/// @}
31613
31614
31615/*! @name Editing
31616@{ */
31617/// @}
31618
31619
31620/*! @name Persistence
31621@{ */
31622/// @}
31623
31624};
31625
31626/*!
31627@brief An Effect Wrapper as defined by an afxEffectWrapperData datablock.
31628
31629Conceptually an effect wrapper encloses a building-block effect and acts as a handle for adding the effect to a choreographer. Effect wrapper fields primarily deal with effect timing, constraints, and conditional effect execution.
31630
31631Not intended to be used directly, afxEffectWrapper is an internal baseclass used to implement effect-specific adapter classes.
31632
31633@ingroup afxEffects
31634@ingroup AFX
31635
31636*/
31637class afxEffectWrapper : public SimObject {
31638public:
31639
31640/*! @name Callbacks
31641@{ */
31642/// @}
31643
31644/*!
31645@brief ...
31646*/
31647float liveScaleFactor;
31648/*!
31649@brief ...
31650*/
31651float liveFadeFactor;
31652
31653/*! @name Ungrouped
31654@{ */
31655/// @}
31656
31657
31658/*! @name Object
31659@{ */
31660/// @}
31661
31662
31663/*! @name Editing
31664@{ */
31665/// @}
31666
31667
31668/*! @name Persistence
31669@{ */
31670/// @}
31671
31672};
31673
31674/*!
31675@brief Defines a particular magic-missile type. (Use with afxMagicSpellData.)
31676@tsexample
31677datablock afxMagicMissileData(Fireball_MM)
31678{
31679  muzzleVelocity = 50;
31680  velInheritFactor = 0;
31681  lifetime = 20000;
31682  isBallistic = true;
31683  ballisticCoefficient = 0.85;
31684  gravityMod = 0.05;
31685  isGuided = true;
31686  precision = 30;
31687  trackDelay = 7;
31688  launchOffset = "0 0 43.7965";
31689  launchOnServerSignal = true;
31690};
31691@endtsexample
31692@ingroup AFX
31693
31694*/
31695class afxMagicMissileData : public GameBaseData {
31696public:
31697
31698/*! @name Callbacks
31699@{ */
31700/// @}
31701
31702/*!
31703*/
31704ParticleEmitterData ParticleEmitter;
31705/*!
31706*/
31707ParticleEmitterData particleWaterEmitter;
31708/*!
31709*/
31710filename projectileShapeName;
31711/*!
31712*/
31713Point3F scale;
31714/*!
31715*/
31716SFXTrack sound;
31717/*!
31718*/
31719SplashData Splash;
31720/*!
31721*/
31722LightDescription lightDesc;
31723/*!
31724*/
31725bool isBallistic;
31726/*!
31727*/
31728float muzzleVelocity;
31729/*!
31730*/
31731int lifetime;
31732/*!
31733*/
31734float gravityMod;
31735/*!
31736*/
31737filename missileShapeName;
31738/*!
31739*/
31740Point3F missileShapeScale;
31741/*!
31742*/
31743Point3F startingVelocityVector;
31744/*!
31745*/
31746bool isGuided;
31747/*!
31748*/
31749float precision;
31750/*!
31751*/
31752int trackDelay;
31753/*!
31754*/
31755float ballisticCoefficient;
31756/*!
31757*/
31758int collisionMask;
31759/*!
31760*/
31761bool followTerrain;
31762/*!
31763*/
31764float followTerrainHeight;
31765/*!
31766*/
31767float followTerrainAdjustRate;
31768/*!
31769*/
31770int followTerrainAdjustDelay;
31771/*!
31772*/
31773float acceleration;
31774/*!
31775*/
31776int accelDelay;
31777/*!
31778*/
31779int accelLifetime;
31780/*!
31781*/
31782string launchNode;
31783/*!
31784*/
31785Point3F launchOffset;
31786/*!
31787*/
31788Point3F launchOffsetServer;
31789/*!
31790*/
31791Point3F launchOffsetClient;
31792/*!
31793*/
31794Point3F launchNodeOffset;
31795/*!
31796*/
31797float launchAimPitch;
31798/*!
31799*/
31800float launchAimPan;
31801/*!
31802*/
31803string launchConstraintServer;
31804/*!
31805*/
31806string launchConstraintClient;
31807/*!
31808*/
31809bool echoLaunchOffset;
31810/*!
31811*/
31812floatList wiggleMagnitudes;
31813/*!
31814*/
31815floatList wiggleSpeeds;
31816/*!
31817*/
31818string wiggleAxis;
31819/*!
31820*/
31821float hoverAltitude;
31822/*!
31823*/
31824float hoverAttackDistance;
31825/*!
31826*/
31827float hoverAttackGradient;
31828/*!
31829*/
31830int hovertime;
31831/*!
31832*/
31833bool reverseTargeting;
31834/*!
31835*/
31836int casterSafetyTime;
31837
31838/*! @name Scripting
31839@{ */
31840/// @}
31841
31842
31843/*! @name Ungrouped
31844@{ */
31845/// @}
31846
31847
31848/*! @name Object
31849@{ */
31850/// @}
31851
31852
31853/*! @name Editing
31854@{ */
31855/// @}
31856
31857
31858/*! @name Persistence
31859@{ */
31860/// @}
31861
31862};
31863
31864/*! UNDOCUMENTED!
31865@ingroup UNDOCUMENTED
31866 */
31867class afxRenderHighlightMgr : public RenderTexTargetBinManager {
31868public:
31869
31870/*! @name Callbacks
31871@{ */
31872/// @}
31873
31874
31875/*! @name Ungrouped
31876@{ */
31877/// @}
31878
31879
31880/*! @name Object
31881@{ */
31882/// @}
31883
31884
31885/*! @name Editing
31886@{ */
31887/// @}
31888
31889
31890/*! @name Persistence
31891@{ */
31892/// @}
31893
31894};
31895
31896/*!
31897@brief A class that manages certain AFX effects that can persist for long durations.
31898
31899A class that manages certain AFX effects that can persist much longer than the duration of choreographers.
31900@ingroup AFX
31901
31902*/
31903class afxResidueMgr : public GameBase {
31904public:
31905
31906/*! @name Callbacks
31907@{ */
31908/// @}
31909
31910/*!
31911@brief Disables rendering of all instances of this type.
31912
31913
31914@ingroup UNDOCUMENTED
31915*/
31916static bool isRenderable;
31917/*!
31918@brief Disables selection of all instances of this type.
31919
31920
31921@ingroup UNDOCUMENTED
31922*/
31923static bool isSelectable;
31924
31925/*! @name Game
31926@{ */
31927/// @}
31928
31929
31930/*! @name GameObject
31931@{ */
31932/// @}
31933
31934
31935/*! @name Transform
31936@{ */
31937/// @}
31938
31939
31940/*! @name Editing
31941@{ */
31942/// @}
31943
31944
31945/*! @name Mounting
31946@{ */
31947/// @}
31948
31949
31950/*! @name Ungrouped
31951@{ */
31952/// @}
31953
31954
31955/*! @name Object
31956@{ */
31957/// @}
31958
31959
31960/*! @name Editing
31961@{ */
31962/// @}
31963
31964
31965/*! @name Persistence
31966@{ */
31967/// @}
31968
31969};
31970
31971/*!
31972@brief A render bin for zodiac rendering on GroundPlane objects.
31973
31974This bin renders instances of AFX zodiac effects onto GroundPlane surfaces.
31975
31976@ingroup RenderBin
31977@ingroup AFX
31978
31979*/
31980class afxZodiacGroundPlaneRenderer : public RenderBinManager {
31981public:
31982
31983/*! @name Callbacks
31984@{ */
31985/// @}
31986
31987
31988/*! @name Ungrouped
31989@{ */
31990/// @}
31991
31992
31993/*! @name Object
31994@{ */
31995/// @}
31996
31997
31998/*! @name Editing
31999@{ */
32000/// @}
32001
32002
32003/*! @name Persistence
32004@{ */
32005/// @}
32006
32007};
32008
32009/*!
32010@brief A render bin for zodiac rendering on MeshRoad objects.
32011
32012This bin renders instances of AFX zodiac effects onto MeshRoad surfaces.
32013
32014@ingroup RenderBin
32015@ingroup AFX
32016
32017*/
32018class afxZodiacMeshRoadRenderer : public RenderBinManager {
32019public:
32020
32021/*! @name Callbacks
32022@{ */
32023/// @}
32024
32025
32026/*! @name Ungrouped
32027@{ */
32028/// @}
32029
32030
32031/*! @name Object
32032@{ */
32033/// @}
32034
32035
32036/*! @name Editing
32037@{ */
32038/// @}
32039
32040
32041/*! @name Persistence
32042@{ */
32043/// @}
32044
32045};
32046
32047/*!
32048@brief A render bin for zodiac rendering on polysoup TSStatic objects.
32049
32050This bin renders instances of AFX zodiac effects onto polysoup TSStatic surfaces.
32051
32052@ingroup RenderBin
32053@ingroup AFX
32054
32055*/
32056class afxZodiacPolysoupRenderer : public RenderBinManager {
32057public:
32058
32059/*! @name Callbacks
32060@{ */
32061/// @}
32062
32063
32064/*! @name Ungrouped
32065@{ */
32066/// @}
32067
32068
32069/*! @name Object
32070@{ */
32071/// @}
32072
32073
32074/*! @name Editing
32075@{ */
32076/// @}
32077
32078
32079/*! @name Persistence
32080@{ */
32081/// @}
32082
32083};
32084
32085/*!
32086@brief A render bin for zodiac rendering on Terrain objects.
32087
32088This bin renders instances of AFX zodiac effects onto Terrain surfaces.
32089
32090@ingroup RenderBin
32091@ingroup AFX
32092
32093*/
32094class afxZodiacTerrainRenderer : public RenderBinManager {
32095public:
32096
32097/*! @name Callbacks
32098@{ */
32099/// @}
32100
32101
32102/*! @name Ungrouped
32103@{ */
32104/// @}
32105
32106
32107/*! @name Object
32108@{ */
32109/// @}
32110
32111
32112/*! @name Editing
32113@{ */
32114/// @}
32115
32116
32117/*! @name Persistence
32118@{ */
32119/// @}
32120
32121};
32122
32123/*!
32124@brief A datablock that specifies an Animation Clip effect.
32125
32126An Animation Clip forces a target ShapeBase-derived object, such as Player or AIPlayer, to perform a particular animation sequence. Animation Clip does not supply any new animation data, but simply selects, by name, a sequence that is already defined in the target. Animation Clip can also target afxModel effects within the same choreographer.
32127
32128The target of an Animation Clip is the constraint source object specified by the posConstraint field of the enclosing effect wrapper. The target must be a ShapeBase-derived object, or an afxModel and it must contain an animation sequence with the same name as the clipName field.
32129
32130Animation Clip controls the rate of animation playback and can even play a sequence in reverse. When an Animation Clip selects a blended animation sequence, it is mixed with the current animation instead of replacing it. Animation Clips can be used to activate multiple, overlapping blend sequences.
32131
32132Normally when an Animation Clip is applied to a user-controlled Player, any interactive user actions will override the animation selected by the clip, but Animation Clips can be configured to temporarily block out some user actions for the duration of the clip.
32133
32134@ingroup afxEffects
32135@ingroup AFX
32136@ingroup Datablocks
32137
32138*/
32139class afxAnimClipData : public GameBaseData {
32140public:
32141
32142/*! @name Callbacks
32143@{ */
32144/// @}
32145
32146/*!
32147@brief The name of an animation sequence to be played by a ShapeBase-derived object to which this effect is constrained. Also works on afxModel effects.
32148
32149default: ""
32150
32151*/
32152string clipName;
32153/*!
32154@brief The desired playback speed for the sequence. A value of 1.0 indicates forward playback at a normal rate. Negative values cause the sequence to play backwards.
32155
32156default: 1.0
32157
32158*/
32159float rate;
32160/*!
32161@brief Sets a starting offset for the selected animation clip. It directly specifies an animation thread position in the 0.0 to 1.0 range as a fraction of the clip's duration.
32162
32163default: 1.0
32164
32165*/
32166float posOffset;
32167/*!
32168@brief The duration in which the active animation overlaps and blends into the sequence selected by the animation clip.
32169
32170default: 0.12
32171
32172*/
32173float transitionTime;
32174/*!
32175@brief Specifies if the animation clip should not be applied to corpses or anything else with a disabled damage state.
32176
32177default: false
32178
32179*/
32180bool ignoreCorpse;
32181/*!
32182@brief Specifies if the animation clip should not be applied to living objects or anything else with an enabled damage state.
32183
32184default: false
32185
32186*/
32187bool ignoreLiving;
32188/*!
32189@brief Indicates if the animation clip is a death animation. If the target object dies during the effect, this will prevent the object from playing another standard death animation after this clip finishes.
32190
32191default: false
32192
32193*/
32194bool treatAsDeathAnim;
32195/*!
32196@brief Indicates if user control of a Player should be temporarily blocked during the clip. (See afxAnimLockData.)
32197
32198default: false
32199
32200*/
32201bool lockAnimation;
32202/*!
32203@brief If true, the clip will not be played on targets that are the control object and the camera is in first person mode.
32204
32205default: false
32206
32207*/
32208bool ignoreFirstPerson;
32209/*!
32210@brief If true, the clip will not be played on targets that are the control object and the camera is in third person mode.
32211
32212default: false
32213
32214*/
32215bool ignoreThirdPerson;
32216/*!
32217@brief A synonym for ignoreLiving.
32218*/
32219bool ignoreDisabled;
32220/*!
32221@brief A synonym for ignoreCorpse.
32222*/
32223bool ignoreEnabled;
32224
32225/*! @name Scripting
32226@{ */
32227/// @}
32228
32229
32230/*! @name Ungrouped
32231@{ */
32232/// @}
32233
32234
32235/*! @name Object
32236@{ */
32237/// @}
32238
32239
32240/*! @name Editing
32241@{ */
32242/// @}
32243
32244
32245/*! @name Persistence
32246@{ */
32247/// @}
32248
32249};
32250
32251/*!
32252@brief A datablock that specifies an Animation Lock effect.
32253
32254Animation Lock is used to temporarily lock out user-controlled Player actions, usually while an Animation Clip is concurrently playing. Animation Clips can already do this, but must lock out user actions for the entire clip length. Sometimes you only want to block user actions for a short section of a longer playing animation, such as the part where the Player is thrown into the air from an impact. With Animation Lock, you can set a specific timespan for when user actions are blocked, independent of any Animation Clip timing.
32255
32256The target of an Animation Lock is the constraint source object specified by the posConstraint field of the enclosing effect wrapper. The target must be a Player, a subclass of Player, or an afxModel.
32257
32258The timing of the Animation Lock is determined by the timing fields of the enclosing effect wrapper.
32259
32260Locking behavior timing is set by fields of the enclosing effect wrapper, so afxAnimLockData does not require any fields. However, TorqueScript syntax disallows the declaration of an empty datablock. Therefore, it is recommended that you set a dynamic field named 'priority' to zero in the body of the datablock as a workaround to this limitation.
32261
32262@ingroup afxEffects
32263@ingroup AFX
32264@ingroup Datablocks
32265
32266*/
32267class afxAnimLockData : public GameBaseData {
32268public:
32269
32270/*! @name Callbacks
32271@{ */
32272/// @}
32273
32274
32275/*! @name Scripting
32276@{ */
32277/// @}
32278
32279
32280/*! @name Ungrouped
32281@{ */
32282/// @}
32283
32284
32285/*! @name Object
32286@{ */
32287/// @}
32288
32289
32290/*! @name Editing
32291@{ */
32292/// @}
32293
32294
32295/*! @name Persistence
32296@{ */
32297/// @}
32298
32299};
32300
32301/*!
32302@brief A datablock that specifies an Area Damage effect.
32303
32304An Area Damage effect is useful for assigning area damage with unusual timing that must be synchronized with other effects. Negative damage amounts can be used for healing effects.
32305
32306The primary difference between afxAreaDamageData and afxDamageData, which is also capable of inflicting area damage, is that afxAreaDamageData effects calculate the area damage in C++ code rather than calling out to the script function radiusDamage(). In cases where area damage needs to be inflicted repeatedly or in areas crowded with many targets, afxAreaDamageData is likely to get better performance.
32307
32308@ingroup afxEffects
32309@ingroup AFX
32310@ingroup Datablocks
32311
32312*/
32313class afxAreaDamageData : public GameBaseData {
32314public:
32315
32316/*! @name Callbacks
32317@{ */
32318/// @}
32319
32320/*!
32321@brief An arbitrary string which is passed as an argument to a spell's onDamage() script method. It is used to classify a type of damage such as 'melee', 'magical', or 'fire'.
32322*/
32323string flavor;
32324/*!
32325@brief An amount of area damage to inflict on a target. Objects within half the radius receive full damage which then diminishes out to the full distance of the specified radius.
32326*/
32327float damage;
32328/*!
32329@brief Radius centered at the effect position in which damage will be applied.
32330*/
32331float radius;
32332/*!
32333@brief Specifies an amount of force to apply to damaged objects. Objects within half the radius receive full impulse which then diminishes out to the full distance of the specified radius.
32334*/
32335float impulse;
32336/*!
32337@brief When true, the onInflictedAreaDamage() method of the damaged object will be called to notify it of the damage. This is useful for starting some effects or action that responds to the damage.
32338*/
32339bool notifyDamageSource;
32340/*!
32341@brief When true, the object specified as the effect's primary position constraint will not receive any damage.
32342*/
32343bool excludeConstraintObject;
32344
32345/*! @name Scripting
32346@{ */
32347/// @}
32348
32349
32350/*! @name Ungrouped
32351@{ */
32352/// @}
32353
32354
32355/*! @name Object
32356@{ */
32357/// @}
32358
32359
32360/*! @name Editing
32361@{ */
32362/// @}
32363
32364
32365/*! @name Persistence
32366@{ */
32367/// @}
32368
32369};
32370
32371/*!
32372@brief A datablock that specifies an Audio Bank effect.
32373
32374afxAudioBank is very similar to the stock Torque SFXProfile datablock but it allows specification of up to 32 different sound files. The sound that actually plays is determined by the playIndex field.
32375
32376afxAudioBank is most useful when used in combination with field substitutions, whereby a substitution statement assigned to playIndex selects a different sound (perhaps randomly) each time the effect is used.
32377
32378@ingroup afxEffects
32379@ingroup AFX
32380@ingroup Datablocks
32381
32382*/
32383class afxAudioBank : public SimDataBlock {
32384public:
32385
32386/*! @name Callbacks
32387@{ */
32388/// @}
32389
32390/*!
32391@brief A filesystem path to the folder containing the sound files specified by the filenames[] field. All sound files used in a single AudioBank must be located in the same folder.
32392*/
32393filename Path;
32394/*!
32395@brief Up to 32 names of sound files found in the path folder. The sound that is actually played by an Audio Bank effect is determined by the playIndex field.
32396*/
32397string filenames[ 32 ];
32398/*!
32399@brief SFXDescription datablock to use with this set of sounds.
32400*/
32401SFXDescription description;
32402/*!
32403@brief If set to true, file is pre-loaded, otherwise it is loaded on-demand.
32404*/
32405bool preload;
32406/*!
32407@brief An array index that selects a sound to play from the filenames[] field. Values outside of the range of assigned filename[] entries will not play any sound.
32408*/
32409int playIndex;
32410
32411/*! @name Ungrouped
32412@{ */
32413/// @}
32414
32415
32416/*! @name Object
32417@{ */
32418/// @}
32419
32420
32421/*! @name Editing
32422@{ */
32423/// @}
32424
32425
32426/*! @name Persistence
32427@{ */
32428/// @}
32429
32430};
32431
32432/*!
32433@brief A datablock that specifies a Billboard effect.
32434
32435A Billboard effect is a textured quadrangle which is always aligned to face towards the camera. It is much like a single static particle and is rendered in a similar fashion.
32436
32437@ingroup afxEffects
32438@ingroup AFX
32439@ingroup Datablocks
32440
32441*/
32442class afxBillboardData : public GameBaseData {
32443public:
32444
32445/*! @name Callbacks
32446@{ */
32447/// @}
32448
32449/*!
32450@brief The color assigned to the quadrangle geometry. The way it combines with the given texture varies according to the setting of the textureFunction field.
32451*/
32452LinearColorF color;
32453/*!
32454@brief An image to use as the billboard's texture.
32455*/
32456filename texture;
32457/*!
32458@brief A value-pair that specifies the horizontal and vertical dimensions of the billboard in scene units.
32459*/
32460Point2F dimensions;
32461/*!
32462@brief An array of four value-pairs that specify the UV texture coordinates for the four corners of the billboard's quadrangle.
32463*/
32464Point2F textureCoords[ 4 ];
32465/*!
32466@brief Selects a common blend factor preset. When set to 'user', srcBlendFactor and dstBlendFactor can be used to set additional blend factor combinations.
32467
32468Possible values: normal, additive, subtractive, premultalpha, or user.
32469*/
32470afxBillboard_BlendStyle blendStyle;
32471/*!
32472@brief Specifies source blend factor when blendStyle is set to 'user'.
32473
32474Possible values: GFXBlendZero, GFXBlendOne, GFXBlendDestColor, GFXBlendInvDestColor, GFXBlendSrcAlpha, GFXBlendInvSrcAlpha, GFXBlendDestAlpha, GFXBlendInvDestAlpha, or GFXBlendSrcAlphaSat
32475*/
32476GFXBlend srcBlendFactor;
32477/*!
32478@brief Specifies destination blend factor when blendStyle is set to 'user'.
32479
32480Possible values: GFXBlendZero, GFXBlendOne, GFXBlendSrcColor, GFXBlendInvSrcColor, GFXBlendSrcAlpha, GFXBlendInvSrcAlpha, GFXBlendDestAlpha, or GFXBlendInvDestAlpha
32481*/
32482GFXBlend dstBlendFactor;
32483
32484/*! @name Scripting
32485@{ */
32486/// @}
32487
32488
32489/*! @name Ungrouped
32490@{ */
32491/// @}
32492
32493
32494/*! @name Object
32495@{ */
32496/// @}
32497
32498
32499/*! @name Editing
32500@{ */
32501/// @}
32502
32503
32504/*! @name Persistence
32505@{ */
32506/// @}
32507
32508};
32509
32510/*!
32511@brief A Billboard effect as defined by an afxBillboardData datablock.
32512
32513A Billboard effect is a textured quadrangle which is always aligned to face towards the camera. It is much like a single static particle and is rendered in a similar fashion.
32514@ingroup afxEffects
32515@ingroup AFX
32516
32517*/
32518class afxBillboard : public GameBase {
32519public:
32520
32521/*! @name Callbacks
32522@{ */
32523/// @}
32524
32525/*!
32526@brief Disables rendering of all instances of this type.
32527
32528
32529@ingroup UNDOCUMENTED
32530*/
32531static bool isRenderable;
32532/*!
32533@brief Disables selection of all instances of this type.
32534
32535
32536@ingroup UNDOCUMENTED
32537*/
32538static bool isSelectable;
32539
32540/*! @name Game
32541@{ */
32542/// @}
32543
32544
32545/*! @name GameObject
32546@{ */
32547/// @}
32548
32549
32550/*! @name Transform
32551@{ */
32552/// @}
32553
32554
32555/*! @name Editing
32556@{ */
32557/// @}
32558
32559
32560/*! @name Mounting
32561@{ */
32562/// @}
32563
32564
32565/*! @name Ungrouped
32566@{ */
32567/// @}
32568
32569
32570/*! @name Object
32571@{ */
32572/// @}
32573
32574
32575/*! @name Editing
32576@{ */
32577/// @}
32578
32579
32580/*! @name Persistence
32581@{ */
32582/// @}
32583
32584};
32585
32586/*!
32587@brief A datablock that specifies a Camera Puppet effect.
32588
32589A Camera Puppet effect is used to control the position and orientation of the camera using the AFX constraint system. Camera Puppet effects are useful for creating small cut-scenes and can add a lot of visual drama to a spell or effectron effect.
32590
32591Effective use of Camera Puppet effects require a fairly advanced understanding of how Torque cameras work in a server-client context. Care must be taken to prevent client cameras from drifting too far out of sync from the server camera. Otherwise, obvious discontinuities in the motion will result when the Camera Puppet ends and control is restored to the server camera. Scoping problems can also result if a client camera is moved to a location that is inconsistent with the scene scoping done by the server camera.
32592
32593Often it is useful to manage camera controlling in an isolated effectron rather than directly incorporated into a magic-spell. This way the camera controlling effectron can target the specific client associated with the spellcaster. The spellcasting player observes the spell in a dramatic cut-scene-like fashion while other players continue to observe from their own viewing locations.
32594
32595@ingroup afxEffects
32596@ingroup AFX
32597@ingroup Datablocks
32598
32599*/
32600class afxCameraPuppetData : public GameBaseData {
32601public:
32602
32603/*! @name Callbacks
32604@{ */
32605/// @}
32606
32607/*!
32608@brief This field is like the effect-wrapper fields for specifying constraint sources, but here it specifies a target for the camera-puppet effect.
32609*/
32610string cameraSpec;
32611/*!
32612@brief Specifies the networking model used for the camerapuppet effect. The effect can puppet just the server camera, just the client camera, or both.
32613
32614Possible values: $AFX::SERVER_ONLY, $AFX::CLIENT_ONLY, or $AFX::SERVER_AND_CLIENT.
32615*/
32616char networking;
32617
32618/*! @name Scripting
32619@{ */
32620/// @}
32621
32622
32623/*! @name Ungrouped
32624@{ */
32625/// @}
32626
32627
32628/*! @name Object
32629@{ */
32630/// @}
32631
32632
32633/*! @name Editing
32634@{ */
32635/// @}
32636
32637
32638/*! @name Persistence
32639@{ */
32640/// @}
32641
32642};
32643
32644/*!
32645@brief A datablock that specifies a Camera Shake effect.
32646
32647Camera Shake internally utilizes the standard Torque CameraShake class to implement a shaken camera effect.
32648
32649@ingroup afxEffects
32650@ingroup AFX
32651@ingroup Datablocks
32652
32653*/
32654class afxCameraShakeData : public GameBaseData {
32655public:
32656
32657/*! @name Callbacks
32658@{ */
32659/// @}
32660
32661/*!
32662@brief The camera shake frequencies for all three axes: X, Y, Z.
32663*/
32664Point3F Frequency;
32665/*!
32666@brief The camera shake amplitudes for all three axes: X, Y, Z.
32667*/
32668Point3F Amplitude;
32669/*!
32670@brief Radius about the effect position in which shaking will be applied.
32671*/
32672float radius;
32673/*!
32674@brief Magnitude by which shaking decreases over distance to radius.
32675*/
32676float Falloff;
32677
32678/*! @name Scripting
32679@{ */
32680/// @}
32681
32682
32683/*! @name Ungrouped
32684@{ */
32685/// @}
32686
32687
32688/*! @name Object
32689@{ */
32690/// @}
32691
32692
32693/*! @name Editing
32694@{ */
32695/// @}
32696
32697
32698/*! @name Persistence
32699@{ */
32700/// @}
32701
32702};
32703
32704/*!
32705@brief A datablock that specifies a Collision Event effect.
32706
32707MORE NEEDED HERE.
32708@ingroup afxEffects
32709@ingroup AFX
32710@ingroup Datablocks
32711
32712*/
32713class afxCollisionEventData : public GameBaseData {
32714public:
32715
32716/*! @name Callbacks
32717@{ */
32718/// @}
32719
32720/*!
32721@brief ...
32722*/
32723string methodName;
32724/*!
32725@brief ...
32726*/
32727string scriptData;
32728/*!
32729@brief ...
32730*/
32731bool generateTrigger;
32732/*!
32733@brief ...
32734*/
32735char triggerBit;
32736
32737/*! @name Scripting
32738@{ */
32739/// @}
32740
32741
32742/*! @name Ungrouped
32743@{ */
32744/// @}
32745
32746
32747/*! @name Object
32748@{ */
32749/// @}
32750
32751
32752/*! @name Editing
32753@{ */
32754/// @}
32755
32756
32757/*! @name Persistence
32758@{ */
32759/// @}
32760
32761};
32762
32763/*!
32764@brief A datablock that specifies a Console Message effect.
32765
32766Console Message effects are useful for debugging purposes when you want to make sure that an effect with a certain kind of timing is actually getting executed and for evaluating some kinds of field substitutions.
32767
32768@ingroup afxEffects
32769@ingroup AFX
32770@ingroup Datablocks
32771
32772*/
32773class afxConsoleMessageData : public GameBaseData {
32774public:
32775
32776/*! @name Callbacks
32777@{ */
32778/// @}
32779
32780/*!
32781@brief A text message to be displayed when the effect is executed.
32782*/
32783string Message;
32784
32785/*! @name Scripting
32786@{ */
32787/// @}
32788
32789
32790/*! @name Ungrouped
32791@{ */
32792/// @}
32793
32794
32795/*! @name Object
32796@{ */
32797/// @}
32798
32799
32800/*! @name Editing
32801@{ */
32802/// @}
32803
32804
32805/*! @name Persistence
32806@{ */
32807/// @}
32808
32809};
32810
32811/*!
32812@brief A datablock that specifies a Damage effect.
32813
32814A Damage effect is useful for assigning damage with unusual timing that must be synchronized with other effects. They can be used to deal direct damage, radius damage, and damage over time. Negative damage amounts can be used for healing effects.
32815
32816@ingroup afxEffects
32817@ingroup AFX
32818@ingroup Datablocks
32819
32820*/
32821class afxDamageData : public GameBaseData {
32822public:
32823
32824/*! @name Callbacks
32825@{ */
32826/// @}
32827
32828/*!
32829@brief An arbitrary string which is passed as an argument to a spell's onDamage() script method. It can be used to identify which damage effect the damage came from in cases where more than one damage effect is used in a single spell.
32830*/
32831string Label;
32832/*!
32833@brief An arbitrary string which is passed as an argument to a spell's onDamage() script method. It is used to classify a type of damage such as 'melee', 'magical', or 'fire'.
32834*/
32835string flavor;
32836/*!
32837@brief An amount of direct damage to inflict on a target.
32838*/
32839float directDamage;
32840/*!
32841@brief The number of times to inflict the damage specified by directDamage. Values greater than 1 inflict damage over time, with the amount of directDamage repeatedly dealt at evenly spaced intervals over the lifetime of the effect.
32842*/
32843char directDamageRepeats;
32844/*!
32845@brief An amount of area damage to inflict on a target. Objects within half the radius receive full damage which then diminishes out to the full distance of areaDamageRadius.
32846*/
32847float areaDamage;
32848/*!
32849@brief Radius centered at the effect position in which damage will be applied.
32850*/
32851float areaDamageRadius;
32852/*!
32853@brief Specifies an amount of force to apply to damaged objects. Objects within half the radius receive full impulse which then diminishes out to the full distance of areaDamageRadius.
32854*/
32855float areaDamageImpulse;
32856
32857/*! @name Scripting
32858@{ */
32859/// @}
32860
32861
32862/*! @name Ungrouped
32863@{ */
32864/// @}
32865
32866
32867/*! @name Object
32868@{ */
32869/// @}
32870
32871
32872/*! @name Editing
32873@{ */
32874/// @}
32875
32876
32877/*! @name Persistence
32878@{ */
32879/// @}
32880
32881};
32882
32883/*!
32884@brief A datablock that specifies a Foot Switch effect.
32885
32886A Foot Switch effect is used to disable some or all of the standard built-in footstep effects generated by Player objects.
32887
32888Stock Player objects generate footprint decals, footstep sounds, and puffs of particle dust in response to special animation triggers embedded in the Player's dts model. With the help of Phase Effects, AFX can substitute alternatives for these built-in effects. When this is done, it is often preferable to turn off some or all of the built-in footstep effects.
32889
32890Foot Switch effects are only meaningful when the primary position constraint is a Player or Player-derived object.
32891
32892@ingroup afxEffects
32893@ingroup AFX
32894@ingroup Datablocks
32895
32896*/
32897class afxFootSwitchData : public GameBaseData {
32898public:
32899
32900/*! @name Callbacks
32901@{ */
32902/// @}
32903
32904/*!
32905@brief When true, all of a Player's footstep effects are turned off for the duration of the foot-switch effect.
32906*/
32907bool overrideAll;
32908/*!
32909@brief Specifically selects whether the Player's footprint decals are enabled.
32910*/
32911bool overrideDecals;
32912/*!
32913@brief Specifically selects whether the Player's footstep sounds are enabled.
32914*/
32915bool overrideSounds;
32916/*!
32917@brief Specifically selects whether the Player's footstep puffs of dust are enabled.
32918*/
32919bool overrideDust;
32920
32921/*! @name Scripting
32922@{ */
32923/// @}
32924
32925
32926/*! @name Ungrouped
32927@{ */
32928/// @}
32929
32930
32931/*! @name Object
32932@{ */
32933/// @}
32934
32935
32936/*! @name Editing
32937@{ */
32938/// @}
32939
32940
32941/*! @name Persistence
32942@{ */
32943/// @}
32944
32945};
32946
32947/*!
32948@brief A datablock that specifies a Gui Controller effect.
32949
32950A Gui Controller enables effect manipulation of pre-existing gui controls. With a Gui Controller effect, a regular gui control is located by name, made visible during the lifetime of the effect, and potentially repositioned by projecting 3D constraint positions into 2D screen space. In addition, when used with a progress-bar control, (GuiProgressCtrl, afxSpellCastBar, afxStatusBar), the progress-bar will continuously reflect the elapsed progress of the effect over its lifetime.
32951
32952@ingroup afxEffects
32953@ingroup AFX
32954@ingroup Datablocks
32955
32956*/
32957class afxGuiControllerData : public GameBaseData {
32958public:
32959
32960/*! @name Callbacks
32961@{ */
32962/// @}
32963
32964/*!
32965@brief Specifies the name of an existing gui-control.
32966*/
32967string controlName;
32968/*!
32969@brief When true, the gui-control will retain its initial position, otherwise the gui-control position will be continuously updated using a projection of the 3D constraint position into 2D screen coordinates.
32970*/
32971bool preservePosition;
32972/*!
32973@brief If true, the effect will only be applied to a gui-control on the client that matches the controlling-client of the primary position constraint object.
32974*/
32975bool controllingClientOnly;
32976
32977/*! @name Scripting
32978@{ */
32979/// @}
32980
32981
32982/*! @name Ungrouped
32983@{ */
32984/// @}
32985
32986
32987/*! @name Object
32988@{ */
32989/// @}
32990
32991
32992/*! @name Editing
32993@{ */
32994/// @}
32995
32996
32997/*! @name Persistence
32998@{ */
32999/// @}
33000
33001};
33002
33003/*!
33004@brief A datablock that specifies a Gui Text effect.
33005
33006A Gui Text effect, with the help of an existing afxGuiTextHud, can be used to display 2D text effects on the Gui Canvas. Essentially, using Gui Text effects with an afxGuiTextHud is like using the stock GuiShapeNameHud, but with the ability to make additional text elements come and go as effects constrained to the projection of 3D positions onto the 2D screen.
33007
33008@ingroup afxEffects
33009@ingroup AFX
33010@ingroup Datablocks
33011
33012*/
33013class afxGuiTextData : public GameBaseData {
33014public:
33015
33016/*! @name Callbacks
33017@{ */
33018/// @}
33019
33020/*!
33021@brief The literal text to display on the afxGuiTextHud. The center of the text will be placed at the projection of the 3D constraint position into 2D screen space.
33022
33023If the text field is set to the special string, '#shapeName', the shape name of the primary position constraint object will be used. (This is only meaningful if the constraint source is a ShapeBase-derived object.)
33024*/
33025string text;
33026/*!
33027@brief A color value for the text label.
33028*/
33029LinearColorF color;
33030
33031/*! @name Scripting
33032@{ */
33033/// @}
33034
33035
33036/*! @name Ungrouped
33037@{ */
33038/// @}
33039
33040
33041/*! @name Object
33042@{ */
33043/// @}
33044
33045
33046/*! @name Editing
33047@{ */
33048/// @}
33049
33050
33051/*! @name Persistence
33052@{ */
33053/// @}
33054
33055};
33056
33057/*!
33058@brief afxLightData is a legacy datablock which is not supported for T3D.
33059
33060In T3D, instead of afxLightData, use afxT3DPointLightData or afxT3DSpotLightData.
33061@ingroup afxEffects
33062@ingroup AFX
33063@ingroup Datablocks
33064
33065*/
33066class afxLightData : public GameBaseData {
33067public:
33068
33069/*! @name Callbacks
33070@{ */
33071/// @}
33072
33073
33074/*! @name Scripting
33075@{ */
33076/// @}
33077
33078
33079/*! @name Ungrouped
33080@{ */
33081/// @}
33082
33083
33084/*! @name Object
33085@{ */
33086/// @}
33087
33088
33089/*! @name Editing
33090@{ */
33091/// @}
33092
33093
33094/*! @name Persistence
33095@{ */
33096/// @}
33097
33098};
33099
33100/*!
33101@brief A datablock baseclass for afxT3DPointLightData and afxT3DSpotLightData.
33102
33103Not intended to be used directly, afxT3DLightBaseData exists to provide base member variables and generic functionality for the derived classes afxT3DPointLightData and afxT3DSpotLightData.
33104
33105@see afxT3DPointLightData
33106
33107@see afxT3DSpotLightData
33108
33109@see PointLight
33110
33111@see SpotLight
33112
33113@ingroup afxEffects
33114@ingroup AFX
33115@ingroup Datablocks
33116
33117*/
33118class afxT3DLightBaseData : public GameBaseData {
33119public:
33120
33121/*! @name Callbacks
33122@{ */
33123/// @}
33124
33125
33126/*! @name Light
33127@{ */
33128/*!
33129@brief Enables/Disables the object rendering and functionality in the scene.
33130*/
33131bool isEnabled;
33132/*!
33133@brief Changes the base color hue of the light.
33134*/
33135LinearColorF color;
33136/*!
33137@brief Adjusts the lights power, 0 being off completely.
33138*/
33139float brightness;
33140/*!
33141@brief Enables/disables shadow casts by this light.
33142*/
33143bool castShadows;
33144/*!
33145@brief Used for sorting of lights by the light manager. Priority determines if a light has a stronger effect than, those with a lower value
33146*/
33147float priority;
33148/*!
33149@brief Enables/disables a semi-transparent geometry to help visualize the light's range and placement.
33150*/
33151bool localRenderViz;
33152/// @}
33153
33154
33155/*! @name Light Animation
33156@{ */
33157/*!
33158@brief Toggles animation for the light on and off
33159*/
33160bool animate;
33161/*!
33162@brief Datablock containing light animation information (LightAnimData)
33163*/
33164LightAnimData animationType;
33165/*!
33166@brief The length of time in seconds for a single playback of the light animation
33167*/
33168float animationPeriod;
33169/*!
33170@brief The phase used to offset the animation start time to vary the animation of nearby lights.
33171*/
33172float animationPhase;
33173/// @}
33174
33175
33176/*! @name Misc
33177@{ */
33178/*!
33179@brief Datablock containing light flare information (LightFlareData)
33180*/
33181LightFlareData flareType;
33182/*!
33183@brief Globally scales all features of the light flare
33184*/
33185float flareScale;
33186/// @}
33187
33188
33189/*! @name Scripting
33190@{ */
33191/// @}
33192
33193
33194/*! @name Ungrouped
33195@{ */
33196/// @}
33197
33198
33199/*! @name Object
33200@{ */
33201/// @}
33202
33203
33204/*! @name Editing
33205@{ */
33206/// @}
33207
33208
33209/*! @name Persistence
33210@{ */
33211/// @}
33212
33213};
33214
33215/*!
33216@brief A datablock that specifies a Machine Gun effect.
33217
33218Machine Gun is a simple but useful effect for rapidly shooting standard Torque Projectile objects. For performance reasons, keep in mind that each bullet is a separate Projectile object, which is not a very lightweight object.
33219
33220@ingroup afxEffects
33221@ingroup AFX
33222@ingroup Datablocks
33223
33224*/
33225class afxMachineGunData : public GameBaseData {
33226public:
33227
33228/*! @name Callbacks
33229@{ */
33230/// @}
33231
33232/*!
33233@brief A ProjectileData datablock describing the projectile to be launched.
33234*/
33235ProjectileData Projectile;
33236/*!
33237@brief Specifies the number of projectiles fired over a minute of time. A value of 1200 will create 20 projectiles per second.
33238
33239Sample values for real machine guns:
33240    AK-47 = 600, M16 = 750-900, UZI = 600
33241*/
33242int roundsPerMinute;
33243
33244/*! @name Scripting
33245@{ */
33246/// @}
33247
33248
33249/*! @name Ungrouped
33250@{ */
33251/// @}
33252
33253
33254/*! @name Object
33255@{ */
33256/// @}
33257
33258
33259/*! @name Editing
33260@{ */
33261/// @}
33262
33263
33264/*! @name Persistence
33265@{ */
33266/// @}
33267
33268};
33269
33270/*!
33271@brief A datablock that specifies a Model effect.
33272
33273A Model effect is a lightweight client-only geometry object useful for effect-driven props.
33274
33275@ingroup afxEffects
33276@ingroup AFX
33277@ingroup Datablocks
33278
33279*/
33280class afxModelData : public GameBaseData {
33281public:
33282
33283/*! @name Callbacks
33284@{ */
33285/// @}
33286
33287/*!
33288@brief The name of a .dts format file to use for the model.
33289*/
33290filename shapeFile;
33291/*!
33292@brief The name of an animation sequence to play in the model.
33293*/
33294filename sequence;
33295/*!
33296@brief The rate of playback for the sequence.
33297*/
33298float sequenceRate;
33299/*!
33300@brief An offset in seconds indicating a starting point for the animation sequence specified by the sequence field. A rate of 1.0 (rather than sequenceRate) is used to convert from seconds to the thread offset.
33301*/
33302float sequenceOffset;
33303/*!
33304@brief An alpha multiplier used to set maximum opacity of the model.
33305*/
33306float alphaMult;
33307/*!
33308*/
33309float fogMult;
33310/*!
33311@brief Rename one or more texture tags in the model. Texture tags are what link a model's textures to materials.
33312
33313Field should be a string containing space-separated remapping tokens. A remapping token is two names separated by a colon, ':'. The first name should be a texture-tag that exists in the model, while the second is a new name to replace it. The string can have any number of remapping tokens as long as the total string length does not exceed 255.
33314*/
33315string remapTextureTags;
33316/*!
33317@brief Sets whether the model casts a shadow.
33318*/
33319bool shadowEnable;
33320/*!
33321@brief deprecated
33322*/
33323bool useVertexAlpha;
33324/*!
33325@brief deprecated
33326*/
33327int forceOnMaterialFlags;
33328/*!
33329@brief deprecated
33330*/
33331int forceOffMaterialFlags;
33332/*!
33333@brief deprecated
33334*/
33335bool textureFiltering;
33336/*!
33337@brief deprecated
33338*/
33339bool overrideLightingOptions;
33340/*!
33341*/
33342bool receiveSunLight;
33343/*!
33344@brief deprecated
33345*/
33346bool receiveLMLighting;
33347/*!
33348@brief deprecated
33349*/
33350bool useAdaptiveSelfIllumination;
33351/*!
33352@brief deprecated
33353*/
33354bool useCustomAmbientLighting;
33355/*!
33356@brief deprecated
33357*/
33358bool customAmbientSelfIllumination;
33359/*!
33360@brief deprecated
33361*/
33362LinearColorF customAmbientLighting;
33363/*!
33364@brief deprecated
33365*/
33366int shadowSize;
33367/*!
33368@brief deprecated
33369*/
33370float shadowMaxVisibleDistance;
33371/*!
33372@brief deprecated
33373*/
33374float shadowProjectionDistance;
33375/*!
33376@brief deprecated
33377*/
33378float shadowSphereAdjust;
33379
33380/*! @name Scripting
33381@{ */
33382/// @}
33383
33384
33385/*! @name Ungrouped
33386@{ */
33387/// @}
33388
33389
33390/*! @name Object
33391@{ */
33392/// @}
33393
33394
33395/*! @name Editing
33396@{ */
33397/// @}
33398
33399
33400/*! @name Persistence
33401@{ */
33402/// @}
33403
33404};
33405
33406/*!
33407@brief A Model effect as defined by an afxModelData datablock.
33408
33409A Model effect is a lightweight client-only geometry object useful for effect-driven props.
33410@ingroup afxEffects
33411@ingroup AFX
33412
33413*/
33414class afxModel : public GameBase {
33415public:
33416
33417/*! @name Callbacks
33418@{ */
33419/// @}
33420
33421/*!
33422@brief Disables rendering of all instances of this type.
33423
33424
33425@ingroup UNDOCUMENTED
33426*/
33427static bool isRenderable;
33428/*!
33429@brief Disables selection of all instances of this type.
33430
33431
33432@ingroup UNDOCUMENTED
33433*/
33434static bool isSelectable;
33435
33436/*! @name Game
33437@{ */
33438/// @}
33439
33440
33441/*! @name GameObject
33442@{ */
33443/// @}
33444
33445
33446/*! @name Transform
33447@{ */
33448/// @}
33449
33450
33451/*! @name Editing
33452@{ */
33453/// @}
33454
33455
33456/*! @name Mounting
33457@{ */
33458/// @}
33459
33460
33461/*! @name Ungrouped
33462@{ */
33463/// @}
33464
33465
33466/*! @name Object
33467@{ */
33468/// @}
33469
33470
33471/*! @name Editing
33472@{ */
33473/// @}
33474
33475
33476/*! @name Persistence
33477@{ */
33478/// @}
33479
33480};
33481
33482/*!
33483@brief A datablock that specifies a Mooring effect.
33484
33485A Mooring is an invisible effect object which can be positioned and oriented within a scene like other objects. Its main purpose is to serve as a common mount point for other effects within the same choreographer. Typically one uses AFX animation features to create movement for a Mooring and then other effects are bound to it using effect-to-effect constraints (#effect).
33486
33487@ingroup afxEffects
33488@ingroup AFX
33489@ingroup Datablocks
33490
33491*/
33492class afxMooringData : public GameBaseData {
33493public:
33494
33495/*! @name Callbacks
33496@{ */
33497/// @}
33498
33499/*!
33500@brief Specifies whether to display an axis to help visualize the position and orientation of the mooring.
33501*/
33502bool displayAxisMarker;
33503/*!
33504@brief This field is only meaningful for networking settings of SCOPE_ALWAYS and GHOSTABLE. In these cases, client moorings are ghosting a mooring on the server, and trackPosOnly determines if the client moorings need to be updated with the server mooring's complete transform or just its position. If only the position needs to be tracked, setting trackPosOnly to true will reduce the network traffic.
33505*/
33506bool trackPosOnly;
33507/*!
33508@brief Specifies the networking model used for the mooring and should be one of: $AFX::SCOPE_ALWAYS, $AFX::GHOSTABLE, $AFX::SERVER_ONLY, or $AFX::CLIENT_ONLY
33509*/
33510char networking;
33511
33512/*! @name Scripting
33513@{ */
33514/// @}
33515
33516
33517/*! @name Ungrouped
33518@{ */
33519/// @}
33520
33521
33522/*! @name Object
33523@{ */
33524/// @}
33525
33526
33527/*! @name Editing
33528@{ */
33529/// @}
33530
33531
33532/*! @name Persistence
33533@{ */
33534/// @}
33535
33536};
33537
33538/*!
33539@brief A Mooring effect as defined by an afxMooringData datablock.
33540
33541A Mooring is an invisible effect object which can be positioned and oriented within a scene like other objects. Its main purpose is to serve as a common mount point for other effects within the same choreographer. Typically one uses AFX animation features to create movement for a Mooring and then other effects are bound to it using effect-to-effect constraints (#effect).
33542@ingroup afxEffects
33543@ingroup AFX
33544
33545*/
33546class afxMooring : public GameBase {
33547public:
33548
33549/*! @name Callbacks
33550@{ */
33551/// @}
33552
33553/*!
33554@brief Disables rendering of all instances of this type.
33555
33556
33557@ingroup UNDOCUMENTED
33558*/
33559static bool isRenderable;
33560/*!
33561@brief Disables selection of all instances of this type.
33562
33563
33564@ingroup UNDOCUMENTED
33565*/
33566static bool isSelectable;
33567
33568/*! @name Game
33569@{ */
33570/// @}
33571
33572
33573/*! @name GameObject
33574@{ */
33575/// @}
33576
33577
33578/*! @name Transform
33579@{ */
33580/// @}
33581
33582
33583/*! @name Editing
33584@{ */
33585/// @}
33586
33587
33588/*! @name Mounting
33589@{ */
33590/// @}
33591
33592
33593/*! @name Ungrouped
33594@{ */
33595/// @}
33596
33597
33598/*! @name Object
33599@{ */
33600/// @}
33601
33602
33603/*! @name Editing
33604@{ */
33605/// @}
33606
33607
33608/*! @name Persistence
33609@{ */
33610/// @}
33611
33612};
33613
33614/*!
33615@brief afxMultiLightData is a legacy datablock which is not supported for T3D.
33616
33617@ingroup afxEffects
33618@ingroup AFX
33619@ingroup Datablocks
33620
33621*/
33622class afxMultiLightData : public GameBaseData {
33623public:
33624
33625/*! @name Callbacks
33626@{ */
33627/// @}
33628
33629
33630/*! @name Scripting
33631@{ */
33632/// @}
33633
33634
33635/*! @name Ungrouped
33636@{ */
33637/// @}
33638
33639
33640/*! @name Object
33641@{ */
33642/// @}
33643
33644
33645/*! @name Editing
33646@{ */
33647/// @}
33648
33649
33650/*! @name Persistence
33651@{ */
33652/// @}
33653
33654};
33655
33656/*!
33657@brief Defines particle emission properties such as ejection angle, period and velocity for a ParticleEmitter.
33658
33659@tsexample
33660datablock ParticleEmitterData( GrenadeExpDustEmitter )
33661{
33662   ejectionPeriodMS = 1;
33663   periodVarianceMS = 0;
33664   ejectionVelocity = 15;
33665   velocityVariance = 0.0;
33666   ejectionOffset = 0.0;
33667   thetaMin = 85;
33668   thetaMax = 85;
33669   thetaVariance = 0;
33670   phiReferenceVel = 0;
33671   phiVariance = 360;
33672   overrideAdvance = false;
33673   lifetimeMS = 200;
33674   particles = "GrenadeExpDust";
33675};
33676@endtsexample
33677
33678@ingroup FX
33679@see ParticleEmitter
33680@see ParticleData
33681@see ParticleEmitterNode
33682
33683*/
33684class ParticleEmitterData : public GameBaseData {
33685public:
33686/*!
33687@brief Reloads the ParticleData datablocks and other fields used by this emitter.
33688
33689@tsexample
33690// Get the editor's current particle emitter
33691%emitter = PE_EmitterEditor.currEmitter
33692
33693// Change a field value
33694%emitter.setFieldValue( %propertyField, %value );
33695
33696// Reload this emitter
33697%emitter.reload();
33698@endtsexample
33699*/
33700void reload();
33701
33702/*! @name Callbacks
33703@{ */
33704/// @}
33705
33706
33707/*! @name ParticleEmitterData
33708@{ */
33709/*!
33710@brief Time (in milliseconds) between each particle ejection.
33711*/
33712int ejectionPeriodMS;
33713/*!
33714@brief Variance in ejection period, from 1 - ejectionPeriodMS.
33715*/
33716int periodVarianceMS;
33717/*!
33718@brief Particle ejection velocity.
33719*/
33720float ejectionVelocity;
33721/*!
33722@brief Variance for ejection velocity, from 0 - ejectionVelocity.
33723*/
33724float velocityVariance;
33725/*!
33726@brief Distance along ejection Z axis from which to eject particles.
33727*/
33728float ejectionOffset;
33729/*!
33730@brief Distance Padding along ejection Z axis from which to eject particles.
33731*/
33732float ejectionOffsetVariance;
33733/*!
33734@brief Minimum angle, from the horizontal plane, to eject from.
33735*/
33736float thetaMin;
33737/*!
33738@brief Maximum angle, from the horizontal plane, to eject particles from.
33739*/
33740float thetaMax;
33741/*!
33742@brief Angle variance from the previous particle, from 0 - 180.
33743*/
33744float thetaVariance;
33745/*!
33746@brief Reference angle, from the vertical plane, to eject particles from.
33747*/
33748float phiReferenceVel;
33749/*!
33750@brief Variance from the reference angle, from 0 - 360.
33751*/
33752float phiVariance;
33753/*!
33754@brief For soft particles, the distance (in meters) where particles will be faded based on the difference in depth between the particle and the scene geometry.
33755*/
33756float softnessDistance;
33757/*!
33758@brief Used to generate the final particle color by controlling interpolation between the particle color and the particle color multiplied by the ambient light color.
33759*/
33760float ambientFactor;
33761/*!
33762@brief If false, particles emitted in the same frame have their positions adjusted. If true, adjustment is skipped and particles will clump together.
33763*/
33764bool overrideAdvance;
33765/*!
33766@brief If true, Particles will always face the camera.
33767*/
33768bool orientParticles;
33769/*!
33770@brief If true, particles will be oriented to face in the direction they are moving.
33771*/
33772bool orientOnVelocity;
33773/*!
33774@brief If true, particles are rendered as a continous ribbon.
33775*/
33776bool ribbonParticles;
33777/*!
33778@brief @brief List of space or TAB delimited ParticleData datablock names.
33779
33780
33781A random one of these datablocks is selected each time a particle is emitted.
33782*/
33783string particles;
33784/*!
33785@brief Lifetime of emitted particles (in milliseconds).
33786*/
33787int lifetimeMS;
33788/*!
33789@brief Variance in particle lifetime from 0 - lifetimeMS.
33790*/
33791int lifetimeVarianceMS;
33792/*!
33793@brief @brief If true, use emitter specified sizes instead of datablock sizes.
33794
33795Useful for Debris particle emitters that control the particle size.
33796*/
33797bool useEmitterSizes;
33798/*!
33799@brief @brief If true, use emitter specified colors instead of datablock colors.
33800
33801
33802Useful for ShapeBase dust and WheeledVehicle wheel particle emitters that use the current material to control particle color.
33803*/
33804bool useEmitterColors;
33805/*!
33806@brief String value that controls how emitted particles blend with the scene.
33807*/
33808ParticleBlendStyle blendStyle;
33809/*!
33810@brief If true, particles are sorted furthest to nearest.
33811*/
33812bool sortParticles;
33813/*!
33814@brief @brief If true, reverses the normal draw order of particles.
33815
33816
33817Particles are normally drawn from newest to oldest, or in Z order (furthest first) if sortParticles is true. Setting this field to true will reverse that order: oldest first, or nearest first if sortParticles is true.
33818*/
33819bool reverseOrder;
33820/*!
33821@brief Optional texture to override ParticleData::textureName.
33822*/
33823string textureName;
33824/*!
33825@brief If true, particles always face along the axis defined by alignDirection.
33826*/
33827bool alignParticles;
33828/*!
33829@brief The direction aligned particles should face, only valid if alignParticles is true.
33830*/
33831Point3F alignDirection;
33832/*!
33833@brief This particle system should not use the mixed-resolution renderer. If your particle system has large amounts of overdraw, consider disabling this option.
33834*/
33835bool highResOnly;
33836/*!
33837@brief Controls whether particles are rendered onto reflective surfaces like water.
33838*/
33839bool renderReflection;
33840/*!
33841@brief If true, the particles are rendered to the glow buffer as well.
33842*/
33843bool glow;
33844/// @}
33845
33846
33847/*! @name AFX
33848@{ */
33849/*!
33850*/
33851bool ejectionInvert;
33852/*!
33853*/
33854bool fadeColor;
33855/*!
33856*/
33857bool fadeAlpha;
33858/*!
33859*/
33860bool fadeSize;
33861/*!
33862*/
33863bool useEmitterTransform;
33864/// @}
33865
33866
33867/*! @name AFX Pooled Particles
33868@{ */
33869/*!
33870*/
33871afxParticlePoolData poolData;
33872/*!
33873*/
33874int poolIndex;
33875/*!
33876*/
33877bool poolDepthFade;
33878/*!
33879*/
33880bool poolRadialFade;
33881/// @}
33882
33883
33884/*! @name Scripting
33885@{ */
33886/// @}
33887
33888
33889/*! @name Ungrouped
33890@{ */
33891/// @}
33892
33893
33894/*! @name Object
33895@{ */
33896/// @}
33897
33898
33899/*! @name Editing
33900@{ */
33901/// @}
33902
33903
33904/*! @name Persistence
33905@{ */
33906/// @}
33907
33908};
33909
33910/*!
33911@brief A base datablock inherited by AFX Particle Emitter effects.
33912
33913A base datablock inherited by AFX Particle Emitter effects.
33914
33915@ingroup afxEffects
33916@ingroup AFX
33917@ingroup Datablocks
33918
33919*/
33920class afxParticleEmitterData : public ParticleEmitterData {
33921public:
33922
33923/*! @name Callbacks
33924@{ */
33925/// @}
33926
33927/*!
33928@brief If true, the initial velocity of emitted particles is multiplied by the fade amount of the containing effect wrapper. As the effect fades-in and out, so does the initial velocity of new particles.
33929*/
33930bool fadeVelocity;
33931/*!
33932@brief If true, the ejection offset of emitted particles is multiplied by the fade amount of the containing effect wrapper. As the effect fades-in and out, so does the ejection offset of new particles.
33933*/
33934bool fadeOffset;
33935/*!
33936@brief General direction vector used for emitting particles. Its exact interpretation is determined by the particle emitter subclass.
33937*/
33938Point3F vector;
33939/*!
33940@brief Sets whether the vector field should be interpreted as a vector in the world coordinate system.
33941*/
33942bool vectorIsWorld;
33943/*!
33944@brief A string of paths to be used as transform paths. Each path name must reference an afxPathData datablock. Transform paths are used to translate particles along a given path or series of paths.
33945*/
33946string pathsTransform;
33947
33948/*! @name ParticleEmitterData
33949@{ */
33950/// @}
33951
33952
33953/*! @name AFX
33954@{ */
33955/// @}
33956
33957
33958/*! @name AFX Pooled Particles
33959@{ */
33960/// @}
33961
33962
33963/*! @name Scripting
33964@{ */
33965/// @}
33966
33967
33968/*! @name Ungrouped
33969@{ */
33970/// @}
33971
33972
33973/*! @name Object
33974@{ */
33975/// @}
33976
33977
33978/*! @name Editing
33979@{ */
33980/// @}
33981
33982
33983/*! @name Persistence
33984@{ */
33985/// @}
33986
33987};
33988
33989/*!
33990@brief An AFX customized particle emitter that emits particles along a 3D vector.
33991
33992An AFX customized particle emitter that emits particles along a 3D vector.
33993
33994@ingroup afxEffects
33995@ingroup AFX
33996@ingroup Datablocks
33997
33998*/
33999class afxParticleEmitterVectorData : public afxParticleEmitterData {
34000public:
34001
34002/*! @name Callbacks
34003@{ */
34004/// @}
34005
34006
34007/*! @name ParticleEmitterData
34008@{ */
34009/// @}
34010
34011
34012/*! @name AFX
34013@{ */
34014/// @}
34015
34016
34017/*! @name AFX Pooled Particles
34018@{ */
34019/// @}
34020
34021
34022/*! @name Scripting
34023@{ */
34024/// @}
34025
34026
34027/*! @name Ungrouped
34028@{ */
34029/// @}
34030
34031
34032/*! @name Object
34033@{ */
34034/// @}
34035
34036
34037/*! @name Editing
34038@{ */
34039/// @}
34040
34041
34042/*! @name Persistence
34043@{ */
34044/// @}
34045
34046};
34047
34048/*!
34049@brief An AFX customized particle emitter that emits particles within a cone shape.
34050
34051An AFX customized particle emitter that emits particles within a cone shape.
34052
34053@ingroup afxEffects
34054@ingroup AFX
34055@ingroup Datablocks
34056
34057*/
34058class afxParticleEmitterConeData : public afxParticleEmitterData {
34059public:
34060
34061/*! @name Callbacks
34062@{ */
34063/// @}
34064
34065/*!
34066@brief ...
34067*/
34068float spreadMin;
34069/*!
34070@brief ...
34071*/
34072float spreadMax;
34073
34074/*! @name ParticleEmitterData
34075@{ */
34076/// @}
34077
34078
34079/*! @name AFX
34080@{ */
34081/// @}
34082
34083
34084/*! @name AFX Pooled Particles
34085@{ */
34086/// @}
34087
34088
34089/*! @name Scripting
34090@{ */
34091/// @}
34092
34093
34094/*! @name Ungrouped
34095@{ */
34096/// @}
34097
34098
34099/*! @name Object
34100@{ */
34101/// @}
34102
34103
34104/*! @name Editing
34105@{ */
34106/// @}
34107
34108
34109/*! @name Persistence
34110@{ */
34111/// @}
34112
34113};
34114
34115/*!
34116@brief An AFX customized particle emitter that emits particles along a path.
34117
34118An AFX customized particle emitter that emits particles along a path.
34119
34120@ingroup afxEffects
34121@ingroup AFX
34122@ingroup Datablocks
34123
34124*/
34125class afxParticleEmitterPathData : public afxParticleEmitterData {
34126public:
34127
34128/*! @name Callbacks
34129@{ */
34130/// @}
34131
34132/*!
34133@brief ...
34134*/
34135string paths;
34136/*!
34137@brief ...
34138*/
34139afxParticleEmitterPath_OriginType pathOrigin;
34140/*!
34141@brief ...
34142*/
34143bool groundConform;
34144/*!
34145@brief ...
34146*/
34147bool groundConformTerrain;
34148/*!
34149@brief ...
34150*/
34151bool groundConformInteriors;
34152/*!
34153@brief ...
34154*/
34155float groundConformHeight;
34156
34157/*! @name ParticleEmitterData
34158@{ */
34159/// @}
34160
34161
34162/*! @name AFX
34163@{ */
34164/// @}
34165
34166
34167/*! @name AFX Pooled Particles
34168@{ */
34169/// @}
34170
34171
34172/*! @name Scripting
34173@{ */
34174/// @}
34175
34176
34177/*! @name Ungrouped
34178@{ */
34179/// @}
34180
34181
34182/*! @name Object
34183@{ */
34184/// @}
34185
34186
34187/*! @name Editing
34188@{ */
34189/// @}
34190
34191
34192/*! @name Persistence
34193@{ */
34194/// @}
34195
34196};
34197
34198/*!
34199@brief An AFX customized particle emitter that emits particles within a disc shape.
34200
34201An AFX customized particle emitter that emits particles within a disc shape.
34202
34203@ingroup afxEffects
34204@ingroup AFX
34205@ingroup Datablocks
34206
34207*/
34208class afxParticleEmitterDiscData : public afxParticleEmitterData {
34209public:
34210
34211/*! @name Callbacks
34212@{ */
34213/// @}
34214
34215/*!
34216@brief ...
34217*/
34218float radiusMin;
34219/*!
34220@brief ...
34221*/
34222float radiusMax;
34223
34224/*! @name ParticleEmitterData
34225@{ */
34226/// @}
34227
34228
34229/*! @name AFX
34230@{ */
34231/// @}
34232
34233
34234/*! @name AFX Pooled Particles
34235@{ */
34236/// @}
34237
34238
34239/*! @name Scripting
34240@{ */
34241/// @}
34242
34243
34244/*! @name Ungrouped
34245@{ */
34246/// @}
34247
34248
34249/*! @name Object
34250@{ */
34251/// @}
34252
34253
34254/*! @name Editing
34255@{ */
34256/// @}
34257
34258
34259/*! @name Persistence
34260@{ */
34261/// @}
34262
34263};
34264
34265/*!
34266@brief A datablock that specifies a PhysicalZone effect.
34267
34268A Physical Zone is a Torque effect that applies physical forces to Players and other movable objects that enter a specific region of influence. AFX has enhanced Physical Zones by allowing orientation of vector forces and adding radial forces. AFX has also optimized Physical Zone networking so that they can be constrained to moving objects for a variety of effects including repelling and flying.
34269
34270@ingroup afxEffects
34271@ingroup AFX
34272@ingroup Datablocks
34273
34274*/
34275class afxPhysicalZoneData : public GameBaseData {
34276public:
34277
34278/*! @name Callbacks
34279@{ */
34280/// @}
34281
34282/*!
34283@brief A multiplier that biases the velocity of an object every tick it is within the zone.
34284*/
34285float velocityMod;
34286/*!
34287@brief A multiplier that biases the influence of gravity on objects within the zone.
34288*/
34289float gravityMod;
34290/*!
34291@brief A three-valued vector representing a directional force applied to objects withing the zone.
34292*/
34293Point3F appliedForce;
34294/*!
34295@brief Floating point values describing the outer bounds of the PhysicalZone's region of influence.
34296*/
34297string polyhedron;
34298/*!
34299@brief This enumerated attribute defines the type of force used in the PhysicalZone. Possible values: vector, sphere, or cylinder.
34300*/
34301PhysicalZone_ForceType forceType;
34302/*!
34303@brief Determines if the force can be oriented by the PhysicalZone's transform matrix.
34304*/
34305bool orientForce;
34306/*!
34307@brief When true, an object used as the primary position constraint of a physical-zone effect will not be influenced by the forces of the zone.
34308*/
34309bool excludeConstraintObject;
34310
34311/*! @name Scripting
34312@{ */
34313/// @}
34314
34315
34316/*! @name Ungrouped
34317@{ */
34318/// @}
34319
34320
34321/*! @name Object
34322@{ */
34323/// @}
34324
34325
34326/*! @name Editing
34327@{ */
34328/// @}
34329
34330
34331/*! @name Persistence
34332@{ */
34333/// @}
34334
34335};
34336
34337/*!
34338@brief A datablock that specifies a Player Movement effect.
34339
34340Player Movement effects are used to directly alter the speed and/or movement direction of Player objects. The Player Movement effect is similar to the Player Puppet effect, but where puppet effects totally take over a Player's transformation using the AFX constraint system, Player Movement effects 'steer' the player using the same mechanisms that allow Player control from mouse and keyboard input. Another difference is that Player Movement effects only influence the server instance of a Player. Puppet effects can influence both the Player's server instance and its client ghosts.
34341
34342@ingroup afxEffects
34343@ingroup AFX
34344@ingroup Datablocks
34345
34346*/
34347class afxPlayerMovementData : public GameBaseData {
34348public:
34349
34350/*! @name Callbacks
34351@{ */
34352/// @}
34353
34354/*!
34355@brief A floating-point multiplier that scales the constraint Player's movement speed.
34356*/
34357float speedBias;
34358/*!
34359*/
34360Point3F movement;
34361/*!
34362@brief Possible values: add, multiply, or replace.
34363*/
34364afxPlayerMovement_OpType movementOp;
34365
34366/*! @name Scripting
34367@{ */
34368/// @}
34369
34370
34371/*! @name Ungrouped
34372@{ */
34373/// @}
34374
34375
34376/*! @name Object
34377@{ */
34378/// @}
34379
34380
34381/*! @name Editing
34382@{ */
34383/// @}
34384
34385
34386/*! @name Persistence
34387@{ */
34388/// @}
34389
34390};
34391
34392/*!
34393@brief A datablock that specifies a Player Puppet effect.
34394
34395Player Puppet effects are defined using the afxPlayerPuppetData datablock and are used to control the movement of Player objects with the AFX constraint system. The Player Puppet effect is similar to the Player Movement effect, but where movement effects 'steer' the player using the same mechanisms that allow Player control from mouse and keyboard input, Player Puppet effects totally take over a Player's transformation using the AFX constraint system.
34396
34397Player Puppet can be configured to directly move a Player's client ghosts as well as its server instance. When doing this, it is important to keep the general motion of the Player object and its ghosts somewhat consistent. Otherwise, obvious discontinuities in the motion will result when the Player Puppet ends and control is restored to the server Player.
34398
34399@ingroup afxEffects
34400@ingroup AFX
34401@ingroup Datablocks
34402
34403*/
34404class afxPlayerPuppetData : public GameBaseData {
34405public:
34406
34407/*! @name Callbacks
34408@{ */
34409/// @}
34410
34411/*!
34412@brief ...
34413*/
34414string objectSpec;
34415/*!
34416@brief ...
34417*/
34418char networking;
34419
34420/*! @name Scripting
34421@{ */
34422/// @}
34423
34424
34425/*! @name Ungrouped
34426@{ */
34427/// @}
34428
34429
34430/*! @name Object
34431@{ */
34432/// @}
34433
34434
34435/*! @name Editing
34436@{ */
34437/// @}
34438
34439
34440/*! @name Persistence
34441@{ */
34442/// @}
34443
34444};
34445
34446/*!
34447@brief A datablock that specifies a dynamic Point Light effect.
34448
34449A Point Light effect that uses the T3D PointLight object. afxT3DPointLightData has the same fields found in PointLight but in a datablock structure.
34450
34451@ingroup afxEffects
34452@ingroup AFX
34453@ingroup Datablocks
34454
34455*/
34456class afxT3DPointLightData : public afxT3DLightBaseData {
34457public:
34458
34459/*! @name Callbacks
34460@{ */
34461/// @}
34462
34463
34464/*! @name Light
34465@{ */
34466/*!
34467@brief Controls the falloff of the light emission
34468*/
34469float radius;
34470/// @}
34471
34472
34473/*! @name Light
34474@{ */
34475/// @}
34476
34477
34478/*! @name Light Animation
34479@{ */
34480/// @}
34481
34482
34483/*! @name Misc
34484@{ */
34485/// @}
34486
34487
34488/*! @name Scripting
34489@{ */
34490/// @}
34491
34492
34493/*! @name Ungrouped
34494@{ */
34495/// @}
34496
34497
34498/*! @name Object
34499@{ */
34500/// @}
34501
34502
34503/*! @name Editing
34504@{ */
34505/// @}
34506
34507
34508/*! @name Persistence
34509@{ */
34510/// @}
34511
34512};
34513
34514/*!
34515@brief Stores properties for an individual projectile type.
34516@tsexample
34517datablock ProjectileData(GrenadeLauncherProjectile)
34518{
34519 projectileShapeName = "art/shapes/weapons/SwarmGun/rocket.dts";
34520directDamage = 30;
34521radiusDamage = 30;
34522damageRadius = 5;
34523areaImpulse = 2000;
34524explosion = GrenadeLauncherExplosion;
34525waterExplosion = GrenadeLauncherWaterExplosion;
34526decal = ScorchRXDecal;
34527splash = GrenadeSplash;
34528particleEmitter = GrenadeProjSmokeTrailEmitter;
34529particleWaterEmitter = GrenadeTrailWaterEmitter;
34530muzzleVelocity = 30;
34531velInheritFactor = 0.3;
34532armingDelay = 2000;
34533lifetime = 10000;
34534fadeDelay = 4500;
34535bounceElasticity = 0.4;
34536bounceFriction = 0.3;
34537isBallistic = true;
34538gravityMod = 0.9;
34539lightDesc = GrenadeLauncherLightDesc;
34540damageType = "GrenadeDamage";
34541};
34542@endtsexample
34543@ingroup gameObjects
34544
34545*/
34546class ProjectileData : public GameBaseData {
34547public:
34548
34549/*! @name Callbacks
34550@{ */
34551/*!
34552@brief Called when a projectile explodes.
34553
34554This function is only called on server objects.
34555@param proj The exploding projectile.
34556@param pos The position of the explosion.
34557@param fade The current fadeValue of the projectile, affects its visibility.
34558
34559@see Projectile*/
34560void onExplode( Projectile proj, Point3F pos, float fade );
34561/*!
34562@brief Called when a projectile collides with another object.
34563
34564This function is only called on server objects.@param proj The projectile colliding with SceneObject col.
34565@param col The SceneObject hit by the projectile.
34566@param fade The current fadeValue of the projectile, affects its visibility.
34567@param pos The position of the collision.
34568@param normal The normal of the collision.
34569@see Projectile*/
34570void onCollision( Projectile proj, SceneObject col, float fade, Point3F pos, Point3F normal );
34571/// @}
34572
34573/*!
34574@brief @brief Particle emitter datablock used to generate particles while the projectile is outside of water.
34575
34576
34577@note If datablocks are defined for both particleEmitter and particleWaterEmitter, both effects will play as the projectile enters or leaves water.
34578
34579@see particleWaterEmitter
34580
34581*/
34582ParticleEmitterData ParticleEmitter;
34583/*!
34584@brief @brief Particle emitter datablock used to generate particles while the projectile is submerged in water.
34585
34586
34587@note If datablocks are defined for both particleWaterEmitter and particleEmitter , both effects will play as the projectile enters or leaves water.
34588
34589@see particleEmitter
34590
34591*/
34592ParticleEmitterData particleWaterEmitter;
34593/*!
34594@brief @brief File path to the model of the projectile.
34595
34596
34597
34598*/
34599filename projectileShapeName;
34600/*!
34601@brief @brief Scale to apply to the projectile's size.
34602
34603
34604@note This is applied after SceneObject::scale
34605
34606*/
34607Point3F scale;
34608/*!
34609@brief @brief SFXTrack datablock used to play sounds while in flight.
34610
34611
34612
34613*/
34614SFXTrack sound;
34615/*!
34616@brief @brief Explosion datablock used when the projectile explodes outside of water.
34617
34618
34619
34620*/
34621ExplosionData Explosion;
34622/*!
34623@brief @brief Explosion datablock used when the projectile explodes underwater.
34624
34625
34626
34627*/
34628ExplosionData waterExplosion;
34629/*!
34630@brief @brief Splash datablock used to create splash effects as the projectile enters or leaves water
34631
34632
34633
34634*/
34635SplashData Splash;
34636/*!
34637@brief @brief Decal datablock used for decals placed at projectile explosion points.
34638
34639
34640
34641*/
34642DecalData decal;
34643/*!
34644@brief @brief LightDescription datablock used for lights attached to the projectile.
34645
34646
34647
34648*/
34649LightDescription lightDesc;
34650/*!
34651@brief @brief Detetmines if the projectile should be affected by gravity and whether or not it bounces before exploding.
34652
34653
34654
34655*/
34656bool isBallistic;
34657/*!
34658@brief @brief Amount of velocity the projectile recieves from the source that created it.
34659
34660
34661Use an amount between 0 and 1 for the best effect. This value is never modified by the engine.
34662@note This value by default is not transmitted between the server and the client.
34663*/
34664float velInheritFactor;
34665/*!
34666@brief @brief Amount of velocity the projectile recieves from the "muzzle" of the gun.
34667
34668
34669Used with velInheritFactor to determine the initial velocity of the projectile. This value is never modified by the engine.
34670
34671@note This value by default is not transmitted between the server and the client.
34672
34673@see velInheritFactor
34674*/
34675float muzzleVelocity;
34676/*!
34677*/
34678float impactForce;
34679/*!
34680@brief @brief Amount of time, in milliseconds, before the projectile is removed from the simulation.
34681
34682
34683Used with fadeDelay to determine the transparency of the projectile at a given time. A projectile may exist up to a maximum of 131040ms (or 4095 ticks) as defined by Projectile::MaxLivingTicks in the source code.@see fadeDelay
34684*/
34685int lifetime;
34686/*!
34687@brief @brief Amount of time, in milliseconds, before the projectile will cause damage or explode on impact.
34688
34689
34690This value must be equal to or less than the projectile's lifetime.
34691
34692@see lifetime
34693*/
34694int armingDelay;
34695/*!
34696@brief @brief Amount of time, in milliseconds, before the projectile begins to fade out.
34697
34698
34699This value must be smaller than the projectile's lifetime to have an affect.
34700*/
34701int fadeDelay;
34702/*!
34703@brief @brief Influences post-bounce velocity of a projectile that does not explode on contact.
34704
34705
34706Scales the velocity from a bounce after friction is taken into account. A value of 1.0 will leave it's velocity unchanged while values greater than 1.0 will increase it.
34707
34708*/
34709float bounceElasticity;
34710/*!
34711@brief @brief Factor to reduce post-bounce velocity of a projectile that does not explode on contact.
34712
34713
34714Reduces bounce velocity by this factor and a multiple of the tangent to impact. Used to simulate surface friction.
34715
34716*/
34717float bounceFriction;
34718/*!
34719@brief @brief Scales the influence of gravity on the projectile.
34720
34721
34722The larger this value is, the more that gravity will affect the projectile. A value of 1.0 will assume "normal" influence upon it.
34723The magnitude of gravity is assumed to be 9.81 m/s/s
34724
34725@note ProjectileData::isBallistic must be true for this to have any affect.
34726*/
34727float gravityMod;
34728
34729/*! @name Scripting
34730@{ */
34731/// @}
34732
34733
34734/*! @name Ungrouped
34735@{ */
34736/// @}
34737
34738
34739/*! @name Object
34740@{ */
34741/// @}
34742
34743
34744/*! @name Editing
34745@{ */
34746/// @}
34747
34748
34749/*! @name Persistence
34750@{ */
34751/// @}
34752
34753};
34754
34755/*!
34756@brief A datablock that specifies a Projectile effect.
34757
34758afxProjectileData inherits from ProjectileData and adds some AFX specific fields.
34759
34760@ingroup afxEffects
34761@ingroup AFX
34762@ingroup Datablocks
34763
34764*/
34765class afxProjectileData : public ProjectileData {
34766public:
34767
34768/*! @name Callbacks
34769@{ */
34770/// @}
34771
34772/*!
34773@brief ...
34774*/
34775char networking;
34776/*!
34777@brief ...
34778*/
34779string launchPosSpec;
34780/*!
34781@brief ...
34782*/
34783Point3F launchDirBias;
34784/*!
34785@brief ...
34786*/
34787bool ignoreSourceTimeout;
34788/*!
34789@brief ...
34790*/
34791int dynamicCollisionMask;
34792/*!
34793@brief ...
34794*/
34795int staticCollisionMask;
34796/*!
34797@brief ...
34798*/
34799bool overrideCollisionMasks;
34800/*!
34801@brief Possible values: towardPos2Constraint, orientConstraint, or launchDirField.
34802*/
34803afxProjectile_LaunchDirType launchDirMethod;
34804
34805/*! @name Scripting
34806@{ */
34807/// @}
34808
34809
34810/*! @name Ungrouped
34811@{ */
34812/// @}
34813
34814
34815/*! @name Object
34816@{ */
34817/// @}
34818
34819
34820/*! @name Editing
34821@{ */
34822/// @}
34823
34824
34825/*! @name Persistence
34826@{ */
34827/// @}
34828
34829};
34830
34831/*!
34832@brief Base projectile class. Uses the ProjectileData class for properties of individual projectiles.
34833@ingroup gameObjects
34834
34835*/
34836class Projectile : public GameBase {
34837public:
34838/*!
34839@brief Updates the projectile's positional and collision information.
34840
34841This function will first delete the projectile if it is a server object and is outside it's ProjectileData::lifetime. Also responsible for applying gravity, determining collisions, triggering explosions, emitting trail particles, and calculating bounces if necessary.@param seconds Amount of time, in seconds since the simulation's start, to advance.
34842@tsexample
34843// Tell the projectile to process a simulation event, and provide the amount of time
34844// that has passed since the simulation began.
34845%seconds = 2.0;
34846%projectile.presimulate(%seconds);
34847@endtsexample
34848@note This function is not called if the SimObject::hidden is true.*/
34849void presimulate( float seconds=1.0f );
34850
34851/*! @name Callbacks
34852@{ */
34853/// @}
34854
34855/*!
34856@brief Disables rendering of all instances of this type.
34857
34858
34859@ingroup UNDOCUMENTED
34860*/
34861static bool isRenderable;
34862/*!
34863@brief Disables selection of all instances of this type.
34864
34865
34866@ingroup UNDOCUMENTED
34867*/
34868static bool isSelectable;
34869
34870/*! @name Physics
34871@{ */
34872/*!
34873@brief @brief Starting position for the projectile.
34874
34875
34876
34877*/
34878Point3F initialPosition;
34879/*!
34880@brief @brief Starting velocity for the projectile.
34881
34882
34883
34884*/
34885Point3F initialVelocity;
34886/// @}
34887
34888
34889/*! @name Source
34890@{ */
34891/*!
34892@brief @brief ID number of the object that fired the projectile.
34893
34894
34895@note If the projectile was fired by a WeaponImage, sourceObject will be the object that owns the WeaponImage. This is usually the player.
34896*/
34897int sourceObject;
34898/*!
34899@brief @brief The sourceObject's weapon slot that the projectile originates from.
34900
34901
34902
34903*/
34904int sourceSlot;
34905/*!
34906*/
34907bool ignoreSourceTimeout;
34908/// @}
34909
34910
34911/*! @name Game
34912@{ */
34913/// @}
34914
34915
34916/*! @name GameObject
34917@{ */
34918/// @}
34919
34920
34921/*! @name Transform
34922@{ */
34923/// @}
34924
34925
34926/*! @name Editing
34927@{ */
34928/// @}
34929
34930
34931/*! @name Mounting
34932@{ */
34933/// @}
34934
34935
34936/*! @name Ungrouped
34937@{ */
34938/// @}
34939
34940
34941/*! @name Object
34942@{ */
34943/// @}
34944
34945
34946/*! @name Editing
34947@{ */
34948/// @}
34949
34950
34951/*! @name Persistence
34952@{ */
34953/// @}
34954
34955};
34956
34957/*!
34958@brief A Projectile effect as defined by an afxProjectileData datablock.
34959
34960@ingroup afxEffects
34961@ingroup AFX
34962
34963*/
34964class afxProjectile : public Projectile {
34965public:
34966
34967/*! @name Callbacks
34968@{ */
34969/// @}
34970
34971/*!
34972@brief Disables rendering of all instances of this type.
34973
34974
34975@ingroup UNDOCUMENTED
34976*/
34977static bool isRenderable;
34978/*!
34979@brief Disables selection of all instances of this type.
34980
34981
34982@ingroup UNDOCUMENTED
34983*/
34984static bool isSelectable;
34985
34986/*! @name Physics
34987@{ */
34988/// @}
34989
34990
34991/*! @name Source
34992@{ */
34993/// @}
34994
34995
34996/*! @name Game
34997@{ */
34998/// @}
34999
35000
35001/*! @name GameObject
35002@{ */
35003/// @}
35004
35005
35006/*! @name Transform
35007@{ */
35008/// @}
35009
35010
35011/*! @name Editing
35012@{ */
35013/// @}
35014
35015
35016/*! @name Mounting
35017@{ */
35018/// @}
35019
35020
35021/*! @name Ungrouped
35022@{ */
35023/// @}
35024
35025
35026/*! @name Object
35027@{ */
35028/// @}
35029
35030
35031/*! @name Editing
35032@{ */
35033/// @}
35034
35035
35036/*! @name Persistence
35037@{ */
35038/// @}
35039
35040};
35041
35042/*!
35043@brief A datablock that specifies a Script Event effect.
35044
35045Arbitrary script functions can be called as an AFX effect using afxScriptEventData. They are useful for implementing high-level scripted side-effects such as character resurrection or teleportation.
35046
35047@ingroup afxEffects
35048@ingroup AFX
35049@ingroup Datablocks
35050
35051*/
35052class afxScriptEventData : public GameBaseData {
35053public:
35054
35055/*! @name Callbacks
35056@{ */
35057/// @}
35058
35059/*!
35060@brief The name of a script method defined for the instance class of an effects choreographer. The arguments used to call this method are determined by the type of choreographer.
35061*/
35062string methodName;
35063/*!
35064@brief An arbitrary blind data value which is passed in as an argument of the script event method. The value of scriptData can be used to differentiate uses when handling different script event effects with a single method.
35065*/
35066string scriptData;
35067
35068/*! @name Scripting
35069@{ */
35070/// @}
35071
35072
35073/*! @name Ungrouped
35074@{ */
35075/// @}
35076
35077
35078/*! @name Object
35079@{ */
35080/// @}
35081
35082
35083/*! @name Editing
35084@{ */
35085/// @}
35086
35087
35088/*! @name Persistence
35089@{ */
35090/// @}
35091
35092};
35093
35094/*!
35095@brief A datablock that specifies a dynamic Spot Light effect.
35096
35097A Spot Light effect that uses the T3D SpotLight object. afxT3DSpotLightData has the same fields found in SpotLight but in a datablock structure.
35098
35099@ingroup afxEffects
35100@ingroup AFX
35101@ingroup Datablocks
35102
35103*/
35104class afxT3DSpotLightData : public afxT3DLightBaseData {
35105public:
35106
35107/*! @name Callbacks
35108@{ */
35109/// @}
35110
35111
35112/*! @name Light
35113@{ */
35114/*!
35115@brief ...
35116*/
35117float range;
35118/*!
35119@brief ...
35120*/
35121float innerAngle;
35122/*!
35123@brief ...
35124*/
35125float outerAngle;
35126/// @}
35127
35128
35129/*! @name Light
35130@{ */
35131/// @}
35132
35133
35134/*! @name Light Animation
35135@{ */
35136/// @}
35137
35138
35139/*! @name Misc
35140@{ */
35141/// @}
35142
35143
35144/*! @name Scripting
35145@{ */
35146/// @}
35147
35148
35149/*! @name Ungrouped
35150@{ */
35151/// @}
35152
35153
35154/*! @name Object
35155@{ */
35156/// @}
35157
35158
35159/*! @name Editing
35160@{ */
35161/// @}
35162
35163
35164/*! @name Persistence
35165@{ */
35166/// @}
35167
35168};
35169
35170/*!
35171@brief A datablock that specifies a StaticShape effect.
35172
35173afxStaticShapeData inherits from StaticShapeData and adds some AFX specific fields. StaticShape effects should be specified using afxStaticShapeData rather than StaticShapeData datablocks.
35174
35175@ingroup afxEffects
35176@ingroup AFX
35177@ingroup Datablocks
35178
35179*/
35180class afxStaticShapeData : public StaticShapeData {
35181public:
35182
35183/*! @name Callbacks
35184@{ */
35185/// @}
35186
35187/*!
35188@brief An animation sequence in the StaticShape to play.
35189*/
35190filename sequence;
35191/*!
35192@brief ...
35193*/
35194bool ignoreSceneAmbient;
35195/*!
35196@brief ...
35197*/
35198bool useCustomSceneAmbient;
35199/*!
35200@brief ...
35201*/
35202LinearColorF customSceneAmbient;
35203/*!
35204@brief When true, the StaticShape effect will leave behind the StaticShape object as a permanent part of the scene.
35205*/
35206bool doSpawn;
35207
35208/*! @name Shadows
35209@{ */
35210/// @}
35211
35212
35213/*! @name Render
35214@{ */
35215/// @}
35216
35217
35218/*! @name Destruction
35219Parameters related to the destruction effects of this object.
35220@{ */
35221/// @}
35222
35223
35224/*! @name Physics
35225@{ */
35226/// @}
35227
35228
35229/*! @name Damage/Energy
35230@{ */
35231/// @}
35232
35233
35234/*! @name Camera
35235The settings used by the shape when it is the camera.
35236@{ */
35237/// @}
35238
35239
35240/*! @name Misc
35241@{ */
35242/// @}
35243
35244
35245/*! @name Reflection
35246@{ */
35247/// @}
35248
35249
35250/*! @name Scripting
35251@{ */
35252/// @}
35253
35254
35255/*! @name Ungrouped
35256@{ */
35257/// @}
35258
35259
35260/*! @name Object
35261@{ */
35262/// @}
35263
35264
35265/*! @name Editing
35266@{ */
35267/// @}
35268
35269
35270/*! @name Persistence
35271@{ */
35272/// @}
35273
35274};
35275
35276/*!
35277@brief A StaticShape effect as defined by an afxStaticShapeData datablock.
35278
35279@ingroup afxEffects
35280@ingroup AFX
35281
35282*/
35283class afxStaticShape : public StaticShape {
35284public:
35285
35286/*! @name Callbacks
35287@{ */
35288/// @}
35289
35290/*!
35291@brief Disables rendering of all instances of this type.
35292
35293
35294@ingroup UNDOCUMENTED
35295*/
35296static bool isRenderable;
35297/*!
35298@brief Disables selection of all instances of this type.
35299
35300
35301@ingroup UNDOCUMENTED
35302*/
35303static bool isSelectable;
35304
35305/*! @name Game
35306@{ */
35307/// @}
35308
35309
35310/*! @name GameObject
35311@{ */
35312/// @}
35313
35314
35315/*! @name Transform
35316@{ */
35317/// @}
35318
35319
35320/*! @name Editing
35321@{ */
35322/// @}
35323
35324
35325/*! @name Mounting
35326@{ */
35327/// @}
35328
35329
35330/*! @name Ungrouped
35331@{ */
35332/// @}
35333
35334
35335/*! @name Object
35336@{ */
35337/// @}
35338
35339
35340/*! @name Editing
35341@{ */
35342/// @}
35343
35344
35345/*! @name Persistence
35346@{ */
35347/// @}
35348
35349};
35350
35351/*!
35352@brief afxVolumeLightData is a legacy datablock which is not supported for T3D.
35353
35354@ingroup afxEffects
35355@ingroup AFX
35356@ingroup Datablocks
35357
35358*/
35359class afxVolumeLightData : public GameBaseData {
35360public:
35361
35362/*! @name Callbacks
35363@{ */
35364/// @}
35365
35366
35367/*! @name Scripting
35368@{ */
35369/// @}
35370
35371
35372/*! @name Ungrouped
35373@{ */
35374/// @}
35375
35376
35377/*! @name Object
35378@{ */
35379/// @}
35380
35381
35382/*! @name Editing
35383@{ */
35384/// @}
35385
35386
35387/*! @name Persistence
35388@{ */
35389/// @}
35390
35391};
35392
35393/*!
35394@brief A datablock that specifies a decal-like Zodiac effect.
35395
35396Zodiacs are special-purpose decal textures, often circular, that are always projected vertically onto the ground. Parameters control dynamic rotation and scale as well as texture, color, and blending style.
35397
35398Zodiacs render on objects of type TerrainBlock, InteriorInstance, GroundPlane, MeshRoad, and TSStatic. They are very effective as spellcasting lighting rings, explosion shockwaves, scorched earth decals, and selection indicators.
35399
35400@ingroup afxEffects
35401@ingroup AFX
35402@ingroup Datablocks
35403
35404*/
35405class afxZodiacData : public GameBaseData {
35406public:
35407
35408/*! @name Callbacks
35409@{ */
35410/// @}
35411
35412/*!
35413@brief An image to use as the zodiac's texture.
35414*/
35415filename texture;
35416/*!
35417@brief The zodiac's radius in scene units.
35418*/
35419float radius;
35420/*!
35421@brief For interior zodiacs only, verticalRange specifies distances above and below the zodiac's position. If both values are 0.0, the radius is used.
35422*/
35423Point2F verticalRange;
35424/*!
35425@brief Specifies if the zodiac's verticalRange should scale according to changes in the radius. When a zodiacs is used as an expanding shockwave, this value should be set to false, otherwise the zodiac can expand to cover an entire interior.
35426*/
35427bool scaleVerticalRange;
35428/*!
35429@brief The starting angle in degrees of the zodiac's rotation.
35430*/
35431float startAngle;
35432/*!
35433@brief The rate of rotation in degrees-per-second. Zodiacs with a positive rotationRate rotate clockwise, while those with negative values turn counter-clockwise.
35434*/
35435float rotationRate;
35436/*!
35437@brief A duration of time in seconds over which the zodiac grows from a zero size to its full size as specified by the radius.
35438*/
35439float growInTime;
35440/*!
35441@brief A duration of time in seconds over which the zodiac shrinks from full size to invisible.
35442*/
35443float shrinkOutTime;
35444/*!
35445@brief A rate in meters-per-second at which the zodiac grows in size. A negative value will shrink the zodiac.
35446*/
35447float growthRate;
35448/*!
35449@brief A color value for the zodiac.
35450*/
35451LinearColorF color;
35452/*!
35453@brief A blending style for the zodiac. Possible values: normal, additive, or subtractive.
35454*/
35455afxZodiac_BlendType blend;
35456/*!
35457@brief Specifies if the zodiac should be rendered on terrain or terrain-like surfaces.
35458*/
35459bool showOnTerrain;
35460/*!
35461@brief Specifies if the zodiac should be rendered on interior or interior-like surfaces.
35462*/
35463bool showOnInteriors;
35464/*!
35465@brief Specifies if the zodiac should be rendered on the reflection rendering pass of the object it will be projected onto.
35466*/
35467bool showInReflections;
35468/*!
35469@brief Specifies if the zodiac should be rendered on the non-reflection rendering pass of the object it will be projected onto.
35470*/
35471bool showInNonReflections;
35472/*!
35473@brief Specifies if the zodiac's rotation should be defined by its constrained transformation.
35474*/
35475bool trackOrientConstraint;
35476/*!
35477@brief Specifies if interior zodiacs should be rendered exclusively on perfectly horizontal interior surfaces.
35478*/
35479bool interiorHorizontalOnly;
35480/*!
35481@brief Specifies if interior zodiacs should not be rendered on perfectly vertical interior surfaces.
35482*/
35483bool interiorIgnoreVertical;
35484/*!
35485@brief Specifies if interior zodiacs should not be rendered on interior surface which are backfacing to the zodiac's center.
35486*/
35487bool interiorIgnoreBackfaces;
35488/*!
35489*/
35490bool interiorIgnoreOpaque;
35491/*!
35492*/
35493bool interiorIgnoreTransparent;
35494/*!
35495@brief The altitude at which zodiac becomes invisible as the result of fading out or becoming too small.
35496*/
35497float altitudeMax;
35498/*!
35499@brief The altitude at which zodiac begins to fade and/or shrink.
35500*/
35501float altitudeFalloff;
35502/*!
35503@brief When true, zodiac becomes smaller as altitude increases.
35504*/
35505bool altitudeShrinks;
35506/*!
35507@brief When true, zodiac fades out as altitude increases.
35508*/
35509bool altitudeFades;
35510/*!
35511@brief The distance from camera at which the zodiac becomes invisible as the result of fading out.
35512*/
35513float distanceMax;
35514/*!
35515@brief The distance from camera at which the zodiac begins to fade out.
35516*/
35517float distanceFalloff;
35518/*!
35519@brief When true, gradientRange will be used to determine on which polygons the zodiac will render.
35520*/
35521bool useGradientRange;
35522/*!
35523@brief When true, a gradientRange specified on an InteriorInstance or TSStatic will be used instead of the zodiac's gradientRange.
35524*/
35525bool preferDestinationGradients;
35526/*!
35527@brief Zodiac will render on polygons with gradients within the range specified by gradientRange. 0 for floor polys, 90 for wall polys, 180 for ceiling polys.
35528*/
35529Point2F gradientRange;
35530/*!
35531@brief When true, the zodiac will render on polygons with gradients outside of the range specified by gradientRange.
35532*/
35533bool invertGradientRange;
35534
35535/*! @name Scripting
35536@{ */
35537/// @}
35538
35539
35540/*! @name Ungrouped
35541@{ */
35542/// @}
35543
35544
35545/*! @name Object
35546@{ */
35547/// @}
35548
35549
35550/*! @name Editing
35551@{ */
35552/// @}
35553
35554
35555/*! @name Persistence
35556@{ */
35557/// @}
35558
35559};
35560
35561/*!
35562@brief A datablock that specifies a Zodiac Plane effect.
35563
35564afxZodiacData describes a zodiac-like effect called a zodiac plane. It reproduces most of the behavior of normal zodiacs but unlike zodiac decals, it is represented as a flat plane of geometry that can be more flexibly positioned and oriented.
35565
35566@ingroup afxEffects
35567@ingroup AFX
35568@ingroup Datablocks
35569
35570*/
35571class afxZodiacPlaneData : public GameBaseData {
35572public:
35573
35574/*! @name Callbacks
35575@{ */
35576/// @}
35577
35578/*!
35579@brief An image to use as the zodiac's texture.
35580*/
35581filename texture;
35582/*!
35583@brief The zodiac's radius in scene units.
35584*/
35585float radius;
35586/*!
35587@brief The starting angle in degrees of the zodiac's rotation.
35588*/
35589float startAngle;
35590/*!
35591@brief The rate of rotation in degrees-per-second. Zodiacs with a positive rotationRate rotate clockwise, while those with negative values turn counter-clockwise.
35592*/
35593float rotationRate;
35594/*!
35595@brief A duration of time in seconds over which the zodiac grows from a zero size to its full size as specified by the radius.
35596*/
35597float growInTime;
35598/*!
35599@brief A duration of time in seconds over which the zodiac shrinks from full size to invisible.
35600*/
35601float shrinkOutTime;
35602/*!
35603@brief A rate in meters-per-second at which the zodiac grows in size. A negative value will shrink the zodiac.
35604*/
35605float growthRate;
35606/*!
35607@brief A color value for the zodiac.
35608*/
35609LinearColorF color;
35610/*!
35611@brief A blending style for the zodiac. Possible values: normal, additive, or subtractive.
35612*/
35613afxZodiacPlane_BlendType blend;
35614/*!
35615@brief Specifies if the zodiac's rotation should be defined by its constrained transformation.
35616*/
35617bool trackOrientConstraint;
35618/*!
35619@brief Controls whether the zodiac-plane's polygons are rendered when viewed from either side. If set to false, the zodiac-plane will only be seen when viewed from the direction it is facing (according to faceDir).
35620*/
35621bool doubleSided;
35622/*!
35623@brief Specifies which direction the zodiac-plane's polygons face. Possible values: up, down, front, back, right, or left.
35624*/
35625afxZodiacPlane_FacingType faceDir;
35626/*!
35627@brief Normal zodiacs have only one degree of freedom, a rotation around the z-axis. Depending on the setting for trackOrientConstraint, this means that the effect's orientation is either ignored or is limited to influencing the zodiac's angle of rotation. By default, zodiac-plane reproduces this limited behavior in order to match normal zodiacs. When useFullTransform is set to true, the zodiac can be arbitrarily oriented.
35628*/
35629bool useFullTransform;
35630
35631/*! @name Scripting
35632@{ */
35633/// @}
35634
35635
35636/*! @name Ungrouped
35637@{ */
35638/// @}
35639
35640
35641/*! @name Object
35642@{ */
35643/// @}
35644
35645
35646/*! @name Editing
35647@{ */
35648/// @}
35649
35650
35651/*! @name Persistence
35652@{ */
35653/// @}
35654
35655};
35656
35657/*!
35658@brief A ZodiacPlane effect as defined by an afxZodiacPlaneData datablock.
35659
35660@ingroup afxEffects
35661@ingroup AFX
35662
35663*/
35664class afxZodiacPlane : public GameBase {
35665public:
35666
35667/*! @name Callbacks
35668@{ */
35669/// @}
35670
35671/*!
35672@brief Disables rendering of all instances of this type.
35673
35674
35675@ingroup UNDOCUMENTED
35676*/
35677static bool isRenderable;
35678/*!
35679@brief Disables selection of all instances of this type.
35680
35681
35682@ingroup UNDOCUMENTED
35683*/
35684static bool isSelectable;
35685
35686/*! @name Game
35687@{ */
35688/// @}
35689
35690
35691/*! @name GameObject
35692@{ */
35693/// @}
35694
35695
35696/*! @name Transform
35697@{ */
35698/// @}
35699
35700
35701/*! @name Editing
35702@{ */
35703/// @}
35704
35705
35706/*! @name Mounting
35707@{ */
35708/// @}
35709
35710
35711/*! @name Ungrouped
35712@{ */
35713/// @}
35714
35715
35716/*! @name Object
35717@{ */
35718/// @}
35719
35720
35721/*! @name Editing
35722@{ */
35723/// @}
35724
35725
35726/*! @name Persistence
35727@{ */
35728/// @}
35729
35730};
35731
35732/*!
35733@brief Allows legacy sgLightObjectData datablocks to appear in scripts.
35734
35735@ingroup afxMisc
35736@ingroup AFX
35737@ingroup Datablocks
35738
35739*/
35740class sgLightObjectData : public GameBaseData {
35741public:
35742
35743/*! @name Callbacks
35744@{ */
35745/// @}
35746
35747
35748/*! @name Scripting
35749@{ */
35750/// @}
35751
35752
35753/*! @name Ungrouped
35754@{ */
35755/// @}
35756
35757
35758/*! @name Object
35759@{ */
35760/// @}
35761
35762
35763/*! @name Editing
35764@{ */
35765/// @}
35766
35767
35768/*! @name Persistence
35769@{ */
35770/// @}
35771
35772};
35773
35774/*!
35775@brief A datablock for specifiying AFX drag forces.
35776
35777@ingroup afxExperimental
35778@ingroup AFX
35779@ingroup Datablocks
35780
35781*/
35782class afxF_DragData : public GameBaseData {
35783public:
35784
35785/*! @name Callbacks
35786@{ */
35787/// @}
35788
35789/*!
35790@brief ...
35791*/
35792float drag;
35793/*!
35794@brief ...
35795*/
35796float airDensity;
35797/*!
35798@brief ...
35799*/
35800float crossSectionalArea;
35801/*!
35802@brief ...
35803*/
35804string forceSetName;
35805
35806/*! @name Scripting
35807@{ */
35808/// @}
35809
35810
35811/*! @name Ungrouped
35812@{ */
35813/// @}
35814
35815
35816/*! @name Object
35817@{ */
35818/// @}
35819
35820
35821/*! @name Editing
35822@{ */
35823/// @}
35824
35825
35826/*! @name Persistence
35827@{ */
35828/// @}
35829
35830};
35831
35832/*!
35833@brief A datablock for specifiying AFX gravity forces.
35834
35835@ingroup afxExperimental
35836@ingroup AFX
35837@ingroup Datablocks
35838
35839*/
35840class afxF_GravityData : public GameBaseData {
35841public:
35842
35843/*! @name Callbacks
35844@{ */
35845/// @}
35846
35847/*!
35848@brief ...
35849*/
35850float gravity;
35851/*!
35852@brief ...
35853*/
35854string forceSetName;
35855
35856/*! @name Scripting
35857@{ */
35858/// @}
35859
35860
35861/*! @name Ungrouped
35862@{ */
35863/// @}
35864
35865
35866/*! @name Object
35867@{ */
35868/// @}
35869
35870
35871/*! @name Editing
35872@{ */
35873/// @}
35874
35875
35876/*! @name Persistence
35877@{ */
35878/// @}
35879
35880};
35881
35882/*! UNDOCUMENTED!
35883@ingroup UNDOCUMENTED
35884 */
35885class afxXM_BaseData : public GameBaseData {
35886public:
35887
35888/*! @name Callbacks
35889@{ */
35890/// @}
35891
35892/*!
35893@brief ...
35894*/
35895bool ignoreTimeFactor;
35896
35897/*! @name Scripting
35898@{ */
35899/// @}
35900
35901
35902/*! @name Ungrouped
35903@{ */
35904/// @}
35905
35906
35907/*! @name Object
35908@{ */
35909/// @}
35910
35911
35912/*! @name Editing
35913@{ */
35914/// @}
35915
35916
35917/*! @name Persistence
35918@{ */
35919/// @}
35920
35921};
35922
35923/*! UNDOCUMENTED!
35924@ingroup UNDOCUMENTED
35925 */
35926class afxXM_WeightedBaseData : public afxXM_BaseData {
35927public:
35928
35929/*! @name Callbacks
35930@{ */
35931/// @}
35932
35933/*!
35934@brief ...
35935*/
35936float delay;
35937/*!
35938@brief ...
35939*/
35940float lifetime;
35941/*!
35942@brief ...
35943*/
35944float fadeInTime;
35945/*!
35946@brief ...
35947*/
35948float fadeOutTime;
35949/*!
35950@brief ...
35951*/
35952Point2F fadeInEase;
35953/*!
35954@brief ...
35955*/
35956Point2F fadeOutEase;
35957/*!
35958@brief ...
35959*/
35960float lifetimeBias;
35961
35962/*! @name Scripting
35963@{ */
35964/// @}
35965
35966
35967/*! @name Ungrouped
35968@{ */
35969/// @}
35970
35971
35972/*! @name Object
35973@{ */
35974/// @}
35975
35976
35977/*! @name Editing
35978@{ */
35979/// @}
35980
35981
35982/*! @name Persistence
35983@{ */
35984/// @}
35985
35986};
35987
35988/*!
35989@brief An xmod datablock.
35990
35991@ingroup afxExperimental
35992@ingroup afxXMods
35993@ingroup AFX
35994@ingroup Datablocks
35995
35996*/
35997class afxXM_ForceData : public afxXM_WeightedBaseData {
35998public:
35999
36000/*! @name Callbacks
36001@{ */
36002/// @}
36003
36004/*!
36005@brief ...
36006*/
36007string forceSetName;
36008/*!
36009@brief ...
36010*/
36011float updateDT;
36012
36013/*! @name Scripting
36014@{ */
36015/// @}
36016
36017
36018/*! @name Ungrouped
36019@{ */
36020/// @}
36021
36022
36023/*! @name Object
36024@{ */
36025/// @}
36026
36027
36028/*! @name Editing
36029@{ */
36030/// @}
36031
36032
36033/*! @name Persistence
36034@{ */
36035/// @}
36036
36037};
36038
36039/*!
36040@brief A datablock for defining RPG aspects of a spell.
36041
36042@ingroup afxMisc
36043@ingroup AFX
36044@ingroup Datablocks
36045
36046*/
36047class afxRPGMagicSpellData : public GameBaseData {
36048public:
36049
36050/*! @name Callbacks
36051@{ */
36052/// @}
36053
36054/*!
36055@brief ...
36056*/
36057string spellName;
36058/*!
36059@brief ...
36060*/
36061string desc;
36062/*!
36063@brief ...
36064*/
36065afxRPGMagicSpell_TargetType Target;
36066/*!
36067@brief ...
36068*/
36069float range;
36070/*!
36071@brief ...
36072*/
36073int manaCost;
36074/*!
36075@brief ...
36076*/
36077char reagentCost[ 8 ];
36078/*!
36079@brief ...
36080*/
36081string reagentName[ 8 ];
36082/*!
36083*/
36084float castingDur;
36085/*!
36086*/
36087filename iconBitmap;
36088/*!
36089*/
36090string sourcePack;
36091/*!
36092*/
36093bool isPlaceholder;
36094/*!
36095*/
36096char freeTargetStyle;
36097/*!
36098*/
36099bool targetOptional;
36100
36101/*! @name Scripting
36102@{ */
36103/// @}
36104
36105
36106/*! @name Ungrouped
36107@{ */
36108/// @}
36109
36110
36111/*! @name Object
36112@{ */
36113/// @}
36114
36115
36116/*! @name Editing
36117@{ */
36118/// @}
36119
36120
36121/*! @name Persistence
36122@{ */
36123/// @}
36124
36125};
36126
36127/*!
36128@brief A simple but useful GUI control that propagates all events to its parent control.
36129
36130afxEventCatchAll is useful when you want certain events to be handled by its parent afxTSCtrl and not get consumed by certain non-interactive controls like a text HUD.
36131
36132@ingroup afxGUI
36133@ingroup AFX
36134
36135*/
36136class afxEventCatchAll : public GuiControl {
36137public:
36138
36139/*! @name Callbacks
36140@{ */
36141/// @}
36142
36143
36144/*! @name Layout
36145@{ */
36146/// @}
36147
36148
36149/*! @name Control
36150@{ */
36151/// @}
36152
36153
36154/*! @name ToolTip
36155@{ */
36156/// @}
36157
36158
36159/*! @name Editing
36160@{ */
36161/// @}
36162
36163
36164/*! @name Localization
36165@{ */
36166/// @}
36167
36168
36169/*! @name Ungrouped
36170@{ */
36171/// @}
36172
36173
36174/*! @name Object
36175@{ */
36176/// @}
36177
36178
36179/*! @name Editing
36180@{ */
36181/// @}
36182
36183
36184/*! @name Persistence
36185@{ */
36186/// @}
36187
36188};
36189
36190/*!
36191@brief A customized variation of GuiInspectorField.
36192
36193A customized variation of GuiInspectorField.
36194@ingroup AFX
36195
36196*/
36197class afxGuiSubstitutionField : public GuiInspectorField {
36198public:
36199
36200/*! @name Callbacks
36201@{ */
36202/// @}
36203
36204
36205/*! @name Layout
36206@{ */
36207/// @}
36208
36209
36210/*! @name Control
36211@{ */
36212/// @}
36213
36214
36215/*! @name ToolTip
36216@{ */
36217/// @}
36218
36219
36220/*! @name Editing
36221@{ */
36222/// @}
36223
36224
36225/*! @name Localization
36226@{ */
36227/// @}
36228
36229
36230/*! @name Ungrouped
36231@{ */
36232/// @}
36233
36234
36235/*! @name Object
36236@{ */
36237/// @}
36238
36239
36240/*! @name Editing
36241@{ */
36242/// @}
36243
36244
36245/*! @name Persistence
36246@{ */
36247/// @}
36248
36249};
36250
36251/*!
36252@brief Similar to GuiShapeNameHud, afxGuiTextHud displays ShapeBase object names but also allows Gui Text effects.
36253
36254@ingroup GuiGame
36255
36256*/
36257class afxGuiTextHud : public GuiControl {
36258public:
36259
36260/*! @name Callbacks
36261@{ */
36262/// @}
36263
36264
36265/*! @name Colors
36266@{ */
36267/*!
36268@brief ...
36269*/
36270LinearColorF fillColor;
36271/*!
36272@brief ...
36273*/
36274LinearColorF frameColor;
36275/*!
36276@brief ...
36277*/
36278LinearColorF textColor;
36279/// @}
36280
36281
36282/*! @name Misc
36283@{ */
36284/*!
36285@brief ...
36286*/
36287bool showFill;
36288/*!
36289@brief ...
36290*/
36291bool showFrame;
36292/*!
36293@brief ...
36294*/
36295float verticalOffset;
36296/*!
36297@brief ...
36298*/
36299float distanceFade;
36300/*!
36301@brief ...
36302*/
36303bool labelAllShapes;
36304/*!
36305@brief ...
36306*/
36307bool enableControlObjectOcclusion;
36308/// @}
36309
36310
36311/*! @name Layout
36312@{ */
36313/// @}
36314
36315
36316/*! @name Control
36317@{ */
36318/// @}
36319
36320
36321/*! @name ToolTip
36322@{ */
36323/// @}
36324
36325
36326/*! @name Editing
36327@{ */
36328/// @}
36329
36330
36331/*! @name Localization
36332@{ */
36333/// @}
36334
36335
36336/*! @name Ungrouped
36337@{ */
36338/// @}
36339
36340
36341/*! @name Object
36342@{ */
36343/// @}
36344
36345
36346/*! @name Editing
36347@{ */
36348/// @}
36349
36350
36351/*! @name Persistence
36352@{ */
36353/// @}
36354
36355};
36356
36357/*!
36358@brief A simple GUI control used to contain player status bars and a label.
36359
36360@ingroup afxGUI
36361@ingroup AFX
36362
36363*/
36364class afxStatusBox : public GuiBitmapCtrl {
36365public:
36366
36367/*! @name Callbacks
36368@{ */
36369/// @}
36370
36371
36372/*! @name Bitmap
36373@{ */
36374/// @}
36375
36376
36377/*! @name Layout
36378@{ */
36379/// @}
36380
36381
36382/*! @name Control
36383@{ */
36384/// @}
36385
36386
36387/*! @name ToolTip
36388@{ */
36389/// @}
36390
36391
36392/*! @name Editing
36393@{ */
36394/// @}
36395
36396
36397/*! @name Localization
36398@{ */
36399/// @}
36400
36401
36402/*! @name Ungrouped
36403@{ */
36404/// @}
36405
36406
36407/*! @name Object
36408@{ */
36409/// @}
36410
36411
36412/*! @name Editing
36413@{ */
36414/// @}
36415
36416
36417/*! @name Persistence
36418@{ */
36419/// @}
36420
36421};
36422
36423/*!
36424@brief A simple GUI control used for a player status label.
36425
36426@ingroup afxGUI
36427@ingroup AFX
36428
36429*/
36430class afxStatusLabel : public GuiMLTextCtrl {
36431public:
36432
36433/*! @name Callbacks
36434@{ */
36435/// @}
36436
36437
36438/*! @name Text
36439@{ */
36440/// @}
36441
36442
36443/*! @name Layout
36444@{ */
36445/// @}
36446
36447
36448/*! @name Control
36449@{ */
36450/// @}
36451
36452
36453/*! @name ToolTip
36454@{ */
36455/// @}
36456
36457
36458/*! @name Editing
36459@{ */
36460/// @}
36461
36462
36463/*! @name Localization
36464@{ */
36465/// @}
36466
36467
36468/*! @name Ungrouped
36469@{ */
36470/// @}
36471
36472
36473/*! @name Object
36474@{ */
36475/// @}
36476
36477
36478/*! @name Editing
36479@{ */
36480/// @}
36481
36482
36483/*! @name Persistence
36484@{ */
36485/// @}
36486
36487};
36488
36489/*!
36490@brief A ParticlePool datablock.
36491
36492@ingroup afxUtil
36493@ingroup AFX
36494
36495*/
36496class afxParticlePoolData : public GameBaseData {
36497public:
36498
36499/*! @name Callbacks
36500@{ */
36501/// @}
36502
36503/*!
36504@brief ...
36505*/
36506afxParticlePool_PoolType poolType;
36507/*!
36508@brief ...
36509*/
36510LinearColorF baseColor;
36511/*!
36512@brief ...
36513*/
36514float blendWeight;
36515
36516/*! @name Scripting
36517@{ */
36518/// @}
36519
36520
36521/*! @name Ungrouped
36522@{ */
36523/// @}
36524
36525
36526/*! @name Object
36527@{ */
36528/// @}
36529
36530
36531/*! @name Editing
36532@{ */
36533/// @}
36534
36535
36536/*! @name Persistence
36537@{ */
36538/// @}
36539
36540};
36541
36542/*!
36543@brief A ParticlePool object as defined by an afxParticlePoolData datablock.
36544
36545@ingroup afxUtil
36546@ingroup AFX
36547
36548*/
36549class afxParticlePool : public GameBase {
36550public:
36551
36552/*! @name Callbacks
36553@{ */
36554/// @}
36555
36556/*!
36557@brief Disables rendering of all instances of this type.
36558
36559
36560@ingroup UNDOCUMENTED
36561*/
36562static bool isRenderable;
36563/*!
36564@brief Disables selection of all instances of this type.
36565
36566
36567@ingroup UNDOCUMENTED
36568*/
36569static bool isSelectable;
36570
36571/*! @name Game
36572@{ */
36573/// @}
36574
36575
36576/*! @name GameObject
36577@{ */
36578/// @}
36579
36580
36581/*! @name Transform
36582@{ */
36583/// @}
36584
36585
36586/*! @name Editing
36587@{ */
36588/// @}
36589
36590
36591/*! @name Mounting
36592@{ */
36593/// @}
36594
36595
36596/*! @name Ungrouped
36597@{ */
36598/// @}
36599
36600
36601/*! @name Object
36602@{ */
36603/// @}
36604
36605
36606/*! @name Editing
36607@{ */
36608/// @}
36609
36610
36611/*! @name Persistence
36612@{ */
36613/// @}
36614
36615};
36616
36617/*!
36618@brief A datablock for specifiying a 3D path for use with AFX.
36619
36620@ingroup afxUtil
36621@ingroup AFX
36622@ingroup Datablocks
36623
36624*/
36625class afxPathData : public GameBaseData {
36626public:
36627
36628/*! @name Callbacks
36629@{ */
36630/// @}
36631
36632/*!
36633@brief ...
36634*/
36635string points;
36636/*!
36637@brief ...
36638*/
36639string roll;
36640/*!
36641@brief ...
36642*/
36643string times;
36644/*!
36645@brief ...
36646*/
36647string Loop;
36648/*!
36649@brief ...
36650*/
36651float mult;
36652/*!
36653@brief ...
36654*/
36655float delay;
36656/*!
36657@brief ...
36658*/
36659float lifetime;
36660/*!
36661@brief ...
36662*/
36663float timeOffset;
36664/*!
36665@brief ...
36666*/
36667bool reverse;
36668/*!
36669@brief ...
36670*/
36671Point3F offset;
36672/*!
36673@brief ...
36674*/
36675bool echo;
36676/*!
36677@brief ...
36678*/
36679bool concentric;
36680
36681/*! @name Scripting
36682@{ */
36683/// @}
36684
36685
36686/*! @name Ungrouped
36687@{ */
36688/// @}
36689
36690
36691/*! @name Object
36692@{ */
36693/// @}
36694
36695
36696/*! @name Editing
36697@{ */
36698/// @}
36699
36700
36701/*! @name Persistence
36702@{ */
36703/// @}
36704
36705};
36706
36707/*!
36708@brief An xmod datablock.
36709
36710@ingroup afxXMods
36711@ingroup AFX
36712@ingroup Datablocks
36713
36714*/
36715class afxXM_AimData : public afxXM_WeightedBaseData {
36716public:
36717
36718/*! @name Callbacks
36719@{ */
36720/// @}
36721
36722/*!
36723@brief ...
36724*/
36725bool aimZOnly;
36726
36727/*! @name Scripting
36728@{ */
36729/// @}
36730
36731
36732/*! @name Ungrouped
36733@{ */
36734/// @}
36735
36736
36737/*! @name Object
36738@{ */
36739/// @}
36740
36741
36742/*! @name Editing
36743@{ */
36744/// @}
36745
36746
36747/*! @name Persistence
36748@{ */
36749/// @}
36750
36751};
36752
36753/*!
36754@brief An xmod datablock.
36755
36756@ingroup afxXMods
36757@ingroup AFX
36758@ingroup Datablocks
36759
36760*/
36761class afxXM_AltitudeConformData : public afxXM_WeightedBaseData {
36762public:
36763
36764/*! @name Callbacks
36765@{ */
36766/// @}
36767
36768/*!
36769@brief ...
36770*/
36771float height;
36772/*!
36773@brief ...
36774*/
36775bool conformToTerrain;
36776/*!
36777@brief ...
36778*/
36779bool conformToInteriors;
36780/*!
36781@brief ...
36782*/
36783bool freeze;
36784/*!
36785@brief ...
36786*/
36787int interiorTypes;
36788/*!
36789@brief ...
36790*/
36791int terrainTypes;
36792
36793/*! @name Scripting
36794@{ */
36795/// @}
36796
36797
36798/*! @name Ungrouped
36799@{ */
36800/// @}
36801
36802
36803/*! @name Object
36804@{ */
36805/// @}
36806
36807
36808/*! @name Editing
36809@{ */
36810/// @}
36811
36812
36813/*! @name Persistence
36814@{ */
36815/// @}
36816
36817};
36818
36819/*!
36820@brief An xmod datablock.
36821
36822@ingroup afxXMods
36823@ingroup AFX
36824@ingroup Datablocks
36825
36826*/
36827class afxXM_BoxAdaptData : public afxXM_WeightedBaseData {
36828public:
36829
36830/*! @name Callbacks
36831@{ */
36832/// @}
36833
36834/*!
36835@brief ...
36836*/
36837float scaleFactor;
36838/*!
36839@brief ...
36840*/
36841Point2F dimensionRange;
36842
36843/*! @name Scripting
36844@{ */
36845/// @}
36846
36847
36848/*! @name Ungrouped
36849@{ */
36850/// @}
36851
36852
36853/*! @name Object
36854@{ */
36855/// @}
36856
36857
36858/*! @name Editing
36859@{ */
36860/// @}
36861
36862
36863/*! @name Persistence
36864@{ */
36865/// @}
36866
36867};
36868
36869/*!
36870@brief An xmod datablock.
36871
36872@ingroup afxXMods
36873@ingroup AFX
36874@ingroup Datablocks
36875
36876*/
36877class afxXM_BoxConformData : public afxXM_BaseData {
36878public:
36879
36880/*! @name Callbacks
36881@{ */
36882/// @}
36883
36884/*!
36885@brief ...
36886*/
36887afxXM_BoxConformType boxAlignment;
36888
36889/*! @name Scripting
36890@{ */
36891/// @}
36892
36893
36894/*! @name Ungrouped
36895@{ */
36896/// @}
36897
36898
36899/*! @name Object
36900@{ */
36901/// @}
36902
36903
36904/*! @name Editing
36905@{ */
36906/// @}
36907
36908
36909/*! @name Persistence
36910@{ */
36911/// @}
36912
36913};
36914
36915/*!
36916@brief An xmod datablock.
36917
36918@ingroup afxXMods
36919@ingroup AFX
36920@ingroup Datablocks
36921
36922*/
36923class afxXM_BoxHeightOffsetData : public afxXM_BaseData {
36924public:
36925
36926/*! @name Callbacks
36927@{ */
36928/// @}
36929
36930/*!
36931*/
36932Point3F offset;
36933
36934/*! @name Scripting
36935@{ */
36936/// @}
36937
36938
36939/*! @name Ungrouped
36940@{ */
36941/// @}
36942
36943
36944/*! @name Object
36945@{ */
36946/// @}
36947
36948
36949/*! @name Editing
36950@{ */
36951/// @}
36952
36953
36954/*! @name Persistence
36955@{ */
36956/// @}
36957
36958};
36959
36960/*!
36961@brief An xmod datablock.
36962
36963@ingroup afxXMods
36964@ingroup AFX
36965@ingroup Datablocks
36966
36967*/
36968class afxXM_FreezeData : public afxXM_BaseData {
36969public:
36970
36971/*! @name Callbacks
36972@{ */
36973/// @}
36974
36975/*!
36976@brief ...
36977*/
36978int mask;
36979/*!
36980@brief ...
36981*/
36982float delay;
36983
36984/*! @name Scripting
36985@{ */
36986/// @}
36987
36988
36989/*! @name Ungrouped
36990@{ */
36991/// @}
36992
36993
36994/*! @name Object
36995@{ */
36996/// @}
36997
36998
36999/*! @name Editing
37000@{ */
37001/// @}
37002
37003
37004/*! @name Persistence
37005@{ */
37006/// @}
37007
37008};
37009
37010/*!
37011@brief An xmod datablock.
37012
37013@ingroup afxXMods
37014@ingroup AFX
37015@ingroup Datablocks
37016
37017*/
37018class afxXM_GroundConformData : public afxXM_WeightedBaseData {
37019public:
37020
37021/*! @name Callbacks
37022@{ */
37023/// @}
37024
37025/*!
37026@brief ...
37027*/
37028float height;
37029/*!
37030@brief ...
37031*/
37032bool conformToTerrain;
37033/*!
37034@brief ...
37035*/
37036bool conformToInteriors;
37037/*!
37038@brief ...
37039*/
37040bool conformOrientation;
37041
37042/*! @name Scripting
37043@{ */
37044/// @}
37045
37046
37047/*! @name Ungrouped
37048@{ */
37049/// @}
37050
37051
37052/*! @name Object
37053@{ */
37054/// @}
37055
37056
37057/*! @name Editing
37058@{ */
37059/// @}
37060
37061
37062/*! @name Persistence
37063@{ */
37064/// @}
37065
37066};
37067
37068/*!
37069@brief An xmod datablock.
37070
37071@ingroup afxXMods
37072@ingroup AFX
37073@ingroup Datablocks
37074
37075*/
37076class afxXM_HeightSamplerData : public afxXM_WeightedBaseData {
37077public:
37078
37079/*! @name Callbacks
37080@{ */
37081/// @}
37082
37083
37084/*! @name Scripting
37085@{ */
37086/// @}
37087
37088
37089/*! @name Ungrouped
37090@{ */
37091/// @}
37092
37093
37094/*! @name Object
37095@{ */
37096/// @}
37097
37098
37099/*! @name Editing
37100@{ */
37101/// @}
37102
37103
37104/*! @name Persistence
37105@{ */
37106/// @}
37107
37108};
37109
37110/*!
37111@brief An xmod datablock.
37112
37113@ingroup afxXMods
37114@ingroup AFX
37115@ingroup Datablocks
37116
37117*/
37118class afxXM_MountedImageNodeData : public afxXM_BaseData {
37119public:
37120
37121/*! @name Callbacks
37122@{ */
37123/// @}
37124
37125/*!
37126@brief ...
37127*/
37128int imageSlot;
37129/*!
37130@brief ...
37131*/
37132string nodeName;
37133
37134/*! @name Scripting
37135@{ */
37136/// @}
37137
37138
37139/*! @name Ungrouped
37140@{ */
37141/// @}
37142
37143
37144/*! @name Object
37145@{ */
37146/// @}
37147
37148
37149/*! @name Editing
37150@{ */
37151/// @}
37152
37153
37154/*! @name Persistence
37155@{ */
37156/// @}
37157
37158};
37159
37160/*!
37161@brief An xmod datablock.
37162
37163@ingroup afxXMods
37164@ingroup AFX
37165@ingroup Datablocks
37166
37167*/
37168class afxXM_LocalOffsetData : public afxXM_WeightedBaseData {
37169public:
37170
37171/*! @name Callbacks
37172@{ */
37173/// @}
37174
37175/*!
37176@brief ...
37177*/
37178Point3F localOffset;
37179/*!
37180@brief ...
37181*/
37182bool offsetPos2;
37183
37184/*! @name Scripting
37185@{ */
37186/// @}
37187
37188
37189/*! @name Ungrouped
37190@{ */
37191/// @}
37192
37193
37194/*! @name Object
37195@{ */
37196/// @}
37197
37198
37199/*! @name Editing
37200@{ */
37201/// @}
37202
37203
37204/*! @name Persistence
37205@{ */
37206/// @}
37207
37208};
37209
37210/*!
37211@brief An xmod datablock.
37212
37213@ingroup afxXMods
37214@ingroup AFX
37215@ingroup Datablocks
37216
37217*/
37218class afxXM_WorldOffsetData : public afxXM_WeightedBaseData {
37219public:
37220
37221/*! @name Callbacks
37222@{ */
37223/// @}
37224
37225/*!
37226@brief ...
37227*/
37228Point3F worldOffset;
37229/*!
37230@brief ...
37231*/
37232bool offsetPos2;
37233
37234/*! @name Scripting
37235@{ */
37236/// @}
37237
37238
37239/*! @name Ungrouped
37240@{ */
37241/// @}
37242
37243
37244/*! @name Object
37245@{ */
37246/// @}
37247
37248
37249/*! @name Editing
37250@{ */
37251/// @}
37252
37253
37254/*! @name Persistence
37255@{ */
37256/// @}
37257
37258};
37259
37260/*!
37261@brief An xmod datablock.
37262
37263@ingroup afxXMods
37264@ingroup AFX
37265@ingroup Datablocks
37266
37267*/
37268class afxXM_OscillateData : public afxXM_WeightedBaseData {
37269public:
37270
37271/*! @name Callbacks
37272@{ */
37273/// @}
37274
37275/*!
37276@brief ...
37277*/
37278int mask;
37279/*!
37280@brief ...
37281*/
37282Point3F min;
37283/*!
37284@brief ...
37285*/
37286Point3F max;
37287/*!
37288@brief ...
37289*/
37290float speed;
37291/*!
37292@brief ...
37293*/
37294Point3F axis;
37295/*!
37296@brief ...
37297*/
37298bool additiveScale;
37299/*!
37300@brief ...
37301*/
37302bool localOffset;
37303
37304/*! @name Scripting
37305@{ */
37306/// @}
37307
37308
37309/*! @name Ungrouped
37310@{ */
37311/// @}
37312
37313
37314/*! @name Object
37315@{ */
37316/// @}
37317
37318
37319/*! @name Editing
37320@{ */
37321/// @}
37322
37323
37324/*! @name Persistence
37325@{ */
37326/// @}
37327
37328};
37329
37330/*!
37331@brief An xmod datablock.
37332
37333@ingroup afxXMods
37334@ingroup AFX
37335@ingroup Datablocks
37336
37337*/
37338class afxXM_OscillateZodiacColorData : public afxXM_WeightedBaseData {
37339public:
37340
37341/*! @name Callbacks
37342@{ */
37343/// @}
37344
37345/*!
37346@brief ...
37347*/
37348LinearColorF colorA;
37349/*!
37350@brief ...
37351*/
37352LinearColorF colorB;
37353/*!
37354@brief ...
37355*/
37356float speed;
37357
37358/*! @name Scripting
37359@{ */
37360/// @}
37361
37362
37363/*! @name Ungrouped
37364@{ */
37365/// @}
37366
37367
37368/*! @name Object
37369@{ */
37370/// @}
37371
37372
37373/*! @name Editing
37374@{ */
37375/// @}
37376
37377
37378/*! @name Persistence
37379@{ */
37380/// @}
37381
37382};
37383
37384/*!
37385@brief An xmod datablock.
37386
37387@ingroup afxXMods
37388@ingroup AFX
37389@ingroup Datablocks
37390
37391*/
37392class afxXM_PathConformData : public afxXM_WeightedBaseData {
37393public:
37394
37395/*! @name Callbacks
37396@{ */
37397/// @}
37398
37399/*!
37400@brief ...
37401*/
37402string paths;
37403/*!
37404@brief ...
37405*/
37406float pathMult;
37407/*!
37408@brief ...
37409*/
37410float pathTimeOffset;
37411/*!
37412@brief ...
37413*/
37414bool orientToPath;
37415
37416/*! @name Scripting
37417@{ */
37418/// @}
37419
37420
37421/*! @name Ungrouped
37422@{ */
37423/// @}
37424
37425
37426/*! @name Object
37427@{ */
37428/// @}
37429
37430
37431/*! @name Editing
37432@{ */
37433/// @}
37434
37435
37436/*! @name Persistence
37437@{ */
37438/// @}
37439
37440};
37441
37442/*!
37443@brief An xmod datablock.
37444
37445@ingroup afxXMods
37446@ingroup AFX
37447@ingroup Datablocks
37448
37449*/
37450class afxXM_PivotNodeOffsetData : public afxXM_BaseData {
37451public:
37452
37453/*! @name Callbacks
37454@{ */
37455/// @}
37456
37457/*!
37458@brief ...
37459*/
37460string nodeName;
37461/*!
37462@brief ...
37463*/
37464bool nodeIsStatic;
37465
37466/*! @name Scripting
37467@{ */
37468/// @}
37469
37470
37471/*! @name Ungrouped
37472@{ */
37473/// @}
37474
37475
37476/*! @name Object
37477@{ */
37478/// @}
37479
37480
37481/*! @name Editing
37482@{ */
37483/// @}
37484
37485
37486/*! @name Persistence
37487@{ */
37488/// @}
37489
37490};
37491
37492/*!
37493@brief An xmod datablock.
37494
37495@ingroup afxXMods
37496@ingroup AFX
37497@ingroup Datablocks
37498
37499*/
37500class afxXM_RandomRotData : public afxXM_BaseData {
37501public:
37502
37503/*! @name Callbacks
37504@{ */
37505/// @}
37506
37507/*!
37508@brief ...
37509*/
37510Point3F axis;
37511/*!
37512@brief ...
37513*/
37514float thetaMin;
37515/*!
37516@brief ...
37517*/
37518float thetaMax;
37519/*!
37520@brief ...
37521*/
37522float phiMin;
37523/*!
37524@brief ...
37525*/
37526float phiMax;
37527
37528/*! @name Scripting
37529@{ */
37530/// @}
37531
37532
37533/*! @name Ungrouped
37534@{ */
37535/// @}
37536
37537
37538/*! @name Object
37539@{ */
37540/// @}
37541
37542
37543/*! @name Editing
37544@{ */
37545/// @}
37546
37547
37548/*! @name Persistence
37549@{ */
37550/// @}
37551
37552};
37553
37554/*!
37555@brief An xmod datablock.
37556
37557@ingroup afxXMods
37558@ingroup AFX
37559@ingroup Datablocks
37560
37561*/
37562class afxXM_ScaleData : public afxXM_WeightedBaseData {
37563public:
37564
37565/*! @name Callbacks
37566@{ */
37567/// @}
37568
37569/*!
37570@brief ...
37571*/
37572Point3F scale;
37573
37574/*! @name Scripting
37575@{ */
37576/// @}
37577
37578
37579/*! @name Ungrouped
37580@{ */
37581/// @}
37582
37583
37584/*! @name Object
37585@{ */
37586/// @}
37587
37588
37589/*! @name Editing
37590@{ */
37591/// @}
37592
37593
37594/*! @name Persistence
37595@{ */
37596/// @}
37597
37598};
37599
37600/*!
37601@brief An xmod datablock.
37602
37603@ingroup afxXMods
37604@ingroup AFX
37605@ingroup Datablocks
37606
37607*/
37608class afxXM_ShockwaveData : public afxXM_BaseData {
37609public:
37610
37611/*! @name Callbacks
37612@{ */
37613/// @}
37614
37615/*!
37616@brief ...
37617*/
37618float rate;
37619/*!
37620@brief ...
37621*/
37622bool aimZOnly;
37623
37624/*! @name Scripting
37625@{ */
37626/// @}
37627
37628
37629/*! @name Ungrouped
37630@{ */
37631/// @}
37632
37633
37634/*! @name Object
37635@{ */
37636/// @}
37637
37638
37639/*! @name Editing
37640@{ */
37641/// @}
37642
37643
37644/*! @name Persistence
37645@{ */
37646/// @}
37647
37648};
37649
37650/*!
37651@brief An xmod datablock.
37652
37653@ingroup afxXMods
37654@ingroup AFX
37655@ingroup Datablocks
37656
37657*/
37658class afxXM_SpinData : public afxXM_WeightedBaseData {
37659public:
37660
37661/*! @name Callbacks
37662@{ */
37663/// @}
37664
37665/*!
37666@brief ...
37667*/
37668Point3F spinAxis;
37669/*!
37670@brief ...
37671*/
37672float spinAngle;
37673/*!
37674@brief ...
37675*/
37676float spinAngleVariance;
37677/*!
37678@brief ...
37679*/
37680float spinRate;
37681/*!
37682@brief ...
37683*/
37684float spinRateVariance;
37685
37686/*! @name Scripting
37687@{ */
37688/// @}
37689
37690
37691/*! @name Ungrouped
37692@{ */
37693/// @}
37694
37695
37696/*! @name Object
37697@{ */
37698/// @}
37699
37700
37701/*! @name Editing
37702@{ */
37703/// @}
37704
37705
37706/*! @name Persistence
37707@{ */
37708/// @}
37709
37710};
37711
37712/*!
37713@brief An xmod datablock.
37714
37715@ingroup afxXMods
37716@ingroup AFX
37717@ingroup Datablocks
37718
37719*/
37720class afxXM_VelocityOffsetData : public afxXM_WeightedBaseData {
37721public:
37722
37723/*! @name Callbacks
37724@{ */
37725/// @}
37726
37727/*!
37728@brief ...
37729*/
37730float offsetFactor;
37731/*!
37732@brief ...
37733*/
37734bool offsetPos2;
37735/*!
37736@brief ...
37737*/
37738bool normalize;
37739
37740/*! @name Scripting
37741@{ */
37742/// @}
37743
37744
37745/*! @name Ungrouped
37746@{ */
37747/// @}
37748
37749
37750/*! @name Object
37751@{ */
37752/// @}
37753
37754
37755/*! @name Editing
37756@{ */
37757/// @}
37758
37759
37760/*! @name Persistence
37761@{ */
37762/// @}
37763
37764};
37765
37766/*!
37767@brief An xmod datablock.
37768
37769@ingroup afxXMods
37770@ingroup AFX
37771@ingroup Datablocks
37772
37773*/
37774class afxXM_WaveBaseData : public afxXM_WeightedBaseData {
37775public:
37776
37777/*! @name Callbacks
37778@{ */
37779/// @}
37780
37781/*!
37782@brief ...
37783*/
37784afxXM_WaveFormType waveform;
37785/*!
37786@brief ...
37787*/
37788afxXM_WaveParamType parameter;
37789/*!
37790@brief ...
37791*/
37792afxXM_WaveOpType op;
37793/*!
37794@brief waves per second
37795*/
37796float speed;
37797/*!
37798@brief ...
37799*/
37800float speedVariance;
37801/*!
37802@brief ...
37803*/
37804float acceleration;
37805/*!
37806@brief ...
37807*/
37808float phaseShift;
37809/*!
37810@brief ...
37811*/
37812float dutyCycle;
37813/*!
37814@brief ...
37815*/
37816float dutyShift;
37817/*!
37818@brief ...
37819*/
37820float offDutyT;
37821/*!
37822@brief ...
37823*/
37824ByteRange wavesPerPulse;
37825/*!
37826@brief ...
37827*/
37828ByteRange wavesPerRest;
37829/*!
37830@brief ...
37831*/
37832float restDuration;
37833/*!
37834@brief ...
37835*/
37836float restDurationVariance;
37837/*!
37838@brief ...
37839*/
37840Point3F axis;
37841/*!
37842@brief ...
37843*/
37844bool axisIsLocal;
37845
37846/*! @name Scripting
37847@{ */
37848/// @}
37849
37850
37851/*! @name Ungrouped
37852@{ */
37853/// @}
37854
37855
37856/*! @name Object
37857@{ */
37858/// @}
37859
37860
37861/*! @name Editing
37862@{ */
37863/// @}
37864
37865
37866/*! @name Persistence
37867@{ */
37868/// @}
37869
37870};
37871
37872/*!
37873@brief An xmod datablock.
37874
37875@ingroup afxXMods
37876@ingroup AFX
37877@ingroup Datablocks
37878
37879*/
37880class afxXM_WaveRiderBaseData : public afxXM_WeightedBaseData {
37881public:
37882
37883/*! @name Callbacks
37884@{ */
37885/// @}
37886
37887/*!
37888@brief ...
37889*/
37890afxXM_WaveFormType waveform;
37891/*!
37892@brief ...
37893*/
37894afxXM_WaveParamType parameter;
37895/*!
37896@brief ...
37897*/
37898afxXM_WaveOpType op;
37899/*!
37900@brief ...
37901*/
37902float offDutyT;
37903/*!
37904@brief ...
37905*/
37906Point3F axis;
37907/*!
37908@brief ...
37909*/
37910bool axisIsLocal;
37911
37912/*! @name Scripting
37913@{ */
37914/// @}
37915
37916
37917/*! @name Ungrouped
37918@{ */
37919/// @}
37920
37921
37922/*! @name Object
37923@{ */
37924/// @}
37925
37926
37927/*! @name Editing
37928@{ */
37929/// @}
37930
37931
37932/*! @name Persistence
37933@{ */
37934/// @}
37935
37936};
37937
37938/*!
37939@brief An xmod datablock.
37940
37941@ingroup afxXMods
37942@ingroup AFX
37943@ingroup Datablocks
37944
37945*/
37946class afxXM_WaveColorData : public afxXM_WaveBaseData {
37947public:
37948
37949/*! @name Callbacks
37950@{ */
37951/// @}
37952
37953/*!
37954@brief ...
37955*/
37956LinearColorF a;
37957/*!
37958@brief ...
37959*/
37960LinearColorF b;
37961/*!
37962@brief ...
37963*/
37964LinearColorF aVariance;
37965/*!
37966@brief ...
37967*/
37968LinearColorF bVariance;
37969/*!
37970@brief ...
37971*/
37972bool syncVariances;
37973
37974/*! @name Scripting
37975@{ */
37976/// @}
37977
37978
37979/*! @name Ungrouped
37980@{ */
37981/// @}
37982
37983
37984/*! @name Object
37985@{ */
37986/// @}
37987
37988
37989/*! @name Editing
37990@{ */
37991/// @}
37992
37993
37994/*! @name Persistence
37995@{ */
37996/// @}
37997
37998};
37999
38000/*!
38001@brief An xmod datablock.
38002
38003@ingroup afxXMods
38004@ingroup AFX
38005@ingroup Datablocks
38006
38007*/
38008class afxXM_WaveRiderColorData : public afxXM_WaveRiderBaseData {
38009public:
38010
38011/*! @name Callbacks
38012@{ */
38013/// @}
38014
38015/*!
38016@brief ...
38017*/
38018LinearColorF a;
38019/*!
38020@brief ...
38021*/
38022LinearColorF b;
38023/*!
38024@brief ...
38025*/
38026LinearColorF aVariance;
38027/*!
38028@brief ...
38029*/
38030LinearColorF bVariance;
38031/*!
38032@brief ...
38033*/
38034bool syncVariances;
38035
38036/*! @name Scripting
38037@{ */
38038/// @}
38039
38040
38041/*! @name Ungrouped
38042@{ */
38043/// @}
38044
38045
38046/*! @name Object
38047@{ */
38048/// @}
38049
38050
38051/*! @name Editing
38052@{ */
38053/// @}
38054
38055
38056/*! @name Persistence
38057@{ */
38058/// @}
38059
38060};
38061
38062/*!
38063@brief An xmod datablock.
38064
38065@ingroup afxXMods
38066@ingroup AFX
38067@ingroup Datablocks
38068
38069*/
38070class afxXM_WaveScalarData : public afxXM_WaveBaseData {
38071public:
38072
38073/*! @name Callbacks
38074@{ */
38075/// @}
38076
38077/*!
38078@brief ...
38079*/
38080float a;
38081/*!
38082@brief ...
38083*/
38084float b;
38085/*!
38086@brief ...
38087*/
38088float aVariance;
38089/*!
38090@brief ...
38091*/
38092float bVariance;
38093/*!
38094@brief ...
38095*/
38096bool syncVariances;
38097
38098/*! @name Scripting
38099@{ */
38100/// @}
38101
38102
38103/*! @name Ungrouped
38104@{ */
38105/// @}
38106
38107
38108/*! @name Object
38109@{ */
38110/// @}
38111
38112
38113/*! @name Editing
38114@{ */
38115/// @}
38116
38117
38118/*! @name Persistence
38119@{ */
38120/// @}
38121
38122};
38123
38124/*!
38125@brief An xmod datablock.
38126
38127@ingroup afxXMods
38128@ingroup AFX
38129@ingroup Datablocks
38130
38131*/
38132class afxXM_WaveRiderScalarData : public afxXM_WaveRiderBaseData {
38133public:
38134
38135/*! @name Callbacks
38136@{ */
38137/// @}
38138
38139/*!
38140@brief ...
38141*/
38142float a;
38143/*!
38144@brief ...
38145*/
38146float b;
38147/*!
38148@brief ...
38149*/
38150float aVariance;
38151/*!
38152@brief ...
38153*/
38154float bVariance;
38155/*!
38156@brief ...
38157*/
38158bool syncVariances;
38159
38160/*! @name Scripting
38161@{ */
38162/// @}
38163
38164
38165/*! @name Ungrouped
38166@{ */
38167/// @}
38168
38169
38170/*! @name Object
38171@{ */
38172/// @}
38173
38174
38175/*! @name Editing
38176@{ */
38177/// @}
38178
38179
38180/*! @name Persistence
38181@{ */
38182/// @}
38183
38184};
38185
38186/*! UNDOCUMENTED!
38187@ingroup UNDOCUMENTED
38188 */
38189class VObject : public SimObject {
38190public:
38191/*!
38192@brief Save to a given filename.
38193
38194@param pFileName The target file to write to.
38195@return Returns true if the write was successful.*/
38196bool writeFile( String fileName="" );
38197/*!
38198@brief Clears the object and loads the new data from the given filename.
38199
38200@param pFileName The target file to read from.
38201@return Returns true if the read was successful.*/
38202bool readFile( String fileName="" );
38203/*!
38204@brief Get the root object.
38205
38206@return Returns the SimObjectId for the root object.*/
38207int getRoot();
38208/*!
38209@brief Get the parent object.
38210
38211@return Returns the SimObjectId for the parent object.*/
38212int getParent();
38213/*!
38214@brief Get the index of this object relative to its siblings.
38215
38216@return Returns the index of this object.*/
38217int getIndex();
38218/*!
38219@brief Get the number of child objects.
38220
38221@return Returns the number of child objects.*/
38222int getCount();
38223/*!
38224@brief Get the object corresponding to the given index.
38225
38226@param pIndex The index of the object you wish to retrieve.
38227@return Returns the SimObjectID for the object.*/
38228int getObject( int index=0 );
38229/*!
38230@brief Detaches and deletes all of the child objects.
38231
38232@return No return value.*/
38233void clear();
38234/*!
38235@brief Add a child object to this node.
38236
38237@param pObject The SimObjectID of the object to be added to this node.
38238@return No return value.*/
38239void addObject( SimObject simObj=nullAsType<SimObject*>() );
38240/*!
38241@brief Remove the target object from this node.
38242
38243@param pObject The SimObjectID of the object to be removed from this node.
38244@return No return value.*/
38245void removeObject( SimObject simObj=nullAsType<SimObject*>() );
38246/*!
38247@brief Force this label to be unique.
38248
38249@param pLabel The name you wish to reference this object by.
38250@return No return value.*/
38251void setLabelUnique( String label="" );
38252
38253/*! @name Callbacks
38254@{ */
38255/// @}
38256
38257/*!
38258@brief Enable or Disable the object from playback.
38259*/
38260bool Enabled;
38261/*!
38262@brief The label this object is referenced by.
38263*/
38264string Label;
38265};
38266
38267/*! UNDOCUMENTED!
38268@ingroup UNDOCUMENTED
38269 */
38270class VEvent : public VObject {
38271public:
38272
38273/*! @name Callbacks
38274@{ */
38275/// @}
38276
38277/*!
38278@brief The time that this event is triggered.
38279*/
38280int TriggerTime;
38281/*!
38282@brief The total duration that this event plays for.
38283*/
38284int Duration;
38285};
38286
38287/*! UNDOCUMENTED!
38288@ingroup UNDOCUMENTED
38289 */
38290class VGroup : public VObject {
38291public:
38292
38293/*! @name Callbacks
38294@{ */
38295/// @}
38296
38297};
38298
38299/*! UNDOCUMENTED!
38300@ingroup UNDOCUMENTED
38301 */
38302class VTrack : public VObject {
38303public:
38304
38305/*! @name Callbacks
38306@{ */
38307/// @}
38308
38309};
38310
38311/*! UNDOCUMENTED!
38312@ingroup UNDOCUMENTED
38313 */
38314class VSceneObjectEvent : public VEvent {
38315public:
38316/*!
38317@brief Get the object this group references.
38318
38319@return Returns the SimObjectID for the object.*/
38320int getSceneObject();
38321
38322/*! @name Callbacks
38323@{ */
38324/// @}
38325
38326};
38327
38328/*! UNDOCUMENTED!
38329@ingroup UNDOCUMENTED
38330 */
38331class VShapeAnimationEvent : public VSceneObjectEvent {
38332public:
38333
38334/*! @name Callbacks
38335@{ */
38336/// @}
38337
38338/*!
38339@brief The name of the Animation Sequence to play upon triggering.
38340*/
38341string AnimationData;
38342/*!
38343@brief Force the Event's Duration to match the length of the Animation.
38344*/
38345bool AutoDuration;
38346};
38347
38348/*! UNDOCUMENTED!
38349@ingroup UNDOCUMENTED
38350 */
38351class VSceneObjectGroup : public VGroup {
38352public:
38353/*!
38354@brief Get the object this group references.
38355
38356@return Returns the SimObjectID for the object.*/
38357int getSceneObject();
38358
38359/*! @name Callbacks
38360@{ */
38361/// @}
38362
38363/*!
38364@brief The name of the data field referencing the targeted object.
38365*/
38366string Reference;
38367};
38368
38369/*! UNDOCUMENTED!
38370@ingroup UNDOCUMENTED
38371 */
38372class VCameraGroup : public VSceneObjectGroup {
38373public:
38374
38375/*! @name Callbacks
38376@{ */
38377/// @}
38378
38379};
38380
38381/*! UNDOCUMENTED!
38382@ingroup UNDOCUMENTED
38383 */
38384class VCameraShakeEvent : public VEvent {
38385public:
38386
38387/*! @name Callbacks
38388@{ */
38389/// @}
38390
38391/*!
38392@brief Amplitude of the Camera Shake event.
38393*/
38394Point3F Amplitude;
38395/*!
38396@brief Falloff of the Camera Shake event.
38397*/
38398float Falloff;
38399/*!
38400@brief Frequency of the Camera Shake event.
38401*/
38402Point3F Frequency;
38403};
38404
38405/*! UNDOCUMENTED!
38406@ingroup UNDOCUMENTED
38407 */
38408class VSceneObjectTrack : public VTrack {
38409public:
38410/*!
38411@brief Get the object this group references.
38412
38413@return Returns the SimObjectID for the object.*/
38414int getSceneObject();
38415
38416/*! @name Callbacks
38417@{ */
38418/// @}
38419
38420};
38421
38422/*! UNDOCUMENTED!
38423@ingroup UNDOCUMENTED
38424 */
38425class VCameraTrack : public VSceneObjectTrack {
38426public:
38427
38428/*! @name Callbacks
38429@{ */
38430/// @}
38431
38432};
38433
38434/*! UNDOCUMENTED!
38435@ingroup UNDOCUMENTED
38436 */
38437class VCameraShakeTrack : public VCameraTrack {
38438public:
38439
38440/*! @name Callbacks
38441@{ */
38442/// @}
38443
38444};
38445
38446/*! UNDOCUMENTED!
38447@ingroup UNDOCUMENTED
38448 */
38449class VDirectorEvent : public VEvent {
38450public:
38451
38452/*! @name Callbacks
38453@{ */
38454/// @}
38455
38456/*!
38457@brief The name of the CameraGroup that will be activated upon triggering.
38458*/
38459string Target;
38460};
38461
38462/*! UNDOCUMENTED!
38463@ingroup UNDOCUMENTED
38464 */
38465class VDirectorGroup : public VGroup {
38466public:
38467
38468/*! @name Callbacks
38469@{ */
38470/// @}
38471
38472};
38473
38474/*! UNDOCUMENTED!
38475@ingroup UNDOCUMENTED
38476 */
38477class VSceneJumpEvent : public VEvent {
38478public:
38479
38480/*! @name Callbacks
38481@{ */
38482/// @}
38483
38484/*!
38485@brief The name of the Scene that the controller will jump to upon triggering.
38486*/
38487string Target;
38488};
38489
38490/*! UNDOCUMENTED!
38491@ingroup UNDOCUMENTED
38492 */
38493class VSceneJumpTrack : public VTrack {
38494public:
38495
38496/*! @name Callbacks
38497@{ */
38498/// @}
38499
38500};
38501
38502/*! UNDOCUMENTED!
38503@ingroup UNDOCUMENTED
38504 */
38505class VSlowMoEvent : public VEvent {
38506public:
38507
38508/*! @name Callbacks
38509@{ */
38510/// @}
38511
38512/*!
38513@brief The Time Scale to be applied to the Root Controller.
38514*/
38515float TimeScale;
38516};
38517
38518/*! UNDOCUMENTED!
38519@ingroup UNDOCUMENTED
38520 */
38521class VSlowMoTrack : public VTrack {
38522public:
38523
38524/*! @name Callbacks
38525@{ */
38526/// @}
38527
38528};
38529
38530/*! UNDOCUMENTED!
38531@ingroup UNDOCUMENTED
38532 */
38533class VFadeEvent : public VEvent {
38534public:
38535
38536/*! @name Callbacks
38537@{ */
38538/// @}
38539
38540};
38541
38542/*! UNDOCUMENTED!
38543@ingroup UNDOCUMENTED
38544 */
38545class VFadeTrack : public VTrack {
38546public:
38547
38548/*! @name Callbacks
38549@{ */
38550/// @}
38551
38552};
38553
38554/*! UNDOCUMENTED!
38555@ingroup UNDOCUMENTED
38556 */
38557class VSpawnSphereGroup : public VSceneObjectGroup {
38558public:
38559
38560/*! @name Callbacks
38561@{ */
38562/// @}
38563
38564};
38565
38566/*! UNDOCUMENTED!
38567@ingroup UNDOCUMENTED
38568 */
38569class VSpawnSphereSpawnTargetEvent : public VEvent {
38570public:
38571
38572/*! @name Callbacks
38573@{ */
38574/// @}
38575
38576};
38577
38578/*! UNDOCUMENTED!
38579@ingroup UNDOCUMENTED
38580 */
38581class VSpawnSphereSpawnTargetTrack : public VSceneObjectTrack {
38582public:
38583
38584/*! @name Callbacks
38585@{ */
38586/// @}
38587
38588/*!
38589@brief Despawn all targets when the Controller loops?
38590*/
38591bool DespawnOnLoop;
38592/*!
38593@brief Despawn all targets when the Controller stops playing?
38594*/
38595bool DespawnOnStop;
38596};
38597
38598/*! UNDOCUMENTED!
38599@ingroup UNDOCUMENTED
38600 */
38601class VLightObjectAnimationEvent : public VEvent {
38602public:
38603
38604/*! @name Callbacks
38605@{ */
38606/// @}
38607
38608/*!
38609*/
38610LightAnimData AnimationData;
38611};
38612
38613/*! UNDOCUMENTED!
38614@ingroup UNDOCUMENTED
38615 */
38616class VLightObjectAnimationTrack : public VSceneObjectTrack {
38617public:
38618
38619/*! @name Callbacks
38620@{ */
38621/// @}
38622
38623};
38624
38625/*! UNDOCUMENTED!
38626@ingroup UNDOCUMENTED
38627 */
38628class VLightObjectGroup : public VSceneObjectGroup {
38629public:
38630
38631/*! @name Callbacks
38632@{ */
38633/// @}
38634
38635};
38636
38637/*! UNDOCUMENTED!
38638@ingroup UNDOCUMENTED
38639 */
38640class VLightObjectToggleEvent : public VEvent {
38641public:
38642
38643/*! @name Callbacks
38644@{ */
38645/// @}
38646
38647/*!
38648*/
38649VActionToggle Action;
38650};
38651
38652/*! UNDOCUMENTED!
38653@ingroup UNDOCUMENTED
38654 */
38655class VLightObjectToggleTrack : public VSceneObjectTrack {
38656public:
38657
38658/*! @name Callbacks
38659@{ */
38660/// @}
38661
38662};
38663
38664/*! UNDOCUMENTED!
38665@ingroup UNDOCUMENTED
38666 */
38667class VMotionEvent : public VSceneObjectEvent {
38668public:
38669
38670/*! @name Callbacks
38671@{ */
38672/// @}
38673
38674};
38675
38676/*! UNDOCUMENTED!
38677@ingroup UNDOCUMENTED
38678 */
38679class VParticleEffectGroup : public VSceneObjectGroup {
38680public:
38681
38682/*! @name Callbacks
38683@{ */
38684/// @}
38685
38686};
38687
38688/*! UNDOCUMENTED!
38689@ingroup UNDOCUMENTED
38690 */
38691class VParticleEffectToggleEvent : public VEvent {
38692public:
38693
38694/*! @name Callbacks
38695@{ */
38696/// @}
38697
38698/*!
38699*/
38700VActionToggle Action;
38701};
38702
38703/*! UNDOCUMENTED!
38704@ingroup UNDOCUMENTED
38705 */
38706class VParticleEffectToggleTrack : public VSceneObjectTrack {
38707public:
38708
38709/*! @name Callbacks
38710@{ */
38711/// @}
38712
38713};
38714
38715/*! UNDOCUMENTED!
38716@ingroup UNDOCUMENTED
38717 */
38718class VPostEffectToggleEvent : public VEvent {
38719public:
38720
38721/*! @name Callbacks
38722@{ */
38723/// @}
38724
38725/*!
38726*/
38727VActionToggle Action;
38728};
38729
38730/*! UNDOCUMENTED!
38731@ingroup UNDOCUMENTED
38732 */
38733class VPostEffectToggleTrack : public VCameraTrack {
38734public:
38735
38736/*! @name Callbacks
38737@{ */
38738/// @}
38739
38740/*!
38741@brief The name of the PostEffect object to be triggered.
38742*/
38743PostEffect PostEffect;
38744};
38745
38746/*! UNDOCUMENTED!
38747@ingroup UNDOCUMENTED
38748 */
38749class VScriptEvent : public VSceneObjectEvent {
38750public:
38751
38752/*! @name Callbacks
38753@{ */
38754/// @}
38755
38756/*!
38757@brief The type of command to be evaluated.
38758*/
38759VScriptEventCommandType CommandType;
38760/*!
38761@brief The command to be evaluated.
38762*/
38763string command;
38764};
38765
38766/*! UNDOCUMENTED!
38767@ingroup UNDOCUMENTED
38768 */
38769class VScriptEventTrack : public VTrack {
38770public:
38771
38772/*! @name Callbacks
38773@{ */
38774/// @}
38775
38776};
38777
38778/*! UNDOCUMENTED!
38779@ingroup UNDOCUMENTED
38780 */
38781class VSoundEffectEvent : public VSceneObjectEvent {
38782public:
38783
38784/*! @name Callbacks
38785@{ */
38786/// @}
38787
38788/*!
38789*/
38790SFXProfile SoundEffect;
38791};
38792
38793/*! UNDOCUMENTED!
38794@ingroup UNDOCUMENTED
38795 */
38796class VSoundEffectTrack : public VTrack {
38797public:
38798
38799/*! @name Callbacks
38800@{ */
38801/// @}
38802
38803};
38804
38805/*!
38806@brief A container that allows to view one or more possibly larger controls inside its area by providing horizontal and/or vertical scroll bars.
38807
38808@ingroup GuiContainers
38809*/
38810class GuiScrollCtrl : public GuiContainer {
38811public:
38812/*!
38813@brief Scroll all the way to the top of the vertical and left of the horizontal scrollbar.
38814
38815*/
38816void scrollToTop();
38817/*!
38818@brief Scroll all the way to the bottom of the vertical scrollbar and the left of the horizontal bar.
38819
38820*/
38821void scrollToBottom();
38822/*!
38823@brief Set the position of the scrolled content.
38824
38825
38826@param x Position on X axis.
38827@param y Position on y axis.
38828*/
38829void setScrollPosition( int x, int y );
38830/*!
38831@brief Scroll the control so that the given child @a control is visible.
38832
38833
38834@param control A child control.*/
38835void scrollToObject( GuiControl control );
38836/*!
38837@brief Get the current coordinates of the scrolled content.
38838
38839
38840@return The current position of the scrolled content.*/
38841Point2I getScrollPosition();
38842/*!
38843@brief Get the current X coordinate of the scrolled content.
38844
38845
38846@return The current X coordinate of the scrolled content.*/
38847int getScrollPositionX();
38848/*!
38849@brief Get the current Y coordinate of the scrolled content.@return The current Y coordinate of the scrolled content.
38850
38851*/
38852int getScrollPositionY();
38853/*!
38854@brief Refresh sizing and positioning of child controls.
38855
38856*/
38857void computeSizes();
38858
38859/*! @name Callbacks
38860@{ */
38861/*!
38862@brief Called each time the child controls are scrolled by some amount.
38863
38864*/
38865void onScroll();
38866/// @}
38867
38868
38869/*! @name Scolling
38870@{ */
38871/*!
38872*/
38873bool willFirstRespond;
38874/*!
38875@brief When to display the horizontal scrollbar.
38876*/
38877GuiScrollBarBehavior hScrollBar;
38878/*!
38879@brief When to display the vertical scrollbar.
38880*/
38881GuiScrollBarBehavior vScrollBar;
38882/*!
38883@brief Horizontal scrolling not allowed if set.
38884*/
38885bool lockHorizScroll;
38886/*!
38887@brief Vertical scrolling not allowed if set.
38888*/
38889bool lockVertScroll;
38890/*!
38891*/
38892bool constantThumbHeight;
38893/*!
38894@brief Padding region to put around child contents.
38895*/
38896Point2I childMargin;
38897/*!
38898@brief Pixels/Tick - if not positive then mousewheel scrolling occurs instantly (like other scrolling).
38899*/
38900int mouseWheelScrollSpeed;
38901/// @}
38902
38903
38904/*! @name Layout
38905@{ */
38906/// @}
38907
38908
38909/*! @name Layout
38910@{ */
38911/// @}
38912
38913
38914/*! @name Control
38915@{ */
38916/// @}
38917
38918
38919/*! @name ToolTip
38920@{ */
38921/// @}
38922
38923
38924/*! @name Editing
38925@{ */
38926/// @}
38927
38928
38929/*! @name Localization
38930@{ */
38931/// @}
38932
38933
38934/*! @name Ungrouped
38935@{ */
38936/// @}
38937
38938
38939/*! @name Object
38940@{ */
38941/// @}
38942
38943
38944/*! @name Editing
38945@{ */
38946/// @}
38947
38948
38949/*! @name Persistence
38950@{ */
38951/// @}
38952
38953};
38954
38955/*! UNDOCUMENTED!
38956@ingroup UNDOCUMENTED
38957 */
38958class VEditorScrollControl : public GuiScrollCtrl {
38959public:
38960
38961/*! @name Callbacks
38962@{ */
38963/// @}
38964
38965
38966/*! @name Scolling
38967@{ */
38968/// @}
38969
38970
38971/*! @name Layout
38972@{ */
38973/// @}
38974
38975
38976/*! @name Layout
38977@{ */
38978/// @}
38979
38980
38981/*! @name Control
38982@{ */
38983/// @}
38984
38985
38986/*! @name ToolTip
38987@{ */
38988/// @}
38989
38990
38991/*! @name Editing
38992@{ */
38993/// @}
38994
38995
38996/*! @name Localization
38997@{ */
38998/// @}
38999
39000
39001/*! @name Ungrouped
39002@{ */
39003/// @}
39004
39005
39006/*! @name Object
39007@{ */
39008/// @}
39009
39010
39011/*! @name Editing
39012@{ */
39013/// @}
39014
39015
39016/*! @name Persistence
39017@{ */
39018/// @}
39019
39020};
39021
39022/*! UNDOCUMENTED!
39023@ingroup UNDOCUMENTED
39024 */
39025class VFadeControl : public GuiControl {
39026public:
39027
39028/*! @name Callbacks
39029@{ */
39030/// @}
39031
39032
39033/*! @name Layout
39034@{ */
39035/// @}
39036
39037
39038/*! @name Control
39039@{ */
39040/// @}
39041
39042
39043/*! @name ToolTip
39044@{ */
39045/// @}
39046
39047
39048/*! @name Editing
39049@{ */
39050/// @}
39051
39052
39053/*! @name Localization
39054@{ */
39055/// @}
39056
39057
39058/*! @name Ungrouped
39059@{ */
39060/// @}
39061
39062
39063/*! @name Object
39064@{ */
39065/// @}
39066
39067
39068/*! @name Editing
39069@{ */
39070/// @}
39071
39072
39073/*! @name Persistence
39074@{ */
39075/// @}
39076
39077};
39078
39079/*! UNDOCUMENTED!
39080@ingroup UNDOCUMENTED
39081 */
39082class VCameraShakeNetEvent {
39083public:
39084
39085/*! @name Callbacks
39086@{ */
39087/// @}
39088
39089};
39090
39091/*! UNDOCUMENTED!
39092@ingroup UNDOCUMENTED
39093 */
39094class VPostEffectNetEvent {
39095public:
39096
39097/*! @name Callbacks
39098@{ */
39099/// @}
39100
39101};
39102
39103/*! UNDOCUMENTED!
39104@ingroup UNDOCUMENTED
39105 */
39106class VSoundEffectNetEvent {
39107public:
39108
39109/*! @name Callbacks
39110@{ */
39111/// @}
39112
39113};
39114
39115/*! UNDOCUMENTED!
39116@ingroup UNDOCUMENTED
39117 */
39118class VActor : public ShapeBase {
39119public:
39120
39121/*! @name Callbacks
39122@{ */
39123/// @}
39124
39125/*!
39126@brief Disables rendering of all instances of this type.
39127
39128
39129@ingroup UNDOCUMENTED
39130*/
39131static bool isRenderable;
39132/*!
39133@brief Disables selection of all instances of this type.
39134
39135
39136@ingroup UNDOCUMENTED
39137*/
39138static bool isSelectable;
39139
39140/*! @name Game
39141@{ */
39142/// @}
39143
39144
39145/*! @name GameObject
39146@{ */
39147/// @}
39148
39149
39150/*! @name Transform
39151@{ */
39152/// @}
39153
39154
39155/*! @name Editing
39156@{ */
39157/// @}
39158
39159
39160/*! @name Mounting
39161@{ */
39162/// @}
39163
39164
39165/*! @name Ungrouped
39166@{ */
39167/// @}
39168
39169
39170/*! @name Object
39171@{ */
39172/// @}
39173
39174
39175/*! @name Editing
39176@{ */
39177/// @}
39178
39179
39180/*! @name Persistence
39181@{ */
39182/// @}
39183
39184};
39185
39186/*! UNDOCUMENTED!
39187@ingroup UNDOCUMENTED
39188 */
39189class VHumanoidActor : public VActor {
39190public:
39191
39192/*! @name Callbacks
39193@{ */
39194/// @}
39195
39196/*!
39197@brief Disables rendering of all instances of this type.
39198
39199
39200@ingroup UNDOCUMENTED
39201*/
39202static bool isRenderable;
39203/*!
39204@brief Disables selection of all instances of this type.
39205
39206
39207@ingroup UNDOCUMENTED
39208*/
39209static bool isSelectable;
39210
39211/*! @name Game
39212@{ */
39213/// @}
39214
39215
39216/*! @name GameObject
39217@{ */
39218/// @}
39219
39220
39221/*! @name Transform
39222@{ */
39223/// @}
39224
39225
39226/*! @name Editing
39227@{ */
39228/// @}
39229
39230
39231/*! @name Mounting
39232@{ */
39233/// @}
39234
39235
39236/*! @name Ungrouped
39237@{ */
39238/// @}
39239
39240
39241/*! @name Object
39242@{ */
39243/// @}
39244
39245
39246/*! @name Editing
39247@{ */
39248/// @}
39249
39250
39251/*! @name Persistence
39252@{ */
39253/// @}
39254
39255};
39256
39257/*! UNDOCUMENTED!
39258@ingroup UNDOCUMENTED
39259 */
39260class VActorData : public ShapeBaseData {
39261public:
39262
39263/*! @name Callbacks
39264@{ */
39265/// @}
39266
39267
39268/*! @name Shadows
39269@{ */
39270/// @}
39271
39272
39273/*! @name Render
39274@{ */
39275/// @}
39276
39277
39278/*! @name Destruction
39279Parameters related to the destruction effects of this object.
39280@{ */
39281/// @}
39282
39283
39284/*! @name Physics
39285@{ */
39286/// @}
39287
39288
39289/*! @name Damage/Energy
39290@{ */
39291/// @}
39292
39293
39294/*! @name Camera
39295The settings used by the shape when it is the camera.
39296@{ */
39297/// @}
39298
39299
39300/*! @name Misc
39301@{ */
39302/// @}
39303
39304
39305/*! @name Reflection
39306@{ */
39307/// @}
39308
39309
39310/*! @name Scripting
39311@{ */
39312/// @}
39313
39314
39315/*! @name Ungrouped
39316@{ */
39317/// @}
39318
39319
39320/*! @name Object
39321@{ */
39322/// @}
39323
39324
39325/*! @name Editing
39326@{ */
39327/// @}
39328
39329
39330/*! @name Persistence
39331@{ */
39332/// @}
39333
39334/*!
39335*/
39336float MaxStepHeight;
39337/*!
39338*/
39339float RunSpeed;
39340/*!
39341*/
39342float SubmergeCoverage;
39343};
39344
39345/*! UNDOCUMENTED!
39346@ingroup UNDOCUMENTED
39347 */
39348class VHumanoidActorData : public VActorData {
39349public:
39350
39351/*! @name Callbacks
39352@{ */
39353/// @}
39354
39355
39356/*! @name Shadows
39357@{ */
39358/// @}
39359
39360
39361/*! @name Render
39362@{ */
39363/// @}
39364
39365
39366/*! @name Destruction
39367Parameters related to the destruction effects of this object.
39368@{ */
39369/// @}
39370
39371
39372/*! @name Physics
39373@{ */
39374/// @}
39375
39376
39377/*! @name Damage/Energy
39378@{ */
39379/// @}
39380
39381
39382/*! @name Camera
39383The settings used by the shape when it is the camera.
39384@{ */
39385/// @}
39386
39387
39388/*! @name Misc
39389@{ */
39390/// @}
39391
39392
39393/*! @name Reflection
39394@{ */
39395/// @}
39396
39397
39398/*! @name Scripting
39399@{ */
39400/// @}
39401
39402
39403/*! @name Ungrouped
39404@{ */
39405/// @}
39406
39407
39408/*! @name Object
39409@{ */
39410/// @}
39411
39412
39413/*! @name Editing
39414@{ */
39415/// @}
39416
39417
39418/*! @name Persistence
39419@{ */
39420/// @}
39421
39422};
39423
39424class BanList {
39425public:
39426/*!
39427@brief Ban a user until a given time.
39428
39429
39430@param uniqueId Unique ID of the player.
39431@param transportAddress Address from which the player connected.
39432@param banTime Time at which they will be allowed back in.@tsexample
39433// Kick someone off the server
39434// %client - This is the connection to the person we are kicking
39435function kick(%client)
39436{
39437      // Let the server know what happened
39438      messageAll( 'MsgAdminForce', '\c2The Admin has kicked %1.', %client.playerName);
39439
39440      // If it is not an AI Player, execute the ban.
39441      if (!%client.isAIControlled())
39442         BanList::addAbsolute(%client.guid, %client.getAddress(), $pref::Server::KickBanTime);
39443
39444      // Let the player know they messed up
39445      %client.delete("You have been kicked from this server");
39446}
39447@endtsexample
39448
39449*/
39450static void addAbsolute( int uniqueId, string transportAddress, int banTime );
39451/*!
39452@brief Ban a user for banLength seconds.
39453
39454
39455@param uniqueId Unique ID of the player.
39456@param transportAddress Address from which the player connected.
39457@param banLength Time period over which to ban the player.@tsexample
39458// Kick someone off the server
39459// %client - This is the connection to the person we are kicking
39460function kick(%client)
39461{
39462      // Let the server know what happened
39463      messageAll( 'MsgAdminForce', '\c2The Admin has kicked %1.', %client.playerName);
39464
39465      // If it is not an AI Player, execute the ban.
39466      if (!%client.isAIControlled())
39467         BanList::add(%client.guid, %client.getAddress(), $pref::Server::KickBanTime);
39468
39469      // Let the player know they messed up
39470      %client.delete("You have been kicked from this server");
39471}
39472@endtsexample
39473
39474*/
39475static void add( int uniqueId, string transportAddress, int banLength );
39476/*!
39477@brief Unban someone.
39478
39479
39480@param uniqueId Unique ID of the player.
39481@param transportAddress Address from which the player connected.
39482@tsexample
39483BanList::removeBan(%userID, %ipAddress);
39484@endtsexample
39485
39486*/
39487static void removeBan( int uniqueId, string transportAddress );
39488/*!
39489@brief Is someone banned?
39490
39491
39492@param uniqueId Unique ID of the player.
39493@param transportAddress Address from which the player connected.
39494
39495@tsexample
39496//-----------------------------------------------------------------------------
39497// This script function is called before a client connection
39498// is accepted.  Returning  will accept the connection,
39499// anything else will be sent back as an error to the client.
39500// All the connect args are passed also to onConnectRequest
39501function GameConnection::onConnectRequest( %client, %netAddress, %name )
39502{
39503     // Find out who is trying to connect
39504     echo("Connect request from: " @ %netAddress);
39505
39506     // Are they allowed in?
39507     if(BanList::isBanned(%client.guid, %netAddress))
39508        return "CR_YOUAREBANNED";
39509
39510     // Is there room for an unbanned player?
39511     if($Server::PlayerCount >= $pref::Server::MaxPlayers)
39512        return "CR_SERVERFULL";
39513     return ;
39514}
39515@endtsexample
39516
39517*/
39518static bool isBanned( int uniqueId, string transportAddress );
39519/*!
39520@brief Dump the banlist to a file.
39521
39522
39523@param filename Path of the file to write the list to.
39524
39525@tsexample
39526BanList::Export("./server/banlist.cs");
39527@endtsexample
39528
39529*/
39530static void export( string filename );
39531
39532/*! @name Callbacks
39533@{ */
39534/// @}
39535
39536};
39537
39538/*!
39539@brief Allows communications between the game and a server using TCP/IP protocols.
39540
39541To use TCPObject you set up a connection to a server, send data to the server, and handle each line of the server's response using a callback.  Once you are done communicating with the server, you disconnect.
39542
39543TCPObject is intended to be used with text based protocols which means you'll need to delineate the server's response with an end-of-line character. i.e. the newline character @\n.  You may optionally include the carriage return character @\r prior to the newline and TCPObject will strip it out before sending the line to the callback.  If a newline character is not included in the server's output, the received data will not be processed until you disconnect from the server (which flushes the internal buffer).
39544
39545TCPObject may also be set up to listen to a specific port, making Torque into a TCP server.  When used in this manner, a callback is received when a client connection is made.  Following the outside connection, text may be sent and lines are processed in the usual manner.
39546
39547If you want to work with HTTP you may wish to use HTTPObject instead as it handles all of the HTTP header setup and parsing.
39548
39549@tsexample
39550// In this example we'll retrieve the new forum threads RSS
39551// feed from garagegames.com.  As we're using TCPObject, the
39552// raw text response will be received from the server, including
39553// the HTTP header.
39554
39555// Define callbacks for our specific TCPObject using our instance's
39556// name (RSSFeed) as the namespace.
39557
39558// Handle an issue with resolving the server's name
39559function RSSFeed::onDNSFailed(%this)
39560{
39561   // Store this state
39562   %this.lastState = "DNSFailed";
39563
39564   // Handle DNS failure
39565}
39566
39567function RSSFeed::onConnectFailed(%this)
39568{
39569   // Store this state
39570   %this.lastState = "ConnectFailed";
39571
39572   // Handle connection failure
39573}
39574
39575function RSSFeed::onDNSResolved(%this)
39576{
39577   // Store this state
39578   %this.lastState = "DNSResolved";
39579
39580}
39581
39582function RSSFeed::onConnected(%this)
39583{
39584   // Store this state
39585   %this.lastState = "Connected";
39586
39587}
39588
39589function RSSFeed::onDisconnect(%this)
39590{
39591   // Store this state
39592   %this.lastState = "Disconnected";
39593
39594}
39595
39596// Handle a line from the server
39597function RSSFeed::onLine(%this, %line)
39598{
39599   // Print the line to the console
39600   echo( %line );
39601}
39602
39603// Create the TCPObject
39604%rss = new TCPObject(RSSFeed);
39605
39606// Define a dynamic field to store the last connection state
39607%rss.lastState = "None";
39608
39609// Connect to the server
39610%rss.connect("www.garagegames.com:80");
39611
39612// Send the RSS feed request to the server.  Response will be
39613// handled in onLine() callback above
39614%rss.send("GET /feeds/rss/threads HTTP/1.1\r\nHost: www.garagegames.com\r\n\r\n");
39615@endtsexample
39616
39617@see HTTPObject
39618@ingroup Networking
39619
39620*/
39621class TCPObject : public SimObject {
39622public:
39623/*!
39624@brief Transmits the data string to the connected computer.
39625
39626This method is used to send text data to the connected computer regardless if we initiated the connection using connect(), or listening to a port using listen().
39627@param data The data string to send.
39628@tsexample
39629// Set the command data
39630%data = "GET " @ $RSSFeed::serverURL @ " HTTP/1.0\r\n";
39631%data = %data @ "Host: " @ $RSSFeed::serverName @ "\r\n";
39632%data = %data @ "User-Agent: " @ $RSSFeed::userAgent @ "\r\n\r\n"
39633
39634// Send the command to the connected server.
39635%thisTCPObj.send(%data);
39636@endtsexample*/
39637void send( string data );
39638/*!
39639@brief Transmits the file in binary to the connected computer.
39640
39641@param fileName The filename of the file to transfer.*/
39642bool sendFile( string fileName );
39643/*!
39644@brief Eat the rest of the lines.*/
39645void finishLastLine();
39646/*!
39647@brief Start listening on the specified port for connections.
39648
39649This method starts a listener which looks for incoming TCP connections to a port.  You must overload the onConnectionRequest callback to create a new TCPObject to read, write, or reject the new connection.
39650
39651@param port Port for this TCPObject to start listening for connections on.
39652@tsexample
39653// Create a listener on port 8080.
39654new TCPObject( TCPListener );
39655TCPListener.listen( 8080 );
39656
39657function TCPListener::onConnectionRequest( %this, %address, %id )
39658{
39659   // Create a new object to manage the connection.
39660   new TCPObject( TCPClient, %id );
39661}
39662
39663function TCPClient::onLine( %this, %line )
39664{
39665   // Print the line of text from client.
39666   echo( %line );
39667}
39668@endtsexample*/
39669void listen( uint port );
39670/*!
39671@brief Connect to the given address.
39672
39673@param address Server address (including port) to connect to.
39674@tsexample
39675// Set the address.
39676%address = "www.garagegames.com:80";
39677
39678// Inform this TCPObject to connect to the specified address.
39679%thisTCPObj.connect(%address);
39680@endtsexample*/
39681void connect( string address );
39682/*!
39683@brief Disconnect from whatever this TCPObject is currently connected to, if anything.
39684
39685@tsexample
39686// Inform this TCPObject to disconnect from anything it is currently connected to.
39687%thisTCPObj.disconnect();
39688@endtsexample*/
39689void disconnect();
39690
39691/*! @name Callbacks
39692@{ */
39693/*!
39694@brief Called whenever a connection request is made.
39695
39696This callback is used when the TCPObject is listening to a port and a client is attempting to connect.
39697@param address Server address connecting from.
39698@param ID Connection ID
39699@see listen()*/
39700void onConnectionRequest( string address, string ID );
39701/*!
39702@brief Called whenever a line of data is sent to this TCPObject.
39703
39704This callback is called when the received data contains a newline @\n character, or the connection has been disconnected and the TCPObject's buffer is flushed.
39705@param line Data sent from the server.*/
39706void onLine( string line );
39707/*!
39708@brief Called when we get a packet with no newlines or nulls (probably websocket).
39709
39710@param data Data sent from the server.
39711@return true if script handled the packet.*/
39712bool onPacket( string data );
39713/*!
39714@brief Called when we are done reading all lines.*/
39715void onEndReceive();
39716/*!
39717@brief Called whenever the DNS has been resolved.
39718
39719*/
39720void onDNSResolved();
39721/*!
39722@brief Called whenever the DNS has failed to resolve.
39723
39724*/
39725void onDNSFailed();
39726/*!
39727@brief Called whenever a connection is established with a server.
39728
39729*/
39730void onConnected();
39731/*!
39732@brief Called whenever a connection has failed to be established with a server.
39733
39734*/
39735void onConnectFailed();
39736/*!
39737@brief Called whenever the TCPObject disconnects from whatever it is currently connected to.
39738
39739*/
39740void onDisconnect();
39741/// @}
39742
39743
39744/*! @name Ungrouped
39745@{ */
39746/// @}
39747
39748
39749/*! @name Object
39750@{ */
39751/// @}
39752
39753
39754/*! @name Editing
39755@{ */
39756/// @}
39757
39758
39759/*! @name Persistence
39760@{ */
39761/// @}
39762
39763};
39764
39765/*!
39766@brief Allows communications between the game and a server using HTTP.
39767
39768HTTPObject is derrived from TCPObject and makes use of the same callbacks for dealing with connections and received data.  However, the way in which you use HTTPObject to connect with a server is different than TCPObject.  Rather than opening a connection, sending data, waiting to receive data, and then closing the connection, you issue a get() or post() and handle the response.  The connection is automatically created and destroyed for you.
39769
39770@tsexample
39771// In this example we'll retrieve the weather in Las Vegas using
39772// Google's API.  The response is in XML which could be processed
39773// and used by the game using SimXMLDocument, but we'll just output
39774// the results to the console in this example.
39775
39776// Define callbacks for our specific HTTPObject using our instance's
39777// name (WeatherFeed) as the namespace.
39778
39779// Handle an issue with resolving the server's name
39780function WeatherFeed::onDNSFailed(%this)
39781{
39782   // Store this state
39783   %this.lastState = "DNSFailed";
39784
39785   // Handle DNS failure
39786}
39787
39788function WeatherFeed::onConnectFailed(%this)
39789{
39790   // Store this state
39791   %this.lastState = "ConnectFailed";
39792
39793   // Handle connection failure
39794}
39795
39796function WeatherFeed::onDNSResolved(%this)
39797{
39798   // Store this state
39799   %this.lastState = "DNSResolved";
39800
39801}
39802
39803function WeatherFeed::onConnected(%this)
39804{
39805   // Store this state
39806   %this.lastState = "Connected";
39807
39808   // Clear our buffer
39809   %this.buffer = "";
39810}
39811
39812function WeatherFeed::onDisconnect(%this)
39813{
39814   // Store this state
39815   %this.lastState = "Disconnected";
39816
39817   // Output the buffer to the console
39818   echo("Google Weather Results:");
39819   echo(%this.buffer);
39820}
39821
39822// Handle a line from the server
39823function WeatherFeed::onLine(%this, %line)
39824{
39825   // Store this line in out buffer
39826   %this.buffer = %this.buffer @ %line;
39827}
39828
39829// Create the HTTPObject
39830%feed = new HTTPObject(WeatherFeed);
39831
39832// Define a dynamic field to store the last connection state
39833%feed.lastState = "None";
39834
39835// Send the GET command
39836%feed.get("www.google.com:80", "/ig/api", "weather=Las-Vegas,US");
39837@endtsexample
39838
39839@see TCPObject
39840@ingroup Networking
39841
39842*/
39843class HTTPObject : public TCPObject {
39844public:
39845/*!
39846@brief Send a GET command to a server to send or retrieve data.
39847
39848@param Address HTTP web address to send this get call to. Be sure to include the port at the end (IE: "www.garagegames.com:80").
39849@param requirstURI Specific location on the server to access (IE: "index.php".)
39850@param query Optional. Actual data to transmit to the server. Can be anything required providing it sticks with limitations of the HTTP protocol. If you were building the URL manually, this is the text that follows the question mark.  For example: http://www.google.com/ig/api?<b>weather=Las-Vegas,US</b>
39851@tsexample
39852// Create an HTTP object for communications
39853%httpObj = new HTTPObject();
39854
39855// Specify a URL to transmit to
39856%url = "www.garagegames.com:80";
39857
39858// Specify a URI to communicate with
39859%URI = "/index.php";
39860
39861// Specify a query to send.
39862%query = "";
39863
39864// Send the GET command to the server
39865%httpObj.get(%url,%URI,%query);
39866@endtsexample*/
39867void get( string Address, string requirstURI, string query="" );
39868/*!
39869@brief Send POST command to a server to send or retrieve data.
39870
39871@param Address HTTP web address to send this get call to. Be sure to include the port at the end (IE: "www.garagegames.com:80").
39872@param requirstURI Specific location on the server to access (IE: "index.php".)
39873@param query Actual data to transmit to the server. Can be anything required providing it sticks with limitations of the HTTP protocol. 
39874@param post Submission data to be processed.
39875@tsexample
39876// Create an HTTP object for communications
39877%httpObj = new HTTPObject();
39878
39879// Specify a URL to transmit to
39880%url = "www.garagegames.com:80";
39881
39882// Specify a URI to communicate with
39883%URI = "/index.php";
39884
39885// Specify a query to send.
39886%query = "";
39887
39888// Specify the submission data.
39889%post = "";
39890
39891// Send the POST command to the server
39892%httpObj.POST(%url,%URI,%query,%post);
39893@endtsexample*/
39894void post( string Address, string requirstURI, string query, string post );
39895
39896/*! @name Callbacks
39897@{ */
39898/// @}
39899
39900
39901/*! @name Ungrouped
39902@{ */
39903/// @}
39904
39905
39906/*! @name Object
39907@{ */
39908/// @}
39909
39910
39911/*! @name Editing
39912@{ */
39913/// @}
39914
39915
39916/*! @name Persistence
39917@{ */
39918/// @}
39919
39920};
39921
39922/*!
39923@brief A very simple example of a network event.
39924
39925This object exists purely for instructional purposes. It is primarily geared toward developers that wish to understand the inner-working of Torque 3D's networking system. This is not intended for actual game development.
39926
39927 @see NetEvent for the inner workings of network events
39928
39929@ingroup Networking
39930
39931*/
39932class SimpleMessageEvent {
39933public:
39934/*!
39935@brief Send a SimpleMessageEvent message to the specified connection.
39936
39937The far end that receives the message will print the message out to the console.
39938@param con The unique ID of the connection to transmit to
39939@param message The string containing the message to transmit
39940
39941@tsexample
39942// Send a message to the other end of the given NetConnection
39943SimpleMessageEvent::msg( %conn, "A message from me!");
39944
39945// The far end will see the following in the console
39946// (Note: The number may be something other than 1796 as it is the SimObjectID
39947// of the received event)
39948// 
39949// RMSG 1796  A message from me!
39950@endtsexample*/
39951static void msg( NetConnection con, string message );
39952
39953/*! @name Callbacks
39954@{ */
39955/// @}
39956
39957};
39958
39959/*!
39960@brief A very simple example of a class derived from NetObject.
39961
39962This object exists purely for instructional purposes. It is primarily geared toward developers that wish to understand the inner-working of Torque 3D's networking system. This is not intended for actual game development.
39963
39964 @tsexample
39965// On the server, create a new SimpleNetObject.  This is a ghost always
39966// object so it will be immediately ghosted to all connected clients.
39967$s = new SimpleNetObject();
39968
39969// All connected clients will see the following in their console:
39970// 
39971// Got message: Hello World!
39972@endtsexample
39973
39974@see NetObject for a full breakdown of this example object
39975@ingroup Networking
39976
39977*/
39978class SimpleNetObject : public NetObject {
39979public:
39980/*!
39981@brief Sets the internal message variable.
39982
39983SimpleNetObject is set up to automatically transmit this new message to all connected clients.  It will appear in the clients' console.
39984@param msg The new message to send
39985
39986@tsexample
39987// On the server, create a new SimpleNetObject.  This is a ghost always
39988// object so it will be immediately ghosted to all connected clients.
39989$s = new SimpleNetObject();
39990
39991// All connected clients will see the following in their console:
39992// 
39993// Got message: Hello World!
39994
39995// Now again on the server, change the message.  This will cause it to
39996// be sent to all connected clients.
39997$s.setMessage("A new message from me!");
39998
39999// All connected clients will now see in their console:
40000// 
40001// Go message: A new message from me!
40002@endtsexample*/
40003void setMessage( string msg );
40004
40005/*! @name Callbacks
40006@{ */
40007/// @}
40008
40009
40010/*! @name Ungrouped
40011@{ */
40012/// @}
40013
40014
40015/*! @name Object
40016@{ */
40017/// @}
40018
40019
40020/*! @name Editing
40021@{ */
40022/// @}
40023
40024
40025/*! @name Persistence
40026@{ */
40027/// @}
40028
40029};
40030
40031/*!
40032@brief Playback controller for a sound source.
40033
40034All sound playback is driven by SFXSources.  Each such source represents an independent playback controller that directly or indirectly affects sound output.
40035
40036While this class itself is instantiable, such an instance will not by itself emit any sound.  This is the responsibility of its subclasses.  Note, however, that none of these subclasses must be instantiated directly but must instead be instantiated indirectly through the SFX interface.
40037
40038@section SFXSource_playonce Play-Once Sources
40039
40040Often, a sound source need only exist for the duration of the sound it is playing.  In this case so-called "play-once" sources simplify the bookkeeping involved by leaving the deletion of sources that have expired their playtime to the sound system.
40041
40042Play-once sources can be created in either of two ways:
40043- sfxPlayOnce(): Directly create a play-once source from a SFXTrack or file.
40044- sfxDeleteWhenStopped(): Retroactively turn any source into a play-once source that will automatically be deleted when moving into stopped state.
40045
40046@see sfxPlayOnce
40047@see sfxDeleteWhenStopped
40048
40049@section SFXSource_hierarchies Source Hierarchies
40050
40051Source are arranged into playback hierarchies where a parent source will scale some of the properties of its children and also hand on any play(), pause(), and stop() commands to them.  This allows to easily group sounds into logical units that can then be operated on as a whole.
40052
40053An example of this is the segregation of sounds according to their use in the game.  Volume levels of background music, in-game sound effects, and character voices will usually be controlled independently and putting their sounds into different hierarchies allows to achieve that easily.
40054
40055The source properties that are scaled by parent values are:
40056- volume,
40057- pitch, and
40058- priority
40059
40060This means that if a parent has a volume of 0.5, the child will play at half the effective volume it would otherwise have.
40061
40062Additionally, parents affect the playback state of their children:
40063
40064- A parent that is in stopped state will force all its direct and indirect children into stopped state.
40065- A parent that is in paused state will force all its direct and indirect children that are playing into paused state.  However, children that are in stopped state will not be affected.
40066- A parent that is in playing state will not affect the playback state of its children.
40067
40068Each source maintains a state that is wants to be in which may differ from the state that is enforced on it by its parent.  If a parent changes its states in a way that allows a child to move into its desired state, the child will do so.
40069
40070For logically grouping sources, instantiate the SFXSource class directly and make other sources children to it.  A source thus instantiated will not effect any real sound output on its own but will influence the sound output of its direct and indirect children.
40071
40072@note Be aware that the property values used to scale child property values are the @b effective values.  For example, the value used to scale the volume of a child is the @b effective volume of the parent, i.e. the volume after fades, distance attenuation, etc. has been applied.
40073
40074@see SFXDescription::sourceGroup
40075@section SFXSource_volume Volume Attenuation
40076
40077During its lifetime, the volume of a source will be continually updated.  This update process always progresses in a fixed set of steps to compute the final effective volume of the source based on the base volume level that was either assigned from the SFXDescription associated with the source (SFXDescription::volume) or manually set by the user.  The process of finding a source's final effective volume is called "volume attenuation".  The steps involved in attenuating a source's volume are (in order):
40078<dl>
40079<dt>Fading</dt>
40080<dd>If the source currently has a fade-effect applied, the volume is interpolated along the currently active fade curve.</dd>
40081<dt>Modulation</dt>
40082<dd>If the source is part of a hierarchy, it's volume is scaled according to the effective volume of its parent.</dd>
40083<dt>Distance Attenuation</dt>
40084<dd>If the source is a 3D sound source, then the volume is interpolated according to the distance model in effect and current listener position and orientation (see @ref SFX_3d).</dd>
40085</dl>
40086
40087@see SFXDescription::volume
40088@see SFXDescription::is3d
40089@section SFXSource_fades Volume Fades
40090
40091To ease-in and ease-out playback of a sound, fade effects may be applied to sources.  A fade will either go from zero volume to full effective volume (fade-in) or from full effective volume to zero volume (fade-out).
40092
40093Fading is coupled to the play(), pause(), and stop() methods as well as to loop iterations when SFXDescription::fadeLoops is true for the source.  play() and the start of a loop iteration will trigger a fade-in whereas pause(), stop() and the end of loop iterations will trigger fade-outs.
40094
40095For looping sources, if SFXDescription::fadeLoops is false, only the initial play() will trigger a fade-in and no further fading will be applied to loop iterations.
40096
40097By default, the fade durations will be governed by the SFXDescription::fadeInTime and SFXDescription::fadeOutTime properties of the SFXDescription attached to the source.  However, these may be overridden on a per-source basis by setting fade times explicitly with setFadeTimes().  Additionally, the set values may be overridden for individual play(), pause(), and stop() calls by supplying appropriate fadeInTime/fadeOutTime parameters.
40098
40099By default, volume will interpolate linearly during fades.  However, custom interpolation curves can be assigned through the SFXDescription::fadeInEase and SFXDescription::fadeOutTime properties.
40100
40101@see SFXDescription::fadeInTime
40102@see SFXDescription::fadeOutTime
40103@see SFXDescription::fadeInEase
40104@see SFXDescription::fadeOutEase
40105@see SFXDescription::fadeLoops
40106@section SFXSource_cones Sound Cones
40107
40108@see SFXDescription::coneInsideAngle
40109@see SFXDescription::coneOutsideAngle
40110@see SFXDescription::coneOutsideVolume
40111@section SFXSource_doppler Doppler Effect
40112
40113@see sfxGetDopplerFactor
40114@see sfxSetDopplerFactor
40115@see SFXAmbience::dopplerFactor
40116@section SFXSource_markers Playback Markers
40117
40118Playback markers allow to attach notification triggers to specific playback positions.  Once the play cursor crosses a position for which a marker is defined, the #onMarkerPassed callback will be triggered on the SFXSource thus allowing to couple script logic to .
40119
40120Be aware that the precision with which marker callbacks are triggered are bound by global source update frequency.  Thus there may be a delay between the play cursor actually passing a marker position and the callback being triggered.
40121
40122@ingroup SFX
40123
40124*/
40125class SFXSource : public SimGroup {
40126public:
40127/*!
40128Set the position and orientation of the source's 3D sound.
40129
40130@param position The new position in world space.
40131@param direction The forward vector.*/
40132
40133void setTransform( Point3F position, Point3F direction )
40134/*!
40135Set the position of the source's 3D sound.
40136
40137@param position The new position in world space.
40138@note This method has no effect if the source is not a 3D source.*/
40139
40140void setTransform( Point3F position )
40141/*!
40142@brief Start playback of the source.
40143
40144If the sound data for the source has not yet been fully loaded, there will be a delay after calling play and playback will start after the data has become available.
40145
40146@param fadeInTime Seconds for the sound to reach full volume.  If -1, the SFXDescription::fadeInTime set in the source's associated description is used.  Pass 0 to disable a fade-in effect that may be configured on the description.*/
40147void play( float fadeInTime=-1.0f );
40148/*!
40149@brief Stop playback of the source.
40150
40151@param fadeOutTime Seconds for the sound to fade down to zero volume.  If -1, the SFXDescription::fadeOutTime set in the source's associated description is used.  Pass 0 to disable a fade-out effect that may be configured on the description.
40152Be aware that if a fade-out effect is used, the source will not immediately transtion to stopped state but will rather remain in playing state until the fade-out time has expired.*/
40153void stop( float fadeOutTime=-1.0f );
40154/*!
40155@brief Pause playback of the source.
40156
40157@param fadeOutTime Seconds for the sound to fade down to zero volume.  If -1, the SFXDescription::fadeOutTime set in the source's associated description is used.  Pass 0 to disable a fade-out effect that may be configured on the description.
40158Be aware that if a fade-out effect is used, the source will not immediately to paused state but will rather remain in playing state until the fade-out time has expired..*/
40159void pause( float fadeOutTime=-1.0f );
40160/*!
40161@brief Test whether the source is currently playing.
40162
40163@return True if the source is in playing state, false otherwise.
40164
40165@see play
40166@see getStatus
40167@see SFXStatus*/
40168bool isPlaying();
40169/*!
40170@brief Test whether the source is currently paused.
40171
40172@return True if the source is in paused state, false otherwise.
40173
40174@see pause
40175@see getStatus
40176@see SFXStatus*/
40177bool isPaused();
40178/*!
40179@brief Test whether the source is currently stopped.
40180
40181@return True if the source is in stopped state, false otherwise.
40182
40183@see stop
40184@see getStatus
40185@see SFXStatus*/
40186bool isStopped();
40187/*!
40188@brief Get the current playback status.
40189
40190@return Te current playback status
40191*/
40192SFXStatus getStatus();
40193/*!
40194@brief Get the current base volume level of the source.
40195
40196This is not the final effective volume that the source is playing at but rather the starting volume level before source group modulation, fades, or distance-based volume attenuation are applied.
40197
40198@return The current base volume level.
40199
40200@see setVolume
40201@see SFXDescription::volume
40202
40203@ref SFXSource_volume*/
40204float getVolume();
40205/*!
40206@brief Set the base volume level for the source.
40207
40208This volume will be the starting point for source group volume modulation, fades, and distance-based volume attenuation.
40209
40210@param volume The new base volume level for the source.  Must be 0>=volume<=1.
40211
40212@see getVolume
40213
40214@ref SFXSource_volume*/
40215void setVolume( float volume );
40216/*!
40217@brief Get the final effective volume level of the source.
40218
40219
40220This method returns the volume level as it is after source group volume modulation, fades, and distance-based volume attenuation have been applied to the base volume level.
40221
40222@return The effective volume of the source.
40223
40224@ref SFXSource_volume*/
40225float getAttenuatedVolume();
40226/*!
40227@brief Get the fade-in time set on the source.
40228
40229This will initially be SFXDescription::fadeInTime.
40230
40231@return The fade-in time set on the source in seconds.
40232
40233@see SFXDescription::fadeInTime
40234
40235@ref SFXSource_fades*/
40236float getFadeInTime();
40237/*!
40238@brief Get the fade-out time set on the source.
40239
40240This will initially be SFXDescription::fadeOutTime.
40241
40242@return The fade-out time set on the source in seconds.
40243
40244@see SFXDescription::fadeOutTime
40245
40246@ref SFXSource_fades*/
40247float getFadeOutTime();
40248/*!
40249@brief Set the fade time parameters of the source.
40250
40251@param fadeInTime The new fade-in time in seconds.
40252@param fadeOutTime The new fade-out time in seconds.
40253
40254@see SFXDescription::fadeInTime
40255@see SFXDescription::fadeOutTime
40256
40257@ref SFXSource_fades*/
40258void setFadeTimes( float fadeInTime, float fadeOutTime );
40259/*!
40260@brief Get the pitch scale of the source.
40261
40262Pitch determines the playback speed of the source (default: 1).
40263
40264@return The current pitch scale factor of the source.
40265
40266@see setPitch
40267@see SFXDescription::pitch*/
40268float getPitch();
40269/*!
40270@brief Set the pitch scale of the source.
40271
40272Pitch determines the playback speed of the source (default: 1).
40273
40274@param pitch The new pitch scale factor.
40275
40276@see getPitch
40277@see SFXDescription::pitch*/
40278void setPitch( float pitch );
40279/*!
40280@brief Set up the 3D volume cone for the source.
40281
40282
40283@param innerAngle Angle of the inner sound cone in degrees (@ref SFXDescription::coneInsideAngle).  Must be 0<=innerAngle<=360.
40284@param outerAngle Angle of the outer sound cone in degrees (@ref SFXDescription::coneOutsideAngle).  Must be 0<=outerAngle<=360.
40285@param outsideVolume Volume scale factor outside of outer cone (@ref SFXDescription::coneOutsideVolume).  Must be 0<=outsideVolume<=1.
40286@note This method has no effect on the source if the source is not 3D.
40287
40288*/
40289void setCone( float innerAngle, float outerAngle, float outsideVolume );
40290/*!
40291@brief Get the number of SFXParameters that are attached to the source.
40292
40293@return The number of parameters attached to the source.
40294
40295@tsexample
40296// Print the name ofo each parameter attached to %source.
40297%numParams = %source.getParameterCount();
40298for( %i = 0; %i < %numParams; %i ++ )
40299   echo( %source.getParameter( %i ).getParameterName() );
40300@endtsexample
40301
40302@see getParameter
40303@see addParameter
40304*/
40305int getParameterCount();
40306/*!
40307@brief Attach @a parameter to the source,
40308
40309
40310Once attached, the source will react to value changes of the given @a parameter.  Attaching a parameter will also trigger an initial read-out of the parameter's current value.
40311
40312@param parameter The parameter to attach to the source.*/
40313void addParameter( SFXParameter parameter );
40314/*!
40315@brief Detach @a parameter from the source.
40316
40317
40318Once detached, the source will no longer react to value changes of the given @a parameter.
40319
40320If the parameter is not attached to the source, the method will do nothing.
40321
40322@param parameter The parameter to detach from the source.
40323*/
40324void removeParameter( SFXParameter parameter );
40325/*!
40326@brief Get the parameter at the given index.
40327
40328@param index Index of the parameter to fetch.  Must be 0<=index<=getParameterCount().
40329@return The parameter at the given @a index or null if @a index is out of range.
40330
40331@tsexample
40332// Print the name ofo each parameter attached to %source.
40333%numParams = %source.getParameterCount();
40334for( %i = 0; %i < %numParams; %i ++ )
40335   echo( %source.getParameter( %i ).getParameterName() );
40336@endtsexample
40337
40338@see getParameterCount*/
40339SFXParameter getParameter( int index );
40340/*!
40341@brief Add a notification marker called @a name at @a pos seconds of playback.
40342
40343
40344@param name Symbolic name for the marker that will be passed to the onMarkerPassed() callback.
40345@param pos Playback position in seconds when the notification should trigger.  Note that this is a soft limit and there may be a delay between the play cursor actually passing the position and the callback being triggered.
40346
40347@note For looped sounds, the marker will trigger on each iteration.
40348
40349@tsexample
40350// Create a new source.
40351$source = sfxCreateSource( AudioMusicLoop2D, "art/sound/backgroundMusic" );
40352
40353// Assign a class to the source.
40354$source.class = "BackgroundMusic";
40355
40356// Add a playback marker at one minute into playback.
40357$source.addMarker( "first", 60 );
40358
40359// Define the callback function.  This function will be called when the playback position passes the one minute mark.
40360function BackgroundMusic::onMarkerPassed( %this, %markerName )
40361{
40362   if( %markerName $= "first" )
40363      echo( "Playback has passed the 60 seconds mark." );
40364}
40365
40366// Play the sound.
40367$source.play();
40368@endtsexample*/
40369void addMarker( String name, float pos );
40370
40371/*! @name Callbacks
40372@{ */
40373/*!
40374@brief Called when the playback status of the source changes.
40375
40376@param newStatus The new playback status.*/
40377void onStatusChange( SFXStatus newStatus );
40378/*!
40379@brief Called when a parameter attached to the source changes value.
40380
40381This callback will be triggered before the value change has actually been applied to the source.
40382@param parameter The parameter that has changed value.
40383@note This is also triggered when the parameter is first attached to the source.*/
40384void onParameterValueChange( SFXParameter parameter );
40385/// @}
40386
40387
40388/*! @name Sound
40389@{ */
40390/*!
40391@brief The playback configuration that determines the initial sound properties and setup.
40392
40393Any SFXSource must have an associated SFXDescription.
40394*/
40395SFXDescription description;
40396/*!
40397@brief Name of function to call when the status of the source changes.
40398
40399
40400The source that had its status changed is passed as the first argument to the function and the new status of the source is passed as the second argument.
40401*/
40402string statusCallback;
40403/// @}
40404
40405
40406/*! @name Ungrouped
40407@{ */
40408/// @}
40409
40410
40411/*! @name Object
40412@{ */
40413/// @}
40414
40415
40416/*! @name Editing
40417@{ */
40418/// @}
40419
40420
40421/*! @name Persistence
40422@{ */
40423/// @}
40424
40425};
40426
40427/*!
40428@brief A sound source that drives multi-source playback.
40429
40430This class acts as an interpreter for SFXPlayLists.  It goes through the slots of the playlist it is attached to and performs the actions described by each of the slots in turn.
40431As SFXControllers are created implicitly by the SFX system when instantiating a source for a play list it is in most cases not necessary to directly deal with the class.
40432The following example demonstrates how a controller would commonly be created.
40433@tsexample
40434// Create a play list from two SFXProfiles.
40435%playList = new SFXPlayList()
40436{
40437   // Use a looped description so the list playback will loop.
40438   description = AudioMusicLoop2D;
40439
40440   track[ 0 ] = Profile1;
40441   track[ 1 ] = Profile2;
40442};
40443
40444// Play the list.  This will implicitly create a controller.
40445sfxPlayOnce( %playList );
40446@endtsexample
40447
40448@note Play lists are updated at regular intervals by the sound system.  This processing determines the granularity at which playlist action timing takes place.
40449@note This class cannot be instantiated directly.  Use sfxPlayOnce() or sfxCreateSource() with the playlist you want to play to create an instance of this class.
40450@see SFXPlayList
40451@ingroup SFX
40452
40453*/
40454class SFXController : public SFXSource {
40455public:
40456/*!
40457@brief Get the index of the playlist slot currently processed by the controller.
40458
40459@return The slot index currently being played.
40460@see SFXPlayList*/
40461int getCurrentSlot();
40462/*!
40463@brief Set the index of the playlist slot to play by the controller.  This can be used to seek in the playlist.
40464
40465@param index Index of the playlist slot.*/
40466void setCurrentSlot( int index );
40467
40468/*! @name Callbacks
40469@{ */
40470/// @}
40471
40472
40473/*! @name Debug
40474@{ */
40475/*!
40476@brief If true, the controller logs its operation to the console.
40477
40478This is a non-networked field that will work locally only.
40479*/
40480bool trace;
40481/// @}
40482
40483
40484/*! @name Sound
40485@{ */
40486/// @}
40487
40488
40489/*! @name Ungrouped
40490@{ */
40491/// @}
40492
40493
40494/*! @name Object
40495@{ */
40496/// @}
40497
40498
40499/*! @name Editing
40500@{ */
40501/// @}
40502
40503
40504/*! @name Persistence
40505@{ */
40506/// @}
40507
40508};
40509
40510/*!
40511@brief A sound channel value that can be bound to multiple sound sources.
40512
40513Parameters are special objects that isolate a specific property that sound sources can have and allows to bind this isolated instance to multiple sound sources such that when the value of the parameter changes, all sources bound to the parameter will have their respective property changed.
40514
40515Parameters are identified and referenced by their #internalName.  This means that the SFXDescription::parameters and SFXTrack::parameters fields should contain the #internalNames of the SFXParameter objects which should be attached to the SFXSources when they are created.  No two SFXParameters should have the same #internalName.
40516
40517All SFXParameter instances are automatically made children of the SFXParameterGroup.
40518
40519@note To simply control the volume and/or pitch levels of a group of sounds, it is easier and more efficient to use a sound source group rather than SFXParameters (see @ref SFXSource_hierarchies).  Simply create a SFXSource object representing the group, assign SFXDescription::sourceGroup of the sounds appropriately, and then set the volume and/or pitch level of the group to modulate the respective properties of all children.
40520
40521@section SFXParameter_updates Parameter Updates
40522Parameters are periodically allowed to update their own values.  This makes it possible to attach custom logic to a parameter and have individual parameters synchronize their values autonomously.  Use the onUpdate() callback to attach script code to a parameter update.
40523
40524@tsexample
40525new SFXParameter( EngineRPMLevel )
40526{
40527   // Set the name by which this parameter is identified.
40528   internalName = "EngineRPMLevel";
40529
40530   // Let this parameter control the pitch of attached sources to simulate engine RPM ramping up and down.
40531   channel = "Pitch";
40532
40533   // Start out with unmodified pitch.
40534   defaultValue = 1;
40535
40536   // Add a texture description of what this parameter does.
40537   description = "Engine RPM Level";
40538};
40539
40540// Create a description that automatically attaches the engine RPM parameter.
40541singleton SFXDescription( EngineRPMSound : AudioLoop2D )
40542{
40543   parameters[ 0 ] = "EngineRPMLevel";
40544};
40545
40546// Create sound sources for the engine.
40547sfxCreateSource( EngineRPMSound, "art/sound/engine/enginePrimary" );
40548sfxCreateSource( EngineRPMSound, "art/sound/engine/engineSecondary" );
40549
40550// Setting the parameter value will now affect the pitch level of both sound sources.
40551EngineRPMLevel.value = 0.5;
40552EngineRPMLevel.value = 1.5;
40553@endtsexample
40554
40555@ref SFX_interactive
40556
40557@ingroup SFX
40558*/
40559class SFXParameter : public SimObject {
40560public:
40561/*!
40562@brief Get the name of the parameter.
40563
40564@return The paramete name.*/
40565String getParameterName();
40566/*!
40567@brief Reset the parameter's value to its default.
40568
40569@see SFXParameter::defaultValue
40570*/
40571void reset();
40572
40573/*! @name Callbacks
40574@{ */
40575/*!
40576@brief Called when the sound system triggers an update on the parameter.
40577
40578This occurs periodically during system operation.*/
40579void onUpdate();
40580/// @}
40581
40582
40583/*! @name Sound
40584@{ */
40585/*!
40586@brief Current value of the audio parameter.
40587
40588All attached sources are notified when this value changes.
40589*/
40590float value;
40591/*!
40592@brief Permitted range for #value.
40593
40594Minimum and maximum allowed value for the parameter.  Both inclusive.
40595
40596For all but the User0-3 channels, this property is automatically set up by SFXParameter.
40597*/
40598Point2F range;
40599/*!
40600@brief Channel that the parameter controls.
40601
40602This controls which property of the sources it is attached to the parameter controls.
40603*/
40604SFXChannel channel;
40605/*!
40606@brief Value to which the parameter is initially set.
40607
40608When the parameter is first added to the system, #value will be set to #defaultValue.
40609*/
40610float defaultValue;
40611/*!
40612@brief Textual description of the parameter.
40613
40614Primarily for use in the Audio Parameters dialog of the editor to allow for easier identification of parameters.
40615*/
40616string description;
40617/// @}
40618
40619
40620/*! @name Ungrouped
40621@{ */
40622/// @}
40623
40624
40625/*! @name Object
40626@{ */
40627/// @}
40628
40629
40630/*! @name Editing
40631@{ */
40632/// @}
40633
40634
40635/*! @name Persistence
40636@{ */
40637/// @}
40638
40639};
40640
40641/*!
40642@brief A sound controller that directly plays a single sound file.
40643
40644When playing individual audio files, SFXSounds are implicitly created by the sound system.
40645
40646Each sound source has an associated play cursor that can be queried and explicitly positioned by the user.  The cursor is a floating-point value measured in seconds.
40647
40648For streamed sources, playback may not be continuous in case the streaming queue is interrupted.
40649
40650@note This class cannot be instantiated directly by the user but rather is implicitly created by the sound system when sfxCreateSource() or sfxPlayOnce() is called on a SFXProfile instance.
40651
40652@section SFXSound_virtualization Sounds and Voices
40653
40654To actually emit an audible signal, a sound must allocate a resource on the sound device through which the sound data is being played back.  This resource is called 'voice'.
40655
40656As with other types of resources, the availability of these resources may be restricted, i.e. a given sound device will usually only support a fixed number of voices that are playing at the same time.  Since, however, there may be arbitrary many SFXSounds instantiated and playing at the same time, this needs to be solved.  
40657
40658@see SFXDescription::priority
40659@ingroup SFX
40660*/
40661class SFXSound : public SFXSource {
40662public:
40663/*!
40664@brief Test whether the sound data associated with the sound has been fully loaded and is ready for playback.
40665
40666For streamed sounds, this will be false during playback when the stream queue for the sound is starved and waiting for data.  For buffered sounds, only an initial loading phase will potentially cause isReady to return false.
40667
40668@return True if the sound is ready for playback.*/
40669bool isReady();
40670/*!
40671@brief Get the current playback position in seconds.
40672
40673@return The current play cursor offset.*/
40674float getPosition();
40675/*!
40676@brief Set the current playback position in seconds.
40677
40678If the source is currently playing, playback will jump to the new position.  If playback is stopped or paused, playback will resume at the given position when play() is called.
40679
40680@param position The new position of the play cursor (in seconds).
40681*/
40682void setPosition( float position );
40683/*!
40684@brief Get the total play time (in seconds) of the sound data attached to the sound.
40685
40686@return 
40687
40688@note Be aware that for looped sounds, this will not return the total playback time of the sound.
40689*/
40690float getDuration();
40691
40692/*! @name Callbacks
40693@{ */
40694/// @}
40695
40696
40697/*! @name Sound
40698@{ */
40699/// @}
40700
40701
40702/*! @name Ungrouped
40703@{ */
40704/// @}
40705
40706
40707/*! @name Object
40708@{ */
40709/// @}
40710
40711
40712/*! @name Editing
40713@{ */
40714/// @}
40715
40716
40717/*! @name Persistence
40718@{ */
40719/// @}
40720
40721};
40722
40723/*!
40724@brief A boolean switch used to modify playlist behavior.
40725
40726Sound system states are used to allow playlist controllers to make decisions based on global state.  This is useful, for example, to couple audio playback to gameplay state.  Certain states may, for example, represent different locations that the listener can be in, like underwater, in open space, or indoors.  Other states could represent moods of the current gameplay situation, like, for example, an aggressive mood during combat.
40727
40728By activating and deactivating sound states according to gameplay state, a set of concurrently running playlists may react and adapt to changes in the game.
40729
40730@section SFXState_activation Activation and Deactivation
40731At any time, a given state can be either active or inactive.  Calling activate() on a state increases an internal counter and calling deactivate() decreases the counter.  Only when the count reaches zero will the state be deactivated.
40732
40733In addition to the activation count, states also maintain a disabling count.  Calling disable() increases this count and calling enable() decreases it.  As long as this count is greater than zero, a given state will not be activated even if its activation count is non-zero.  Calling disable() on an active state will not only increase the disabling count but also deactivate the state.  Calling enable() on a state with a positive activation count will re-activate the state when the disabling count reaches zero.
40734
40735@section SFXState_dependencies State Dependencies
40736By listing other states in in its #includedStates and #excludedStates fields, a state may automatically trigger the activation or disabling of other states in the sytem when it is activated.  This allows to form dependency chains between individual states.
40737
40738@tsexample
40739// State indicating that the listener is submerged.
40740singleton SFXState( AudioLocationUnderwater )
40741{
40742   parentGroup = AudioLocation;
40743   // AudioStateExclusive is a class defined in the core scripts that will automatically
40744   // ensure for a state to deactivate all the sibling SFXStates in its parentGroup when it
40745   // is activated.
40746   className = "AudioStateExclusive";
40747};
40748
40749// State suitable e.g. for combat.
40750singleton SFXState( AudioMoodAggressive )
40751{
40752   parentGroup = AudioMood;
40753   className = "AudioStateExclusive";
40754};
40755@endtsexample
40756
40757@see SFXPlayList
40758@see SFXController
40759@see SFXPlayList::state
40760@see SFXPlayList::stateMode
40761
40762@ref SFX_interactive
40763
40764@ingroup SFX
40765@ingroup Datablocks
40766*/
40767class SFXState : public SimDataBlock {
40768public:
40769/*!
40770@brief Test whether the state is currently active.
40771
40772This is true when the activation count is >0 and the disabling count is =0.
40773@return True if the state is currently active.
40774@see activate*/
40775bool isActive();
40776/*!
40777@brief Increase the activation count on the state.
40778
40779If the state isn't already active and it is not disabled, the state will be activated.
40780@see isActive
40781@see deactivate
40782*/
40783void activate();
40784/*!
40785@brief Decrease the activation count on the state.
40786
40787If the count reaches zero and the state was not disabled, the state will be deactivated.
40788@see isActive
40789@see activate
40790*/
40791void deactivate();
40792/*!
40793@brief Test whether the state is currently disabled.
40794
40795This is true when the disabling count of the state is non-zero.
40796@return True if the state is disabled.
40797
40798@see disable
40799*/
40800bool isDisabled();
40801/*!
40802@brief Increase the disabling count of the state.
40803
40804If the state is currently active, it will be deactivated.
40805@see isDisabled
40806*/
40807void disable();
40808/*!
40809@brief Decrease the disabling count of the state.
40810
40811If the disabling count reaches zero while the activation count is still non-zero, the state will be reactivated again.
40812@see isDisabled
40813*/
40814void enable();
40815
40816/*! @name Callbacks
40817@{ */
40818/*!
40819@brief Called when the state goes from inactive to active.
40820
40821*/
40822void onActivate();
40823/*!
40824@brief called when the state goes from active to deactive.
40825
40826*/
40827void onDeactivate();
40828/// @}
40829
40830
40831/*! @name State
40832@{ */
40833/*!
40834@brief States that will automatically be activated when this state is activated.
40835
40836
40837@ref SFXState_activation
40838*/
40839SFXState includedStates[ 4 ];
40840/*!
40841@brief States that will automatically be disabled when this state is activated.
40842
40843
40844@ref SFXState_activation
40845*/
40846SFXState excludedStates[ 4 ];
40847/// @}
40848
40849
40850/*! @name Ungrouped
40851@{ */
40852/// @}
40853
40854
40855/*! @name Object
40856@{ */
40857/// @}
40858
40859
40860/*! @name Editing
40861@{ */
40862/// @}
40863
40864
40865/*! @name Persistence
40866@{ */
40867/// @}
40868
40869};
40870
40871/*!
40872@brief File I/O object used for creating, reading, and writing XML documents.
40873
40874A SimXMLDocument is a container of various XML nodes.  The Document level may contain a header (sometimes called a declaration), comments and child Elements.  Elements may contain attributes, data (or text) and child Elements.
40875
40876You build new Elements using addNewElement().  This makes the new Element the current one you're working with.  You then use setAttribute() to add attributes to the Element.  You use addData() or addText() to write to the text area of an Element.@tsexample
40877// Thanks to Rex Hiebert for this example
40878// Given the following XML
40879<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
40880<DataTables>
40881  <table tableName="2DShapes">
40882     <rec id="1">Triangle</rec>
40883     <rec id="2">Square</rec>
40884     <rec id="3">Circle</rec>
40885  </table>
40886  <table tableName="3DShapes">
40887     <rec id="1">Pyramid</rec>
40888     <rec id="2">Cube</rec>
40889     <rec id="3">Sphere</rec>
40890  </table>
40891</DataTables>
40892
40893// Using SimXMLDocument by itself
40894function readXmlExample(%filename)
40895{
40896   %xml = new SimXMLDocument() {};
40897   %xml.loadFile(%filename);
40898
40899   %xml.pushChildElement("DataTables");
40900   %xml.pushFirstChildElement("table");
40901   while(true)
40902   {
40903    echo("TABLE:" SPC %xml.attribute("tableName"));
40904    %xml.pushFirstChildElement("rec");
40905    while (true)
40906    {
40907      %id = %xml.attribute("id");
40908      %desc = %xml.getData();
40909      echo("  Shape" SPC %id SPC %desc);
40910      if (!%xml.nextSiblingElement("rec")) break;
40911    }
40912    %xml.popElement();
40913    if (!%xml.nextSiblingElement("table")) break;
40914   }
40915}
40916
40917// Thanks to Scott Peal for this example
40918// Using FileObject in conjunction with SimXMLDocument
40919// This example uses an XML file with a format of:
40920// <Models>
40921//    <Model category="" name="" path="" />
40922// </Models>
40923function getModelsInCatagory()
40924{
40925   %file = "./Catalog.xml";
40926   %fo = new FileObject();
40927   %text = "";
40928
40929   if(%fo.openForRead(%file))
40930   {
40931    while(!%fo.isEOF())
40932    {
40933      %text = %text @ %fo.readLine();
40934      if (!%fo.isEOF()) %text = %text @ "\n";
40935    }
40936   }
40937   else
40938   {
40939    echo("Unable to locate the file: " @ %file);
40940   }
40941
40942   %fo.delete();
40943
40944   %xml = new SimXMLDocument() {};
40945   %xml.parse(%text);
40946   // "Get" inside of the root element, "Models".
40947   %xml.pushChildElement(0);
40948
40949   // "Get" into the first child element
40950   if (%xml.pushFirstChildElement("Model"))
40951   {
40952    while (true)
40953    {
40954      // 
40955      //  Here, i read the element's attributes.
40956      //  You might want to save these values in an array or call the %xml.getElementValue()
40957      //  if you have a different XML structure.
40958
40959      %catagory = %xml.attribute("catagory");
40960      %name = %xml.attribute("name");
40961      %path = %xml.attribute("path");
40962
40963      // now, read the next "Model"
40964      if (!%xml.nextSiblingElement("Model")) break;
40965    }
40966   }
40967}
40968@endtsexample
40969
40970@note SimXMLDocument is a wrapper around TinyXml, a standard XML library.  If you're familiar with its concepts, you'll find they also apply here.
40971
40972@see FileObject
40973
40974@ingroup FileSystem
40975
40976*/
40977class SimXMLDocument : public SimObject {
40978public:
40979/*!
40980@brief Set this document to its default state.
40981
40982Clears all Elements from the documents.  Equivalent to using clear()
40983
40984@see clear()*/
40985void reset();
40986/*!
40987@brief Load in given filename and prepare it for use.
40988
40989@note Clears the current document's contents.
40990
40991@param fileName Name and path of XML document
40992@return True if the file was loaded successfully.*/
40993bool loadFile( string fileName );
40994/*!
40995@brief Save document to the given file name.
40996
40997@param fileName Path and name of XML file to save to.
40998@return True if the file was successfully saved.*/
40999bool saveFile( string fileName );
41000/*!
41001@brief Create a document from a XML string.
41002
41003@note Clears the current document's contents.
41004
41005@param xmlString Valid XML to parse and store as a document.*/
41006void parse( string xmlString );
41007/*!
41008@brief Set this document to its default state.
41009
41010Clears all Elements from the documents.  Equivalent to using reset()
41011
41012@see reset()*/
41013void clear();
41014/*!
41015@brief Get last error description.
41016
41017@return A string of the last error message.*/
41018string getErrorDesc();
41019/*!
41020@brief Clear the last error description.*/
41021void clearError();
41022/*!
41023@brief Push the first child Element with the given name onto the stack, making it the current Element.
41024
41025@param name String containing name of the child Element.
41026@return True if the Element was found and made the current one.
41027@tsexample
41028// Using the following test.xml file as an example:
41029// <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
41030// <NewElement>Some text</NewElement>
41031
41032// Load in the file
41033%x = new SimXMLDocument();
41034%x.loadFile("test.xml");
41035
41036// Make the first Element the current one
41037%x.pushFirstChildElement("NewElement");
41038
41039// Store the current Element's text ('Some text' in this example)
41040// into 'result'
41041%result = %x.getText();
41042echo( %result );
41043@endtsexample*/
41044bool pushFirstChildElement( string name );
41045/*!
41046@brief Push the child Element at the given index onto the stack, making it the current one.
41047
41048@param index Numerical index of Element being pushed.@return True if the Element was found and made the current one.*/
41049bool pushChildElement( int index );
41050/*!
41051@brief Put the next sibling Element with the given name on the stack, making it the current one.
41052
41053@param name String containing name of the next sibling.@return True if the Element was found and made the current one.*/
41054bool nextSiblingElement( string name );
41055/*!
41056@brief Get the Element's value if it exists.
41057
41058Usually returns the text from the Element.
41059@return The value from the Element, or an empty string if none is found.*/
41060string elementValue();
41061/*!
41062@brief Pop the last Element off the stack.*/
41063void popElement();
41064/*!
41065@brief Get a string attribute from the current Element on the stack.
41066
41067@param attributeName Name of attribute to retrieve.
41068@return The attribute string if found.  Otherwise returns an empty string.*/
41069string attribute( string attributeName );
41070/*!
41071@brief Get float attribute from the current Element on the stack.
41072
41073@param attributeName Name of attribute to retrieve.
41074@return The value of the given attribute in the form of a float.
41075@deprecated Use attribute().*/
41076float attributeF32( string attributeName );
41077/*!
41078@brief Get int attribute from the current Element on the stack.
41079
41080@param attributeName Name of attribute to retrieve.
41081@return The value of the given attribute in the form of an integer.
41082@deprecated Use attribute().*/
41083int attributeS32( string attributeName );
41084/*!
41085@brief Tests if the requested attribute exists.
41086
41087@param attributeName Name of attribute being queried for.
41088
41089@return True if the attribute exists.*/
41090bool attributeExists( string attributeName );
41091/*!
41092@brief Obtain the name of the current Element's first attribute.
41093
41094@return String containing the first attribute's name, or an empty string if none is found.
41095
41096@see nextAttribute()
41097@see lastAttribute()
41098@see prevAttribute()*/
41099string firstAttribute();
41100/*!
41101@brief Obtain the name of the current Element's last attribute.
41102
41103@return String containing the last attribute's name, or an empty string if none is found.
41104
41105@see prevAttribute()
41106@see firstAttribute()
41107@see lastAttribute()*/
41108string lastAttribute();
41109/*!
41110@brief Get the name of the next attribute for the current Element after a call to firstAttribute().
41111
41112@return String containing the next attribute's name, or an empty string if none is found.@see firstAttribute()
41113@see lastAttribute()
41114@see prevAttribute()*/
41115string nextAttribute();
41116/*!
41117@brief Get the name of the previous attribute for the current Element after a call to lastAttribute().
41118
41119@return String containing the previous attribute's name, or an empty string if none is found.@see lastAttribute()
41120@see firstAttribute()
41121@see nextAttribute()*/
41122string prevAttribute();
41123/*!
41124@brief Set the attribute of the current Element on the stack to the given value.
41125
41126@param attributeName Name of attribute being changed
41127@param value New value to assign to the attribute*/
41128void setAttribute( string attributeName, string value );
41129/*!
41130@brief Add the given SimObject's fields as attributes of the current Element on the stack.
41131
41132@param objectID ID of SimObject being copied.*/
41133void setObjectAttributes( string objectID );
41134/*!
41135@brief Create a new element with the given name as child of current Element and push it onto the Element stack making it the current one.
41136
41137@note This differs from addNewElement() in that it adds the new Element as a child of the current Element (or a child of the document if no Element exists).
41138
41139@param name XML tag for the new Element.
41140@see addNewElement()*/
41141void pushNewElement( string name );
41142/*!
41143@brief Create a new element with the given name as child of current Element's parent and push it onto the Element stack making it the current one.
41144
41145@note This differs from pushNewElement() in that it adds the new Element to the current Element's parent (or document if there is no parent Element).  This makes the new Element a sibling of the current one.
41146
41147@param name XML tag for the new Element.
41148@see pushNewElement()*/
41149void addNewElement( string name );
41150/*!
41151@brief Add a XML header to a document.
41152
41153Sometimes called a declaration, you typically add a standard header to the document before adding any elements.  SimXMLDocument always produces the following header:
41154
41155<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
41156
41157@tsexample
41158// Create a new XML document with just a header and single element.
41159%x = new SimXMLDocument();
41160%x.addHeader();
41161%x.addNewElement("NewElement");
41162%x.saveFile("test.xml");
41163
41164// Produces the following file:
41165// <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
41166// <NewElement />
41167@endtsexample*/
41168void addHeader();
41169/*!
41170@brief Add the given comment as a child of the document.
41171
41172@param comment String containing the comment.@tsexample
41173// Create a new XML document with a header, a comment and single element.
41174%x = new SimXMLDocument();
41175%x.addHeader();
41176%x.addComment("This is a test comment");
41177%x.addNewElement("NewElement");
41178%x.saveFile("test.xml");
41179
41180// Produces the following file:
41181// <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
41182// <!--This is a test comment-->
41183// <NewElement />
41184@endtsexample
41185
41186@see readComment()*/
41187void addComment( string comment );
41188/*!
41189@brief Gives the comment at the specified index, if any.
41190
41191
41192Unlike addComment() that only works at the document level, readComment() may read comments from the document or any child Element.  The current Element (or document if no Elements have been pushed to the stack) is the parent for any comments, and the provided index is the number of comments in to read back.@param index Comment index number to query from the current Element stack
41193
41194@return String containing the comment, or an empty string if no comment is found.
41195
41196@see addComment()*/
41197string readComment( int index );
41198/*!
41199@brief Add the given text as a child of current Element.
41200
41201Use getText() to retrieve any text from the current Element and removeText() to clear any text.
41202
41203addText() and addData() may be used interchangeably.@param text String containing the text.
41204
41205@tsexample
41206// Create a new XML document with a header and single element
41207// with some added text.
41208%x = new SimXMLDocument();
41209%x.addHeader();
41210%x.addNewElement("NewElement");
41211%x.addText("Some text");
41212%x.saveFile("test.xml");
41213
41214// Produces the following file:
41215// <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
41216// <NewElement>Some text</NewElement>
41217@endtsexample
41218
41219@see getText()
41220@see removeText()
41221@see addData()
41222@see getData()*/
41223void addText( string text );
41224/*!
41225@brief Gets the text from the current Element.
41226
41227Use addText() to add text to the current Element and removeText() to clear any text.
41228
41229getText() and getData() may be used interchangeably.@return String containing the text in the current Element.@tsexample
41230// Using the following test.xml file as an example:
41231// <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
41232// <NewElement>Some text</NewElement>
41233
41234// Load in the file
41235%x = new SimXMLDocument();
41236%x.loadFile("test.xml");
41237
41238// Make the first Element the current one
41239%x.pushFirstChildElement("NewElement");
41240
41241// Store the current Element's text ('Some text' in this example)
41242// into 'result'
41243%result = %x.getText();
41244echo( %result );
41245@endtsexample
41246
41247@see addText()
41248@see removeText()
41249@see addData()
41250@see getData()*/
41251string getText();
41252/*!
41253@brief Remove any text on the current Element.
41254
41255Use getText() to retrieve any text from the current Element and addText() to add text to the current Element.  As getData() and addData() are equivalent to getText() and addText(), removeText() will also remove any data from the current Element.
41256
41257@see addText()
41258@see getText()
41259@see addData()
41260@see getData()*/
41261void removeText();
41262/*!
41263@brief Add the given text as a child of current Element.
41264
41265Use getData() to retrieve any text from the current Element.
41266
41267addData() and addText() may be used interchangeably.  As there is no difference between data and text, you may also use removeText() to clear any data from the current Element.
41268
41269@param text String containing the text.
41270
41271@tsexample
41272// Create a new XML document with a header and single element
41273// with some added data.
41274%x = new SimXMLDocument();
41275%x.addHeader();
41276%x.addNewElement("NewElement");
41277%x.addData("Some text");
41278%x.saveFile("test.xml");
41279
41280// Produces the following file:
41281// <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
41282// <NewElement>Some text</NewElement>
41283@endtsexample
41284
41285@see getData()@see addText()
41286@see getText()
41287@see removeText()*/
41288void addData( string text );
41289/*!
41290@brief Gets the text from the current Element.
41291
41292Use addData() to add text to the current Element.
41293
41294getData() and getText() may be used interchangeably.  As there is no difference between data and text, you may also use removeText() to clear any data from the current Element.
41295
41296@return String containing the text in the current Element.@tsexample
41297// Using the following test.xml file as an example:
41298// <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
41299// <NewElement>Some data</NewElement>
41300
41301// Load in the file
41302%x = new SimXMLDocument();
41303%x.loadFile("test.xml");
41304
41305// Make the first Element the current one
41306%x.pushFirstChildElement("NewElement");
41307
41308// Store the current Element's data ('Some data' in this example)
41309// into 'result'
41310%result = %x.getData();
41311echo( %result );
41312@endtsexample
41313
41314@see addData()
41315@see addText()
41316@see getText()
41317@see removeText()*/
41318string getData();
41319
41320/*! @name Callbacks
41321@{ */
41322/// @}
41323
41324
41325/*! @name Ungrouped
41326@{ */
41327/// @}
41328
41329
41330/*! @name Object
41331@{ */
41332/// @}
41333
41334
41335/*! @name Editing
41336@{ */
41337/// @}
41338
41339
41340/*! @name Persistence
41341@{ */
41342/// @}
41343
41344};
41345
41346/*!
41347@brief Data structure for storing indexed sequences of key/value pairs.
41348
41349This is a powerful array class providing PHP style arrays in TorqueScript.
41350
41351The following features are supported:<ul>
41352<li>array pointers: this allows you to move forwards or backwards through the array as if it was a list, including jumping to the start or end.</li>
41353<li>sorting: the array can be sorted in either alphabetic or numeric mode, on the key or the value, and in ascending or descending order</li>
41354<li>add/remove elements: elements can be pushed/popped from the start or end of the array, or can be inserted/erased from anywhere in the middle</li>
41355<li>removal of duplicates: remove duplicate keys or duplicate values</li>
41356<li>searching: search the array and return the index of a particular key or value</li>
41357<li>counting: count the number of instaces of a particular value or key in the array, as well as the total number of elements</li>
41358<li>advanced features: array append, array crop and array duplicate</li>
41359</ul>
41360
41361Array element keys and values can be strings or numbers
41362
41363@ingroup Scripting
41364*/
41365class ArrayObject : public SimObject {
41366public:
41367/*!
41368@brief Search the array from the current position for the element @param value Array value to search for
41369
41370@return Index of the first element found, or -1 if none
41371*/
41372int getIndexFromValue( string value );
41373/*!
41374@brief Search the array from the current position for the key @param value Array key to search for
41375
41376@return Index of the first element found, or -1 if none
41377*/
41378int getIndexFromKey( string key );
41379/*!
41380@brief Get the value of the array element at the submitted index.
41381
41382@param index 0-based index of the array element to get
41383@return The value of the array element at the specified index, or "" if the index is out of range
41384*/
41385string getValue( int index );
41386/*!
41387@brief Get the key of the array element at the submitted index.
41388
41389@param index 0-based index of the array element to get
41390@return The key associated with the array element at the specified index, or "" if the index is out of range
41391*/
41392string getKey( int index );
41393/*!
41394@brief Set the key at the given index.
41395
41396@param key New key value
41397@param index 0-based index of the array element to update
41398*/
41399void setKey( string key, int index );
41400/*!
41401@brief Set the value at the given index.
41402
41403@param value New array element value
41404@param index 0-based index of the array element to update
41405*/
41406void setValue( string value, int index );
41407/*!
41408@brief Get the number of elements in the array.
41409
41410*/
41411int count();
41412/*!
41413@brief Get the number of times a particular value is found in the array.
41414
41415@param value Array element value to count
41416*/
41417int countValue( string value );
41418/*!
41419@brief Get the number of times a particular key is found in the array.
41420
41421@param key Key value to count
41422*/
41423int countKey( string key );
41424/*!
41425@brief Adds a new element to the end of an array (same as push_back()).
41426
41427@param key Key for the new element
41428@param value Value for the new element
41429*/
41430void add( string key, string value="" );
41431/*!
41432@brief Adds a new element to the end of an array.
41433
41434@param key Key for the new element
41435@param value Value for the new element
41436*/
41437void push_back( string key, string value="" );
41438/*!
41439@brief Adds a new element to the front of an array
41440
41441*/
41442void push_front( string key, string value="" );
41443/*!
41444@brief Adds a new element to a specified position in the array.
41445
41446- @a index = 0 will insert an element at the start of the array (same as push_front())
41447- @a index = %array.count() will insert an element at the end of the array (same as push_back())
41448
41449@param key Key for the new element
41450@param value Value for the new element
41451@param index 0-based index at which to insert the new element*/
41452void insert( string key, string value, int index );
41453/*!
41454@brief Removes the last element from the array
41455
41456*/
41457void pop_back();
41458/*!
41459@brief Removes the first element from the array
41460
41461*/
41462void pop_front();
41463/*!
41464@brief Removes an element at a specific position from the array.
41465
41466@param index 0-based index of the element to remove
41467*/
41468void erase( int index );
41469/*!
41470@brief Emptys all elements from an array
41471
41472*/
41473void empty();
41474/*!
41475@brief Removes any elements that have duplicated values (leaving the first instance)
41476
41477*/
41478void uniqueValue();
41479/*!
41480@brief Removes any elements that have duplicated keys (leaving the first instance)
41481
41482*/
41483void uniqueKey();
41484/*!
41485@brief Alters array into an exact duplicate of the target array.
41486
41487@param target ArrayObject to duplicate
41488*/
41489bool duplicate( ArrayObject target );
41490/*!
41491@brief Removes elements with matching keys from array.
41492
41493@param target ArrayObject containing keys to remove from this array
41494*/
41495bool crop( ArrayObject target );
41496/*!
41497@brief Appends the target array to the array object.
41498
41499@param target ArrayObject to append to the end of this array
41500*/
41501bool append( ArrayObject target );
41502/*!
41503@brief Alpha sorts the array by value
41504
41505
41506@param ascending [optional] True for ascending sort, false for descending sort
41507*/
41508void sort( bool ascending=false );
41509/*!
41510@brief Alpha sorts the array by value in ascending order
41511
41512*/
41513void sorta();
41514/*!
41515@brief Alpha sorts the array by value in descending order
41516
41517*/
41518void sortd();
41519/*!
41520@brief Alpha sorts the array by key
41521
41522
41523@param ascending [optional] True for ascending sort, false for descending sort
41524*/
41525void sortk( bool ascending=false );
41526/*!
41527@brief Alpha sorts the array by key in ascending order
41528
41529*/
41530void sortka();
41531/*!
41532@brief Alpha sorts the array by key in descending order
41533
41534*/
41535void sortkd();
41536/*!
41537@brief Numerically sorts the array by value
41538
41539
41540@param ascending [optional] True for ascending sort, false for descending sort
41541*/
41542void sortn( bool ascending=false );
41543/*!
41544@brief Numerically sorts the array by value in ascending order
41545
41546*/
41547void sortna();
41548/*!
41549@brief Numerically sorts the array by value in descending order
41550
41551*/
41552void sortnd();
41553/*!
41554@brief Numerically sorts the array by key
41555
41556
41557@param ascending [optional] True for ascending sort, false for descending sort
41558*/
41559void sortnk( bool ascending=false );
41560/*!
41561@brief Numerical sorts the array by key in ascending order
41562
41563*/
41564void sortnka();
41565/*!
41566@brief Numerical sorts the array by key in descending order
41567
41568*/
41569void sortnkd();
41570/*!
41571@brief Sorts the array by value in ascending order using the given callback function.
41572
41573@param functionName Name of a function that takes two arguments A and B and returns -1 if A is less, 1 if B is less, and 0 if both are equal.
41574
41575@tsexample
41576function mySortCallback(%a, %b)
41577{
41578   return strcmp( %a.name, %b.name );
41579}
41580
41581%array.sortf( "mySortCallback" );
41582@endtsexample
41583*/
41584void sortf( string functionName );
41585/*!
41586@brief Sorts the array by key in ascending order using the given callback function.
41587
41588@param functionName Name of a function that takes two arguments A and B and returns -1 if A is less, 1 if B is less, and 0 if both are equal.@see sortf
41589*/
41590void sortfk( string functionName );
41591/*!
41592@brief Sorts the array by value in descending order using the given callback function.
41593
41594@param functionName Name of a function that takes two arguments A and B and returns -1 if A is less, 1 if B is less, and 0 if both are equal.@see sortf
41595*/
41596void sortfd( string functionName );
41597/*!
41598@brief Sorts the array by key in descending order using the given callback function.
41599
41600@param functionName Name of a function that takes two arguments A and B and returns -1 if A is less, 1 if B is less, and 0 if both are equal.@see sortf
41601*/
41602void sortfkd( string functionName );
41603/*!
41604@brief Moves array pointer to start of array
41605
41606
41607@return Returns the new array pointer*/
41608int moveFirst();
41609/*!
41610@brief Moves array pointer to end of array
41611
41612
41613@return Returns the new array pointer*/
41614int moveLast();
41615/*!
41616@brief Moves array pointer to next position
41617
41618
41619@return Returns the new array pointer, or -1 if already at the end*/
41620int moveNext();
41621/*!
41622@brief Moves array pointer to prev position
41623
41624
41625@return Returns the new array pointer, or -1 if already at the start*/
41626int movePrev();
41627/*!
41628@brief Gets the current pointer index
41629
41630*/
41631int getCurrent();
41632/*!
41633@brief Sets the current pointer index.
41634
41635@param index New 0-based pointer index
41636*/
41637void setCurrent( int index );
41638/*!
41639@brief Echos the array contents to the console
41640
41641*/
41642void echo();
41643
41644/*! @name Callbacks
41645@{ */
41646/// @}
41647
41648/*!
41649@brief Makes the keys and values case-sensitive.
41650
41651By default, comparison of key and value strings will be case-insensitive.
41652*/
41653bool caseSensitive;
41654/*!
41655@brief Helper field which allows you to add new key['keyname'] = value pairs.
41656*/
41657caseString key;
41658
41659/*! @name Ungrouped
41660@{ */
41661/// @}
41662
41663
41664/*! @name Object
41665@{ */
41666/// @}
41667
41668
41669/*! @name Editing
41670@{ */
41671/// @}
41672
41673
41674/*! @name Persistence
41675@{ */
41676/// @}
41677
41678};
41679
41680/*!
41681A class designed to be used as a console consumer and log the data it receives to a file.
41682
41683@see dumpConsoleFunctions
41684@see dumpConsoleClasses
41685@ingroup Logging
41686
41687*/
41688class ConsoleLogger : public SimObject {
41689public:
41690/*!
41691@brief Attaches the logger to the console and begins writing to file@tsexample
41692
41693// Create the logger
41694// Will automatically start writing to testLogging.txt with normal priority
41695new ConsoleLogger(logger, "testLogging.txt", false);
41696
41697// Send something to the console, with the logger consumes and writes to file
41698echo("This is logged to the file");
41699
41700// Stop logging, but do not delete the logger
41701logger.detach();
41702
41703echo("This is not logged to the file");
41704
41705// Attach the logger to the console again
41706logger.attach();
41707
41708// Logging has resumed
41709echo("Logging has resumed");@endtsexample
41710
41711*/
41712bool attach();
41713/*!
41714@brief Detaches the logger from the console and stops writing to file@tsexample
41715
41716// Create the logger
41717// Will automatically start writing to testLogging.txt with normal priority
41718new ConsoleLogger(logger, "testLogging.txt", false);
41719
41720// Send something to the console, with the logger consumes and writes to file
41721echo("This is logged to the file");
41722
41723// Stop logging, but do not delete the logger
41724logger.detach();
41725
41726echo("This is not logged to the file");
41727
41728// Attach the logger to the console again
41729logger.attach();
41730
41731// Logging has resumed
41732echo("Logging has resumed");@endtsexample
41733
41734*/
41735bool detach();
41736
41737/*! @name Callbacks
41738@{ */
41739/// @}
41740
41741
41742/*! @name Logging
41743@{ */
41744/*!
41745@brief Determines the priority level and attention the logged entry gets when recorded
41746
41747
41748
41749*/
41750LogLevel level;
41751/// @}
41752
41753
41754/*! @name Ungrouped
41755@{ */
41756/// @}
41757
41758
41759/*! @name Object
41760@{ */
41761/// @}
41762
41763
41764/*! @name Editing
41765@{ */
41766/// @}
41767
41768
41769/*! @name Persistence
41770@{ */
41771/// @}
41772
41773};
41774
41775/*!
41776@brief A script-level OOP object which allows binding of a class, superClass and arguments along with declaration of methods.
41777
41778ScriptObjects are extrodinarily powerful objects that allow defining of any type of data required. They can optionally have
41779a class and a superclass defined for added control of multiple ScriptObjects through a simple class definition.
41780
41781@tsexample
41782new ScriptObject(Game)
41783{
41784   class = "DeathMatchGame";
41785   superClass = GameCore;
41786   genre = "Action FPS"; // Note the new, non-Torque variable
41787};
41788@endtsexample
41789@see SimObject
41790@ingroup Console
41791@ingroup Scripting
41792*/
41793class ScriptObject : public SimObject {
41794public:
41795
41796/*! @name Callbacks
41797@{ */
41798/*!
41799@brief Called when this ScriptObject is added to the system.
41800
41801@param ID Unique object ID assigned when created (%this in script).
41802*/
41803void onAdd( SimObjectId ID );
41804/*!
41805@brief Called when this ScriptObject is removed from the system.
41806
41807@param ID Unique object ID assigned when created (%this in script).
41808*/
41809void onRemove( SimObjectId ID );
41810/// @}
41811
41812
41813/*! @name Ungrouped
41814@{ */
41815/// @}
41816
41817
41818/*! @name Object
41819@{ */
41820/// @}
41821
41822
41823/*! @name Editing
41824@{ */
41825/// @}
41826
41827
41828/*! @name Persistence
41829@{ */
41830/// @}
41831
41832};
41833
41834/*!
41835@brief A ScriptObject that responds to tick and frame events.
41836
41837ScriptTickObject is a ScriptObject that adds callbacks for tick and frame events.  Use setProcessTicks() to enable or disable the onInterpolateTick() and onProcessTick() callbacks.  The callOnAdvanceTime property determines if the onAdvanceTime() callback is called.
41838
41839@see ScriptObject
41840@ingroup Console
41841@ingroup Scripting
41842*/
41843class ScriptTickObject : public ScriptObject {
41844public:
41845/*!
41846@brief Sets this object as either tick processing or not.
41847
41848@param tick This object's onInterpolateTick() and onProcessTick() callbacks are called if set to true.*/
41849void setProcessTicks( bool tick );
41850/*!
41851@brief Is this object wanting to receive tick notifications.
41852
41853If this object is set to receive tick notifications then its onInterpolateTick() and onProcessTick() callbacks are called.
41854@return True if object wants tick notifications*/
41855bool isProcessingTicks();
41856
41857/*! @name Callbacks
41858@{ */
41859/*!
41860@brief This is called every frame, but only if the object is set to process ticks.
41861
41862@param delta The time delta for this frame.
41863*/
41864void onInterpolateTick( float delta );
41865/*!
41866@brief Called once every 32ms if this object is set to process ticks.
41867
41868*/
41869void onProcessTick();
41870/*!
41871@brief This is called every frame regardless if the object is set to process ticks, but only if the callOnAdvanceTime property is set to true.
41872
41873@param timeDelta The time delta for this frame.
41874@see callOnAdvanceTime
41875*/
41876void onAdvanceTime( float timeDelta );
41877/// @}
41878
41879/*!
41880@brief Call the onAdvaceTime() callback.
41881*/
41882bool callOnAdvanceTime;
41883
41884/*! @name Ungrouped
41885@{ */
41886/// @}
41887
41888
41889/*! @name Object
41890@{ */
41891/// @}
41892
41893
41894/*! @name Editing
41895@{ */
41896/// @}
41897
41898
41899/*! @name Persistence
41900@{ */
41901/// @}
41902
41903};
41904
41905/*!
41906@brief Essentially a SimGroup, but with onAdd and onRemove script callbacks.
41907
41908@tsexample
41909// First container, SimGroup containing a ScriptGroup
41910new SimGroup(Scenes)
41911{
41912  // Subcontainer, ScriptGroup containing variables
41913  // related to a cut scene and a starting WayPoint
41914  new ScriptGroup(WelcomeScene)
41915  {
41916     class = "Scene";
41917     pathName = "Pathx";
41918     description = "A small orc village set in the Hardesty mountains. This town and its surroundings will be used to illustrate some the Torque Game Engine's features.";
41919     pathTime = "0";
41920     title = "Welcome to Orc Town";
41921
41922     new WayPoint(start)
41923     {
41924        position = "163.873 -103.82 208.354";
41925        rotation = "0.136165 -0.0544916 0.989186 44.0527";
41926        scale = "1 1 1";
41927        dataBlock = "WayPointMarker";
41928        team = "0";
41929     };
41930  };
41931};
41932@endtsexample
41933
41934@see SimGroup
41935@ingroup Console
41936@ingroup Scripting
41937*/
41938class ScriptGroup : public SimGroup {
41939public:
41940
41941/*! @name Callbacks
41942@{ */
41943/*!
41944@brief Called when this ScriptGroup is added to the system.
41945
41946@param ID Unique object ID assigned when created (%this in script).
41947*/
41948void onAdd( SimObjectId ID );
41949/*!
41950@brief Called when this ScriptObject is removed from the system.
41951
41952@param ID Unique object ID assigned when created (%this in script).
41953*/
41954void onRemove( SimObjectId ID );
41955/// @}
41956
41957
41958/*! @name Ungrouped
41959@{ */
41960/// @}
41961
41962
41963/*! @name Object
41964@{ */
41965/// @}
41966
41967
41968/*! @name Editing
41969@{ */
41970/// @}
41971
41972
41973/*! @name Persistence
41974@{ */
41975/// @}
41976
41977};
41978
41979/*!
41980@brief This class is responsible opening, reading, creating, and saving file contents.
41981
41982FileObject acts as the interface with OS level files.  You create a new FileObject and pass into it a file's path and name.  The FileObject class supports three distinct operations for working with files:
41983
41984<table border='1' cellpadding='1'><tr><th>Operation</th><th>%FileObject Method</th><th>Description</th></tr><tr><td>Read</td><td>openForRead()</td><td>Open the file for reading</td></tr><tr><td>Write</td><td>openForWrite()</td><td>Open the file for writing to and replace its contents (if any)</td></tr><tr><td>Append</td><td>openForAppend()</td><td>Open the file and start writing at its end</td></tr></table>
41985
41986Before you may work with a file you need to use one of the three above methods on the FileObject.
41987
41988@tsexample
41989// Create a file object for writing
41990%fileWrite = new FileObject();
41991
41992// Open a file to write to, if it does not exist it will be created
41993%result = %fileWrite.OpenForWrite("./test.txt");
41994
41995if ( %result )
41996{
41997   // Write a line to the text files
41998   %fileWrite.writeLine("READ. READ CODE. CODE");
41999}
42000
42001// Close the file when finished
42002%fileWrite.close();
42003
42004// Cleanup the file object
42005%fileWrite.delete();
42006
42007
42008// Create a file object for reading
42009%fileRead = new FileObject();
42010
42011// Open a text file, if it exists
42012%result = %fileRead.OpenForRead("./test.txt");
42013
42014if ( %result )
42015{
42016   // Read in the first line
42017   %line = %fileRead.readline();
42018
42019   // Print the line we just read
42020   echo(%line);
42021}
42022
42023// Close the file when finished
42024%fileRead.close();
42025
42026// Cleanup the file object
42027%fileRead.delete();
42028@endtsexample
42029
42030@ingroup FileSystem
42031
42032*/
42033class FileObject : public SimObject {
42034public:
42035/*!
42036@brief Write an object to a text file, with some data added first.
42037
42038Unlike a simple writeLine using specified strings, this function writes an entire object to file, preserving its type, name, and properties. This is similar to the save() functionality of the SimObject class, but with a bit more control.
42039
42040@param object The SimObject being written to file, properties, name, and all.
42041@param prepend Data or text that is written out before the SimObject.
42042
42043@tsexample
42044// Let's assume this SpawnSphere was created and currently
42045// exists in the running level
42046new SpawnSphere(TestSphere)
42047{
42048   spawnClass = "Player";
42049   spawnDatablock = "DefaultPlayerData";
42050   autoSpawn = "1";
42051   radius = "5";
42052   sphereWeight = "1";
42053   indoorWeight = "1";
42054   outdoorWeight = "1";
42055   dataBlock = "SpawnSphereMarker";
42056   position = "-42.222 1.4845 4.80334";
42057   rotation = "0 0 -1 108";
42058   scale = "1 1 1";
42059   canSaveDynamicFields = "1";
42060};
42061
42062// Create a file object for writing
42063%fileWrite = new FileObject();
42064
42065// Open a file to write to, if it does not exist it will be created
42066%fileWrite.OpenForWrite("./spawnSphers.txt");
42067
42068// Write out the TestSphere, with a prefix
42069%fileWrite.writeObject(TestSphere, "$mySphere = ");
42070
42071// Close the text file
42072%fileWrite.close();
42073
42074// Cleanup
42075%fileWrite.delete();
42076@endtsexample
42077
42078
42079*/
42080
42081void writeObject( SimObject* object, string prepend);
42082/*!
42083@brief Write an object to a text file.
42084
42085Unlike a simple writeLine using specified strings, this function writes an entire object to file, preserving its type, name, and properties. This is similar to the save() functionality of the SimObject class, but with a bit more control.
42086
42087@param object The SimObject being written to file, properties, name, and all.
42088@tsexample
42089// Let's assume this SpawnSphere was created and currently
42090// exists in the running level
42091new SpawnSphere(TestSphere)
42092{
42093   spawnClass = "Player";
42094   spawnDatablock = "DefaultPlayerData";
42095   autoSpawn = "1";
42096   radius = "5";
42097   sphereWeight = "1";
42098   indoorWeight = "1";
42099   outdoorWeight = "1";
42100   dataBlock = "SpawnSphereMarker";
42101   position = "-42.222 1.4845 4.80334";
42102   rotation = "0 0 -1 108";
42103   scale = "1 1 1";
42104   canSaveDynamicFields = "1";
42105};
42106
42107// Create a file object for writing
42108%fileWrite = new FileObject();
42109
42110// Open a file to write to, if it does not exist it will be created
42111%fileWrite.OpenForWrite("./spawnSphers.txt");
42112
42113// Write out the TestSphere
42114%fileWrite.writeObject(TestSphere);
42115
42116// Close the text file
42117%fileWrite.close();
42118
42119// Cleanup
42120%fileWrite.delete();
42121@endtsexample
42122
42123
42124*/
42125
42126void writeObject( SimObject* object);
42127/*!
42128@brief Open a specified file for reading
42129
42130There is no limit as to what kind of file you can read. Any format and data contained within is accessible, not just text
42131
42132@param filename Path, name, and extension of file to be read@tsexample
42133// Create a file object for reading
42134%fileRead = new FileObject();
42135
42136// Open a text file, if it exists
42137%result = %fileRead.OpenForRead("./test.txt");
42138@endtsexample
42139
42140@return True if file was successfully opened, false otherwise*/
42141bool openForRead( string filename );
42142/*!
42143@brief Open a specified file for writing
42144
42145There is no limit as to what kind of file you can write. Any format and data is allowable, not just text
42146
42147@param filename Path, name, and extension of file to write to@tsexample
42148// Create a file object for writing
42149%fileWrite = new FileObject();
42150
42151// Open a file to write to, if it does not exist it will be created
42152%result = %fileWrite.OpenForWrite("./test.txt");
42153@endtsexample
42154
42155@return True if file was successfully opened, false otherwise*/
42156bool openForWrite( string filename );
42157/*!
42158@brief Open a specified file for writing, adding data to the end of the file
42159
42160There is no limit as to what kind of file you can write. Any format and data is allowable, not just text. Unlike openForWrite(), which will erase an existing file if it is opened, openForAppend() preserves data in an existing file and adds to it.
42161
42162@param filename Path, name, and extension of file to append to@tsexample
42163// Create a file object for writing
42164%fileWrite = new FileObject();
42165
42166// Open a file to write to, if it does not exist it will be created
42167// If it does exist, whatever we write will be added to the end
42168%result = %fileWrite.OpenForAppend("./test.txt");
42169@endtsexample
42170
42171@return True if file was successfully opened, false otherwise*/
42172bool openForAppend( string filename );
42173/*!
42174@brief Determines if the parser for this FileObject has reached the end of the file
42175
42176@tsexample
42177// Create a file object for reading
42178%fileRead = new FileObject();
42179
42180// Open a text file, if it exists
42181%fileRead.OpenForRead("./test.txt");
42182
42183// Keep reading until we reach the end of the file
42184while( !%fileRead.isEOF() )
42185{
42186   %line = %fileRead.readline();
42187   echo(%line);
42188}
42189
42190// Made it to the end
42191echo("Finished reading file");
42192@endtsexample
42193
42194@return True if the parser has reached the end of the file, false otherwise*/
42195bool isEOF();
42196/*!
42197@brief Read a line from file.
42198
42199Emphasis on *line*, as in you cannot parse individual characters or chunks of data.  There is no limitation as to what kind of data you can read.
42200
42201@tsexample
42202// Create a file object for reading
42203%fileRead = new FileObject();
42204
42205// Open a text file, if it exists
42206%fileRead.OpenForRead("./test.txt");
42207
42208// Read in the first line
42209%line = %fileRead.readline();
42210
42211// Print the line we just read
42212echo(%line);
42213@endtsexample
42214
42215@return String containing the line of data that was just read*/
42216string readLine();
42217/*!
42218@brief Read a line from the file without moving the stream position.
42219
42220Emphasis on *line*, as in you cannot parse individual characters or chunks of data.  There is no limitation as to what kind of data you can read. Unlike readLine, the parser does not move forward after reading.
42221
42222@param filename Path, name, and extension of file to be read@tsexample
42223// Create a file object for reading
42224%fileRead = new FileObject();
42225
42226// Open a text file, if it exists
42227%fileRead.OpenForRead("./test.txt");
42228
42229// Peek the first line
42230%line = %fileRead.peekLine();
42231
42232// Print the line we just peeked
42233echo(%line);
42234// If we peek again...
42235%line = %fileRead.peekLine();
42236
42237// We will get the same output as the first time
42238// since the stream did not move forward
42239echo(%line);
42240@endtsexample
42241
42242@return String containing the line of data that was just peeked*/
42243string peekLine();
42244/*!
42245@brief Write a line to the file, if it was opened for writing.
42246
42247There is no limit as to what kind of text you can write. Any format and data is allowable, not just text. Be careful of what you write, as whitespace, current values, and literals will be preserved.
42248
42249@param text The data we are writing out to file.@tsexample
42250// Create a file object for writing
42251%fileWrite = new FileObject();
42252
42253// Open a file to write to, if it does not exist it will be created
42254%fileWrite.OpenForWrite("./test.txt");
42255
42256// Write a line to the text files
42257%fileWrite.writeLine("READ. READ CODE. CODE");
42258
42259@endtsexample
42260
42261@return True if file was successfully opened, false otherwise*/
42262void writeLine( string text );
42263/*!
42264@brief Close the file.
42265
42266It is EXTREMELY important that you call this function when you are finished reading or writing to a file. Failing to do so is not only a bad programming practice, but could result in bad data or corrupt files. Remember: Open, Read/Write, Close, Delete...in that order!
42267
42268@tsexample
42269// Create a file object for reading
42270%fileRead = new FileObject();
42271
42272// Open a text file, if it exists
42273%fileRead.OpenForRead("./test.txt");
42274
42275// Peek the first line
42276%line = %fileRead.peekLine();
42277
42278// Print the line we just peeked
42279echo(%line);
42280// If we peek again...
42281%line = %fileRead.peekLine();
42282
42283// We will get the same output as the first time
42284// since the stream did not move forward
42285echo(%line);
42286
42287// Close the file when finished
42288%fileWrite.close();
42289
42290// Cleanup the file object
42291%fileWrite.delete();
42292@endtsexample*/
42293void close();
42294
42295/*! @name Callbacks
42296@{ */
42297/// @}
42298
42299
42300/*! @name Ungrouped
42301@{ */
42302/// @}
42303
42304
42305/*! @name Object
42306@{ */
42307/// @}
42308
42309
42310/*! @name Editing
42311@{ */
42312/// @}
42313
42314
42315/*! @name Persistence
42316@{ */
42317/// @}
42318
42319};
42320
42321/*!
42322@brief Base class for working with streams.
42323
42324You do not instantiate a StreamObject directly.  Instead, it is used as part of a FileStreamObject and ZipObject to support working with uncompressed and compressed files respectively.@tsexample
42325// You cannot actually declare a StreamObject
42326// Instead, use the derived class "FileStreamObject"
42327%fsObject = FileStreamObject();
42328@endtsexample
42329
42330@see FileStreamObject for the derived class usable in script.
42331@see ZipObject where StreamObject is used to read and write to files within a zip archive.
42332@ingroup FileSystem
42333
42334
42335*/
42336class StreamObject : public SimObject {
42337public:
42338/*!
42339@brief Gets a printable string form of the stream's status
42340
42341@tsexample
42342// Create a file stream object for reading
42343%fsObject = new FileStreamObject();
42344
42345// Open a file for reading
42346%fsObject.open("./test.txt", "read");
42347
42348// Get the status and print it
42349%status = %fsObject.getStatus();
42350echo(%status);
42351
42352// Always remember to close a file stream when finished
42353%fsObject.close();
42354@endtsexample
42355
42356@return String containing status constant, one of the following:
42357
42358   OK - Stream is active and no file errors
42359
42360   IOError - Something went wrong during read or writing the stream
42361
42362   EOS - End of Stream reached (mostly for reads)
42363
42364   IllegalCall - An unsupported operation used.  Always w/ accompanied by AssertWarn
42365
42366  Closed - Tried to operate on a closed stream (or detached filter)
42367
42368   UnknownError - Catch all for an error of some kind
42369
42370   Invalid - Entire stream is invalid*/
42371string getStatus();
42372/*!
42373@brief Tests if the stream has reached the end of the file
42374
42375This is an alternative name for isEOF. Both functions are interchangeable. This simply exists for those familiar with some C++ file I/O standards.
42376
42377@tsexample
42378// Create a file stream object for reading
42379%fsObject = new FileStreamObject();
42380
42381// Open a file for reading
42382%fsObject.open("./test.txt", "read");
42383
42384// Keep reading until we reach the end of the file
42385while( !%fsObject.isEOS() )
42386{
42387   %line = %fsObject.readLine();
42388   echo(%line);
42389}
42390// Made it to the end
42391echo("Finished reading file");
42392
42393// Always remember to close a file stream when finished
42394%fsObject.close();
42395@endtsexample
42396
42397@return True if the parser has reached the end of the file, false otherwise
42398@see isEOF()*/
42399bool isEOS();
42400/*!
42401@brief Tests if the stream has reached the end of the file
42402
42403This is an alternative name for isEOS. Both functions are interchangeable. This simply exists for those familiar with some C++ file I/O standards.
42404
42405@tsexample
42406// Create a file stream object for reading
42407%fsObject = new FileStreamObject();
42408
42409// Open a file for reading
42410%fsObject.open("./test.txt", "read");
42411
42412// Keep reading until we reach the end of the file
42413while( !%fsObject.isEOF() )
42414{
42415   %line = %fsObject.readLine();
42416   echo(%line);
42417}
42418// Made it to the end
42419echo("Finished reading file");
42420
42421// Always remember to close a file stream when finished
42422%fsObject.close();
42423@endtsexample
42424
42425@return True if the parser has reached the end of the file, false otherwise
42426@see isEOS()*/
42427bool isEOF();
42428/*!
42429@brief Gets the position in the stream
42430
42431The easiest way to visualize this is to think of a cursor in a text file. If you have moved the cursor by five characters, the current position is 5. If you move ahead 10 more characters, the position is now 15. For StreamObject, when you read in the line the position is increased by the number of characters parsed, the null terminator, and a newline.
42432
42433@tsexample
42434// Create a file stream object for reading
42435%fsObject = new FileStreamObject();
42436
42437// Open a file for reading
42438// This file contains two lines of text repeated:
42439// Hello World
42440// Hello World
42441%fsObject.open("./test.txt", "read");
42442
42443// Read in the first line
42444%line = %fsObject.readLine();
42445
42446// Get the position of the stream
42447%position = %fsObject.getPosition();
42448
42449// Print the current position
42450// Should be 13, 10 for the words, 1 for the space, 1 for the null terminator, and 1 for the newline
42451echo(%position);
42452
42453// Always remember to close a file stream when finished
42454%fsObject.close();
42455@endtsexample
42456
42457@return Number of bytes which stream has parsed so far, null terminators and newlines are included
42458@see setPosition()*/
42459int getPosition();
42460/*!
42461@brief Gets the position in the stream
42462
42463The easiest way to visualize this is to think of a cursor in a text file. If you have moved the cursor by five characters, the current position is 5. If you move ahead 10 more characters, the position is now 15. For StreamObject, when you read in the line the position is increased by the number of characters parsed, the null terminator, and a newline. Using setPosition allows you to skip to specific points of the file.
42464
42465@tsexample
42466// Create a file stream object for reading
42467%fsObject = new FileStreamObject();
42468
42469// Open a file for reading
42470// This file contains the following two lines:
42471// 11111111111
42472// Hello World
42473%fsObject.open("./test.txt", "read");
42474
42475// Skip ahead by 12, which will bypass the first line entirely
42476%fsObject.setPosition(12);
42477
42478// Read in the next line
42479%line = %fsObject.readLine();
42480
42481// Print the line just read in, should be "Hello World"
42482echo(%line);
42483
42484// Always remember to close a file stream when finished
42485%fsObject.close();
42486@endtsexample
42487
42488@return Number of bytes which stream has parsed so far, null terminators and newlines are included
42489@see getPosition()*/
42490bool setPosition( int newPosition );
42491/*!
42492@brief Gets the size of the stream
42493
42494The size is dependent on the type of stream being used. If it is a file stream, returned value will be the size of the file. If it is a memory stream, it will be the size of the allocated buffer.
42495
42496@tsexample
42497// Create a file stream object for reading
42498%fsObject = new FileStreamObject();
42499
42500// Open a file for reading
42501// This file contains the following two lines:
42502// HelloWorld
42503// HelloWorld
42504%fsObject.open("./test.txt", "read");
42505
42506// Found out how large the file stream is
42507// Then print it to the console
42508// Should be 22
42509%streamSize = %fsObject.getStreamSize();
42510echo(%streamSize);
42511
42512// Always remember to close a file stream when finished
42513%fsObject.close();
42514@endtsexample
42515
42516@return Size of stream, in bytes*/
42517int getStreamSize();
42518/*!
42519@brief Read a line from the stream.
42520
42521Emphasis on *line*, as in you cannot parse individual characters or chunks of data. There is no limitation as to what kind of data you can read.
42522
42523@tsexample
42524// Create a file stream object for reading
42525// This file contains the following two lines:
42526// HelloWorld
42527// HelloWorld
42528%fsObject = new FileStreamObject();
42529
42530%fsObject.open("./test.txt", "read");
42531
42532// Read in the first line
42533%line = %fsObject.readLine();
42534
42535// Print the line we just read
42536echo(%line);
42537
42538// Always remember to close a file stream when finished
42539%fsObject.close();
42540@endtsexample
42541
42542@return String containing the line of data that was just read
42543@see writeLine()*/
42544string readLine();
42545/*!
42546@brief Write a line to the stream, if it was opened for writing.
42547
42548There is no limit as to what kind of data you can write. Any format and data is allowable, not just text. Be careful of what you write, as whitespace, current values, and literals will be preserved.
42549
42550@param line The data we are writing out to file.@tsexample
42551// Create a file stream
42552%fsObject = new FileStreamObject();
42553
42554// Open the file for writing
42555// If it does not exist, it is created. If it does exist, the file is cleared
42556%fsObject.open("./test.txt", "write");
42557
42558// Write a line to the file
42559%fsObject.writeLine("Hello World");
42560
42561// Write another line to the file
42562%fsObject.writeLine("Documentation Rocks!");
42563
42564// Always remember to close a file stream when finished
42565%fsObject.close();
42566@endtsexample
42567
42568@see readLine()*/
42569void writeLine( string line );
42570/*!
42571@brief Read in a string and place it on the string table.
42572
42573@param caseSensitive If false then case will not be taken into account when attempting to match the read in string with what is already in the string table.
42574@return The string that was read from the stream.
42575@see writeString()@note When working with these particular string reading and writing methods, the stream begins with the length of the string followed by the string itself, and does not include a NULL terminator.*/
42576String readSTString( bool caseSensitive=false );
42577/*!
42578@brief Read a string up to a maximum of 256 characters@return The string that was read from the stream.
42579@see writeString()@note When working with these particular string reading and writing methods, the stream begins with the length of the string followed by the string itself, and does not include a NULL terminator.*/
42580String readString();
42581/*!
42582@brief Read in a string up to the given maximum number of characters.
42583
42584@param maxLength The maximum number of characters to read in.
42585@return The string that was read from the stream.
42586@see writeLongString()@note When working with these particular string reading and writing methods, the stream begins with the length of the string followed by the string itself, and does not include a NULL terminator.*/
42587String readLongString( int maxLength );
42588/*!
42589@brief Write out a string up to the maximum number of characters.
42590
42591@param maxLength The maximum number of characters that will be written.
42592@param string The string to write out to the stream.
42593@see readLongString()@note When working with these particular string reading and writing methods, the stream begins with the length of the string followed by the string itself, and does not include a NULL terminator.*/
42594void writeLongString( int maxLength, string string );
42595/*!
42596@brief Write out a string with a default maximum length of 256 characters.
42597
42598@param string The string to write out to the stream
42599@param maxLength The maximum string length to write out with a default of 256 characters.  This value should not be larger than 256 as it is written to the stream as a single byte.
42600@see readString()@note When working with these particular string reading and writing methods, the stream begins with the length of the string followed by the string itself, and does not include a NULL terminator.*/
42601void writeString( string string, int maxLength=256 );
42602/*!
42603@brief Copy from another StreamObject into this StreamObject
42604
42605@param other The StreamObject to copy from.
42606@return True if the copy was successful.*/
42607bool copyFrom( SimObject other );
42608
42609/*! @name Callbacks
42610@{ */
42611/// @}
42612
42613
42614/*! @name Ungrouped
42615@{ */
42616/// @}
42617
42618
42619/*! @name Object
42620@{ */
42621/// @}
42622
42623
42624/*! @name Editing
42625@{ */
42626/// @}
42627
42628
42629/*! @name Persistence
42630@{ */
42631/// @}
42632
42633};
42634
42635/*!
42636@brief A wrapper around StreamObject for parsing text and data from files.
42637
42638FileStreamObject inherits from StreamObject and provides some unique methods for working with strings.  If you're looking for general file handling, you may want to use FileObject.
42639
42640@tsexample
42641// Create a file stream object for reading
42642%fsObject = new FileStreamObject();
42643
42644// Open a file for reading
42645%fsObject.open("./test.txt", "read");
42646
42647// Get the status and print it
42648%status = %fsObject.getStatus();
42649echo(%status);
42650
42651// Always remember to close a file stream when finished
42652%fsObject.close();
42653@endtsexample
42654
42655@see StreamObject for the list of inherited functions variables
42656@see FileObject for general file handling.
42657@ingroup FileSystem
42658
42659*/
42660class FileStreamObject : public StreamObject {
42661public:
42662/*!
42663@brief Open a file for reading, writing, reading and writing, or appending
42664
42665Using "Read" for the open mode allows you to parse the contents of file, but not making modifications. "Write" will create a new file if it does not exist, or erase the contents of an existing file when opened. Write also allows you to modify the contents of the file.
42666
42667"ReadWrite" will provide the ability to parse data (read it in) and manipulate data (write it out) interchangeably. Keep in mind the stream can move during each operation. Finally, "WriteAppend" will open a file if it exists, but will not clear the contents. You can write new data starting  at the end of the files existing contents.
42668
42669@param filename Name of file to open
42670@param openMode One of "Read", "Write", "ReadWrite" or "WriteAppend"
42671
42672@tsexample
42673// Create a file stream object for reading
42674%fsObject = new FileStreamObject();
42675
42676// Open a file for reading
42677%fsObject.open("./test.txt", "read");
42678
42679// Get the status and print it
42680%status = %fsObject.getStatus();
42681echo(%status);
42682
42683// Always remember to close a file stream when finished
42684%fsObject.close();
42685@endtsexample
42686
42687@return True if the file was successfully opened, false if something went wrong@see close()*/
42688bool open( string filename, string openMode );
42689/*!
42690@brief Close the file. You can no longer read or write to it unless you open it again.
42691
42692@tsexample
42693// Create a file stream object for reading
42694%fsObject = new FileStreamObject();
42695
42696// Open a file for reading
42697%fsObject.open("./test.txt", "read");
42698
42699// Always remember to close a file stream when finished
42700%fsObject.close();
42701@endtsexample
42702
42703@see open()*/
42704void close();
42705
42706/*! @name Callbacks
42707@{ */
42708/// @}
42709
42710
42711/*! @name Ungrouped
42712@{ */
42713/// @}
42714
42715
42716/*! @name Object
42717@{ */
42718/// @}
42719
42720
42721/*! @name Editing
42722@{ */
42723/// @}
42724
42725
42726/*! @name Persistence
42727@{ */
42728/// @}
42729
42730};
42731
42732/*!
42733@brief Provides access to a zip file.
42734
42735A ZipObject add, delete and extract files that are within a zip archive.  You may also read and write directly to the files within the archive by obtaining a StreamObject for the file.@tsexample
42736// Open a zip archive, creating it if it doesn't exist
42737%archive = new ZipObject();
42738%archive.openArchive("testArchive.zip", Write);
42739
42740// Add a file to the archive with the given name
42741%archive.addFile("./water.png", "water.png");
42742
42743// Close the archive to save the changes
42744%archive.closeArchive();
42745@endtsexample
42746
42747@note Behind the scenes all of the work is being done with the ZipArchive and StreamObject classes.
42748@see StreamObject when using methods such as openFileForRead() and openFileForWrite()
42749
42750@ingroup FileSystem
42751
42752*/
42753class ZipObject : public SimObject {
42754public:
42755/*!
42756@brief Open a zip archive for manipulation.
42757
42758Once a zip archive is opened use the various ZipObject methods for working with the files within the archive.  Be sure to close the archive when you are done with it.
42759
42760@param filename The path and file name of the zip archive to open.
42761@param accessMode One of read, write or readwrite
42762@return True is the archive was successfully opened.
42763@note If you wish to make any changes to the archive, be sure to open it with a write or readwrite access mode.
42764@see closeArchive()*/
42765bool openArchive( string filename, string accessMode="read" );
42766/*!
42767@brief Close an already opened zip archive.
42768
42769@see openArchive()*/
42770void closeArchive();
42771/*!
42772@brief Open a file within the zip archive for reading.
42773
42774Be sure to close the file when you are done with it.
42775@param filename The path and name of the file to open within the zip archive.
42776@return A standard StreamObject is returned for working with the file.
42777@note You must first open the zip archive before working with files within it.
42778@see closeFile()
42779@see openArchive()*/
42780SimObject openFileForRead( string filename );
42781/*!
42782@brief Open a file within the zip archive for writing to.
42783
42784Be sure to close the file when you are done with it.
42785@param filename The path and name of the file to open within the zip archive.
42786@return A standard StreamObject is returned for working with the file.
42787@note You must first open the zip archive before working with files within it.
42788@see closeFile()
42789@see openArchive()*/
42790SimObject openFileForWrite( string filename );
42791/*!
42792@brief Close a previously opened file within the zip archive.
42793
42794@param stream The StreamObject of a previously opened file within the zip archive.
42795@see openFileForRead()
42796@see openFileForWrite()*/
42797void closeFile( SimObject stream );
42798/*!
42799@brief Add a file to the zip archive
42800
42801@param filename The path and name of the file to add to the zip archive.
42802@param pathInZip The path and name to be given to the file within the zip archive.
42803@param replace If a file already exists within the zip archive at the same location as this new file, this parameter indicates if it should be replaced.  By default, it will be replaced.
42804@return True if the file was successfully added to the zip archive.*/
42805bool addFile( string filename, string pathInZip, bool replace=true );
42806/*!
42807@brief Extact a file from the zip archive and save it to the requested location.
42808
42809@param pathInZip The path and name of the file to be extracted within the zip archive.
42810@param filename The path and name to give the extracted file.
42811
42812@return True if the file was successfully extracted.*/
42813bool extractFile( string pathInZip, string filename );
42814/*!
42815@brief Deleted the given file from the zip archive
42816
42817@param pathInZip The path and name of the file to be deleted from the zip archive.
42818@return True of the file was successfully deleted.
42819@note Files that have been deleted from the archive will still show up with a getFileEntryCount() until you close the archive.  If you need to have the file count up to date with only valid files within the archive, you could close and then open the archive again.
42820@see getFileEntryCount()
42821@see closeArchive()
42822@see openArchive()*/
42823bool deleteFile( string pathInZip );
42824/*!
42825@brief Get the number of files within the zip archive.
42826
42827Use getFileEntry() to retrive information on each file within the archive.
42828
42829@return The number of files within the zip archive.
42830@note The returned count will include any files that have been deleted from the archive using deleteFile().  To clear out all deleted files, you could close and then open the archive again.
42831@see getFileEntry()
42832@see closeArchive()
42833@see openArchive()*/
42834int getFileEntryCount();
42835/*!
42836@brief Get information on the requested file within the zip archive.
42837
42838This methods provides five different pieces of information for the requested file:
42839<ul><li>filename - The path and name of the file within the zip archive</li><li>uncompressed size</li><li>compressed size</li><li>compression method</li><li>CRC32</li></ul>
42840Use getFileEntryCount() to obtain the total number of files within the archive.
42841@param index The index of the file within the zip archive.  Use getFileEntryCount() to determine the number of files.
42842@return A tab delimited list of information on the requested file, or an empty string if the file could not be found.
42843@see getFileEntryCount()*/
42844String getFileEntry( int index );
42845
42846/*! @name Callbacks
42847@{ */
42848/// @}
42849
42850
42851/*! @name Ungrouped
42852@{ */
42853/// @}
42854
42855
42856/*! @name Object
42857@{ */
42858/// @}
42859
42860
42861/*! @name Editing
42862@{ */
42863/// @}
42864
42865
42866/*! @name Persistence
42867@{ */
42868/// @}
42869
42870};
42871
42872/*!
42873@brief Provides the code necessary to handle the low level management of the string tables for localization
42874
42875One LangTable is created for each mod, as well as one for the C++ code. LangTable is responsible for obtaining the correct strings from each and relaying it to the appropriate controls.
42876
42877@see Localization for a full description
42878
42879@ingroup Localization
42880
42881*/
42882class LangTable : public SimObject {
42883public:
42884/*!
42885@brief Adds a language to the table
42886
42887@param filename Name and path to the language file
42888@param languageName Optional name to assign to the new language entry
42889
42890@return True If file was successfully found and language created*/
42891int addLanguage( String filename="", String languageName="" );
42892/*!
42893@brief Grabs a string from the specified table
42894
42895If an invalid is passed, the function will attempt to to grab from the default table
42896
42897@param filename Name of the language table to access
42898
42899@return Text from the specified language table, "" if ID was invalid and default table is not set*/
42900string getString( uint id );
42901/*!
42902@brief Sets the default language table
42903
42904@param language ID of the table*/
42905void setDefaultLanguage( int langId );
42906/*!
42907@brief Sets the current language table for grabbing text
42908
42909@param language ID of the table*/
42910void setCurrentLanguage( int langId );
42911/*!
42912@brief Get the ID of the current language table
42913
42914@return Numerical ID of the current language table*/
42915int getCurrentLanguage();
42916/*!
42917@brief Return the readable name of the language table
42918
42919@param language Numerical ID of the language table to access
42920
42921@return String containing the name of the table, NULL if ID was invalid or name was never specified*/
42922string getLangName( int langId );
42923/*!
42924@brief Used to find out how many languages are in the table
42925
42926@return Size of the vector containing the languages, numerical*/
42927int getNumLang();
42928
42929/*! @name Callbacks
42930@{ */
42931/// @}
42932
42933
42934/*! @name Ungrouped
42935@{ */
42936/// @}
42937
42938
42939/*! @name Object
42940@{ */
42941/// @}
42942
42943
42944/*! @name Editing
42945@{ */
42946/// @}
42947
42948
42949/*! @name Persistence
42950@{ */
42951/// @}
42952
42953};
42954
42955/*!
42956@brief The EventManager class is a wrapper for the standard messaging system.
42957
42958It provides functionality for management of event queues, events, and subscriptions. Creating an EventManager is as simple as calling new EventManager and specifying a queue name.
42959
42960@tsexample
42961// Create the EventManager.
42962$MyEventManager = new EventManager() { queue = "MyEventManager"; };
42963
42964// Create an event.
42965$MyEventManager.registerEvent( "SomeCoolEvent" );
42966
42967// Create a listener and subscribe.
42968$MyListener = new ScriptMsgListener() { class = MyListener; };
42969$MyEventManager.subscribe( $MyListener, "SomeCoolEvent" );
42970
42971function MyListener::onSomeCoolEvent( %this, %data )
42972{
42973     echo( "onSomeCoolEvent Triggered" );
42974}
42975
42976// Trigger the event.
42977$MyEventManager.postEvent( "SomeCoolEvent", "Data" );
42978@endtsexample
42979
42980@see ScriptMsgListener
42981
42982@ingroup Messaging
42983
42984*/
42985class EventManager : public SimObject {
42986public:
42987/*!
42988@brief Register an event with the event manager.
42989
42990@param event The event to register.
42991@return Whether or not the event was registered successfully.*/
42992bool registerEvent( string evt );
42993/*!
42994@brief Remove an event from the EventManager.
42995
42996@param event The event to remove.
42997*/
42998void unregisterEvent( string evt );
42999/*!
43000@brief Check if an event is registered or not.
43001
43002@param event The event to check.
43003@return Whether or not the event exists.*/
43004bool isRegisteredEvent( string evt );
43005/*!
43006@brief ~Trigger an event.
43007
43008@param event The event to trigger.
43009@param data The data associated with the event.
43010@return Whether or not the event was dispatched successfully.*/
43011bool postEvent( string evt, string data="" );
43012/*!
43013@brief Subscribe a listener to an event.
43014
43015@param listener The listener to subscribe.
43016@param event The event to subscribe to.
43017@param callback Optional method name to receive the event notification. If this is not specified, "on[event]" will be used.
43018@return Whether or not the subscription was successful.*/
43019bool subscribe( string listenerName, string evt, string callback="" );
43020/*!
43021@brief Remove a listener from an event.
43022
43023@param listener The listener to remove.
43024@param event The event to be removed from.
43025*/
43026void remove( string listenerName, string evt );
43027/*!
43028@brief Remove a listener from all events.
43029
43030@param listener The listener to remove.
43031*/
43032void removeAll( string listenerName );
43033/*!
43034@brief Print all registered events to the console.
43035
43036*/
43037void dumpEvents();
43038/*!
43039@brief Print all subscribers to an event to the console.
43040
43041@param event The event whose subscribers are to be printed. If this parameter isn't specified, all events will be dumped.*/
43042void dumpSubscribers( string listenerName="" );
43043
43044/*! @name Callbacks
43045@{ */
43046/// @}
43047
43048/*!
43049@brief List of events currently waiting
43050*/
43051string queue;
43052};
43053
43054/*!
43055@brief Base class for messages
43056
43057Message is the base class for C++ defined messages, and may also be used in script for script defined messages if no C++ subclass is appropriate.
43058
43059Messages are reference counted and will be automatically deleted when their reference count reaches zero. When you dispatch a message, a reference will be added before the dispatch and freed after the dispatch. This allows for temporary messages with no additional code. If you want to keep the message around, for example to dispatch it to multiple queues, call addReference() before dispatching it and freeReference() when you are done with it. Never delete a Message object directly unless addReference() has not been called or the message has not been dispatched.
43060
43061Message IDs are pooled similarly to datablocks, with the exception that IDs are reused. If you keep a message for longer than a single dispatch, then you should ensure that you clear any script variables that refer to it after the last freeReference(). If you don't, then it is probable that the object ID will become valid again in the future and could cause hard to track down bugs.
43062
43063Messages have a unique type to simplify message handling code. For object messages, the type is defined as either the script defined class name or the C++ class name if no script class was defined. The message type may be obtained through the getType() method.
43064
43065By convention, any data for the message is held in script accessible fields. Messages that need to be handled in C++ as well as script provide the relevant data through persistent fields in a subclass of Message to provide best performance on the C++ side. Script defined messages usually their through dynamic fields, and may be accessed in C++ using the SimObject::getDataField() method.
43066
43067@ingroup Messaging
43068
43069*/
43070class Message : public SimObject {
43071public:
43072/*!
43073@brief Get message type (script class name or C++ class name if no script defined class)
43074
43075*/
43076string getType();
43077/*!
43078@brief Increment the reference count for this message
43079
43080*/
43081void addReference();
43082/*!
43083@brief Decrement the reference count for this message
43084
43085*/
43086void freeReference();
43087
43088/*! @name Callbacks
43089@{ */
43090/*!
43091@brief Script callback when a message is first created and registered.
43092
43093
43094@tsexample
43095function Message::onAdd(%this)
43096{
43097   // Perform on add code here
43098}
43099@endtsexample
43100
43101*/
43102void onAdd();
43103/*!
43104@brief Script callback when a message is deleted.
43105
43106
43107@tsexample
43108function Message::onRemove(%this)
43109{
43110   // Perform on remove code here
43111}
43112@endtsexample
43113
43114*/
43115void onRemove();
43116/// @}
43117
43118
43119/*! @name Ungrouped
43120@{ */
43121/// @}
43122
43123
43124/*! @name Object
43125@{ */
43126/// @}
43127
43128
43129/*! @name Editing
43130@{ */
43131/// @}
43132
43133
43134/*! @name Persistence
43135@{ */
43136/// @}
43137
43138};
43139
43140/*!
43141@brief Definition of a named texture target playing a Theora video.
43142
43143TheoraTextureObject defines a named texture target that may play back a Theora video.  This texture target can, for example, be used by materials to texture objects with videos.
43144
43145@tsexample
43146// The object that provides the video texture and controls its playback.
43147singleton TheoraTextureObject( TheVideo )
43148{
43149   // Unique name for the texture target for referencing in materials.
43150   texTargetName = "video";
43151
43152   // Path to the video file.
43153   theoraFile = "./MyVideo.ogv";
43154};
43155
43156// Material that uses the video texture.
43157singleton Material( TheVideoMaterial )
43158{
43159   // This has to reference the named texture target defined by the
43160   // TheoraTextureObject's 'texTargetName' property.  Prefix with '#' to
43161   // identify as texture target reference.
43162   diffuseMap[ 0 ] = "#video";
43163};
43164@endtsexample
43165
43166@ingroup Rendering
43167*/
43168class TheoraTextureObject : public SimObject {
43169public:
43170/*!
43171@brief Start playback of the video.
43172
43173*/
43174void play();
43175/*!
43176@brief Stop playback of the video.
43177
43178*/
43179void stop();
43180/*!
43181@brief Pause playback of the video.
43182
43183*/
43184void pause();
43185
43186/*! @name Callbacks
43187@{ */
43188/// @}
43189
43190
43191/*! @name Theora
43192@{ */
43193/*!
43194@brief Theora video file to play.
43195*/
43196filename theoraFile;
43197/*!
43198@brief Name of the texture target by which the texture can be referenced in materials.
43199*/
43200string texTargetName;
43201/*!
43202@brief Sound description to use for the video's audio channel.
43203
43204
43205If not set, will use a default one.
43206*/
43207SFXDescription SFXDescription;
43208/*!
43209@brief Should the video loop.
43210*/
43211bool Loop;
43212/// @}
43213
43214
43215/*! @name Ungrouped
43216@{ */
43217/// @}
43218
43219
43220/*! @name Object
43221@{ */
43222/// @}
43223
43224
43225/*! @name Editing
43226@{ */
43227/// @}
43228
43229
43230/*! @name Persistence
43231@{ */
43232/// @}
43233
43234};
43235
43236class GFXCardProfilerAPI {
43237public:
43238/*!
43239@brief Returns the driver version string.
43240
43241*/
43242static String getVersion();
43243/*!
43244@brief Returns the card name.
43245
43246*/
43247static String getCard();
43248/*!
43249@brief Returns the card vendor name.
43250
43251*/
43252static String GetVendor();
43253/*!
43254@brief Returns the renderer name.  For example D3D11 or OpenGL.
43255
43256*/
43257static String getRenderer();
43258/*!
43259@brief Returns the amount of video memory in megabytes.
43260
43261*/
43262static int getVideoMemoryMB();
43263/*!
43264@brief Used to set the value for a specific card capability.
43265
43266@param name The name of the capability being set.
43267@param value The value to set for that capability.*/
43268static void setCapability( string name, int value );
43269/*!
43270@brief Used to query the value of a specific card capability.
43271
43272@param name The name of the capability being queried.
43273@param defaultValue The value to return if the capability is not defined.*/
43274static int queryProfile( string name, int defaultValue );
43275/*!
43276@brief Returns the card name.
43277
43278*/
43279static String getBestDepthFormat();
43280
43281/*! @name Callbacks
43282@{ */
43283/// @}
43284
43285};
43286
43287class GFXInit {
43288public:
43289/*!
43290@brief Return the number of graphics adapters available. @ingroup GFX
43291
43292*/
43293static int getAdapterCount();
43294/*!
43295@brief Returns the name of the graphics adapter.
43296
43297@param index The index of the adapter.*/
43298static String getAdapterName( int index );
43299/*!
43300@brief Returns the name of the graphics adapter's output display device.
43301
43302@param index The index of the adapter.*/
43303static String getAdapterOutputName( int index );
43304/*!
43305@brief Returns the type (D3D11, GL, Null) of a graphics adapter.
43306
43307@param index The index of the adapter.*/
43308static GFXAdapterType getAdapterType( int index );
43309/*!
43310@brief Returns the supported shader model of the graphics adapter or -1 if the index is bad.
43311
43312@param index The index of the adapter.*/
43313static float getAdapterShaderModel( int index );
43314/*!
43315@brief Returns the index of the default graphics adapter.  This is the graphics device which will be used to initialize the engine.
43316
43317*/
43318static int getDefaultAdapterIndex();
43319/*!
43320@brief Gets the number of modes available on the specified adapter.
43321
43322
43323@param index Index of the adapter to get modes from.
43324@return The number of video modes supported by the adapter or -1 if the given adapter was not found.*/
43325static int getAdapterModeCount( int index );
43326/*!
43327@brief Gets the details of the specified adapter mode.
43328
43329
43330@param index Index of the adapter to query.
43331@param modeIndex Index of the mode to get data from.
43332@return A video mode string in the format 'width height fullscreen bitDepth refreshRate aaLevel'.
43333@see GuiCanvas::getVideoMode()*/
43334static String getAdapterMode( int index, int modeIndex );
43335/*!
43336@brief Create the NULL graphics device used for testing or headless operation.
43337
43338*/
43339static void createNullDevice();
43340
43341/*! @name Callbacks
43342@{ */
43343/// @}
43344
43345};
43346
43347/*!
43348@brief A Shader Feature with custom definitions.
43349
43350This class allows for the creation and implementation of a ShaderGen ShaderFeature Implemented either engine side or script, and facilitates passing along of per-instance ShaderData. @ingroup Examples
43351
43352*/
43353class CustomShaderFeatureData : public SimObject {
43354public:
43355void addVariable( String name="", String type="", String defaultValue="" );
43356void addUniform( String name="", String type="", String defaultValue="", uint arraySize=0 );
43357void addSampler( String name="", uint arraySize=0 );
43358void addTexture( String name, String type="", String samplerState="", uint arraySize=0 );
43359void addConnector( String name="", String type="", String elementName="" );
43360void addVertTexCoord( String name="" );
43361/*!
43362@brief Dynamically call a method on an object.
43363
43364@param method Name of method to call.
43365@param args Zero or more arguments for the method.
43366@return The result of the method call.*/
43367void writeLine( string format, string args... );
43368bool hasFeature( String name="" );
43369
43370/*! @name Callbacks
43371@{ */
43372/// @}
43373
43374
43375/*! @name Ungrouped
43376@{ */
43377/// @}
43378
43379
43380/*! @name Object
43381@{ */
43382/// @}
43383
43384
43385/*! @name Editing
43386@{ */
43387/// @}
43388
43389
43390/*! @name Persistence
43391@{ */
43392/// @}
43393
43394};
43395
43396/*!
43397@brief Used to create static or dynamic cubemaps.
43398
43399This object is used with Material, WaterObject, and other objects for cubemap reflections.
43400
43401A simple declaration of a static cubemap:
43402@tsexample
43403singleton CubemapData( SkyboxCubemap )
43404{
43405   cubeFace[0] = "./skybox_1";
43406   cubeFace[1] = "./skybox_2";
43407   cubeFace[2] = "./skybox_3";
43408   cubeFace[3] = "./skybox_4";
43409   cubeFace[4] = "./skybox_5";
43410   cubeFace[5] = "./skybox_6";
43411};
43412@endtsexample
43413@note The dynamic cubemap functionality in CubemapData has been depreciated in favor of ReflectorDesc.
43414@see ReflectorDesc
43415@ingroup GFX
43416
43417*/
43418class CubemapData : public SimObject {
43419public:
43420/*!
43421@brief Update the assigned cubemaps faces.
43422
43423*/
43424void updateFaces();
43425/*!
43426@brief Returns the script filename of where the CubemapData object was defined.  This is used by the material editor.
43427
43428*/
43429string getFilename();
43430/*!
43431@brief Returns the script filename of where the CubemapData object was defined.  This is used by the material editor.
43432
43433*/
43434void save( string filename="", GFXFormat format=<a href="/scripting/group/group__gfx/#group__gfx_1gga81aab0c9b2675820d5721e6152d939cbabb45eeaeb0e6a08158db626fe754bd95">GFXFormatBC1</a> );
43435
43436/*! @name Callbacks
43437@{ */
43438/// @}
43439
43440/*!
43441@brief @brief The 6 cubemap face textures for a static cubemap.
43442
43443
43444They are in the following order:
43445  - cubeFace[0] is -X
43446  - cubeFace[1] is +X
43447  - cubeFace[2] is -Z
43448  - cubeFace[3] is +Z
43449  - cubeFace[4] is -Y
43450  - cubeFace[5] is +Y
43451
43452*/
43453filename cubeFace[ 6 ];
43454/*!
43455@brief @brief Cubemap dds file.
43456
43457
43458
43459*/
43460filename cubemap;
43461};
43462
43463/*!
43464@brief Draws the bitmap within a special button control.  Only a single bitmap is used and the
43465button will be drawn in a highlighted mode when the mouse hovers over it or when it
43466has been clicked.
43467
43468@tsexample
43469new GuiIconButtonCtrl(TestIconButton)
43470{
43471 buttonMargin = "4 4";
43472 iconBitmap = "art/gui/lagIcon.png";
43473 iconLocation = "Center";
43474 sizeIconToButton = "0";
43475 makeIconSquare = "1";
43476 textLocation = "Bottom";
43477 textMargin = "-2";
43478  autoSize = "0";
43479  text = "Lag Icon";
43480  textID = ""STR_LAG"";
43481  buttonType = "PushButton";
43482  profile = "GuiIconButtonProfile";
43483};
43484@endtsexample
43485
43486@see GuiControl
43487@see GuiButtonCtrl
43488
43489@ingroup GuiCore
43490
43491*/
43492class GuiIconButtonCtrl : public GuiButtonCtrl {
43493public:
43494/*!
43495@brief Set the bitmap to use for the button portion of this control.
43496
43497@param buttonFilename Filename for the image
43498@tsexample
43499// Define the button filename
43500%buttonFilename = "pearlButton";
43501
43502// Inform the GuiIconButtonCtrl control to update its main button graphic to the defined bitmap
43503%thisGuiIconButtonCtrl.setBitmap(%buttonFilename);
43504@endtsexample
43505
43506@see GuiControl
43507@see GuiButtonCtrl*/
43508void setBitmap( string buttonFilename );
43509
43510/*! @name Callbacks
43511@{ */
43512/// @}
43513
43514/*!
43515@brief Margin area around the button.
43516
43517
43518*/
43519Point2I buttonMargin;
43520/*!
43521@brief Bitmap file for the icon to display on the button.
43522
43523
43524*/
43525filename iconBitmap;
43526/*!
43527@brief Where to place the icon on the control. Options are 0 (None), 1 (Left), 2 (Right), 3 (Center).
43528
43529
43530*/
43531GuiIconButtonIconLocation iconLocation;
43532/*!
43533@brief If true, the icon will be scaled to be the same size as the button.
43534
43535
43536*/
43537bool sizeIconToButton;
43538/*!
43539@brief If true, will make sure the icon is square.
43540
43541
43542*/
43543bool makeIconSquare;
43544/*!
43545@brief Where to place the text on the control.
43546
43547Options are 0 (None), 1 (Bottom), 2 (Right), 3 (Top), 4 (Left), 5 (Center).
43548
43549*/
43550GuiIconButtonTextLocation textLocation;
43551/*!
43552@brief Margin between the icon and the text.
43553
43554
43555*/
43556int textMargin;
43557/*!
43558@brief If true, the text and icon will be automatically sized to the size of the control.
43559
43560
43561*/
43562bool autoSize;
43563
43564/*! @name Button
43565@{ */
43566/// @}
43567
43568
43569/*! @name Layout
43570@{ */
43571/// @}
43572
43573
43574/*! @name Control
43575@{ */
43576/// @}
43577
43578
43579/*! @name ToolTip
43580@{ */
43581/// @}
43582
43583
43584/*! @name Editing
43585@{ */
43586/// @}
43587
43588
43589/*! @name Localization
43590@{ */
43591/// @}
43592
43593
43594/*! @name Ungrouped
43595@{ */
43596/// @}
43597
43598
43599/*! @name Object
43600@{ */
43601/// @}
43602
43603
43604/*! @name Editing
43605@{ */
43606/// @}
43607
43608
43609/*! @name Persistence
43610@{ */
43611/// @}
43612
43613};
43614
43615/*!
43616@brief A button that is used to represent color; often used in correlation with a color picker.
43617
43618A swatch button is a push button that uses its color field to designate the color drawn over an image, on top of a button.
43619
43620The color itself is a float value stored inside the GuiSwatchButtonCtrl::color field. The texture path that represents
43621the image underlying the color is stored inside the GuiSwatchButtonCtrl::gridBitmap field.
43622The default value assigned toGuiSwatchButtonCtrl::color is "1 1 1 1"( White ). The default/fallback image assigned to 
43623GuiSwatchButtonCtrl::gridBitmap is "tools/gui/images/transp_grid".
43624
43625@tsexample
43626// Create a GuiSwatchButtonCtrl that calls randomFunction with its current color when clicked
43627%swatchButton = new GuiSwatchButtonCtrl()
43628{
43629   profile = "GuiInspectorSwatchButtonProfile";
43630   command = "randomFunction( $ThisControl.color );";
43631};
43632@endtsexample
43633
43634@ingroup GuiButtons
43635*/
43636class GuiSwatchButtonCtrl : public GuiButtonBaseCtrl {
43637public:
43638/*!
43639@brief Set the color of the swatch control.
43640
43641@param newColor The new color string given to the swatch control in float format "r g b a".
43642@note It's also important to note that when setColor is called causes
43643the control's altCommand field to be executed.*/
43644void setColor( string newColor );
43645
43646/*! @name Callbacks
43647@{ */
43648/// @}
43649
43650/*!
43651@brief The foreground color of GuiSwatchButtonCtrl
43652*/
43653LinearColorF color;
43654/*!
43655@brief The bitmap used for the transparent grid
43656*/
43657string gridBitmap;
43658
43659/*! @name Button
43660@{ */
43661/// @}
43662
43663
43664/*! @name Layout
43665@{ */
43666/// @}
43667
43668
43669/*! @name Control
43670@{ */
43671/// @}
43672
43673
43674/*! @name ToolTip
43675@{ */
43676/// @}
43677
43678
43679/*! @name Editing
43680@{ */
43681/// @}
43682
43683
43684/*! @name Localization
43685@{ */
43686/// @}
43687
43688
43689/*! @name Ungrouped
43690@{ */
43691/// @}
43692
43693
43694/*! @name Object
43695@{ */
43696/// @}
43697
43698
43699/*! @name Editing
43700@{ */
43701/// @}
43702
43703
43704/*! @name Persistence
43705@{ */
43706/// @}
43707
43708};
43709
43710/*!
43711@brief Brief Description.
43712
43713This Gui Control is designed to be subclassed to let people create controls which want to receive update ticks at a constant interval. This class was created to be the Parent class of a control which used a DynamicTexture along with a VectorField to create warping effects much like the ones found in visualization displays for iTunes or Winamp. Those displays are updated at the framerate frequency. This works fine for those effects, however for an application of the same type of effects for things like Gui transitions the framerate-driven update frequency is not desirable because it does not allow the developer to be able to have any idea of a consistent user-experience.
43714
43715Enter the ITickable interface. This lets the Gui control, in this case, update the dynamic texture at a constant rate of once per tick, even though it gets rendered every frame, thus creating a framerate-independent update frequency so that the effects are at a consistent speed regardless of the specifics of the system the user is on. This means that the screen-transitions will occur in the same time on a machine getting 300fps in the Gui shell as a machine which gets 150fps in the Gui shell.
43716
43717@ingroup GuiUtil
43718
43719*/
43720class GuiTickCtrl : public GuiControl {
43721public:
43722/*!
43723This will set this object to either be processing ticks or not.
43724
43725@param tick (optional) True or nothing to enable ticking, false otherwise.
43726
43727@tsexample
43728// Turn off ticking for a control, like a MenuBar (declared previously)
43729%sampleMenuBar.setProcessTicks(false);
43730@endtsexample
43731
43732*/
43733
43734void setProcessTicks( bool tick )
43735/*!
43736@brief This will set this object to either be processing ticks or not
43737
43738*/
43739void setProcessTicks( bool tick=true );
43740
43741/*! @name Callbacks
43742@{ */
43743/// @}
43744
43745
43746/*! @name Layout
43747@{ */
43748/// @}
43749
43750
43751/*! @name Control
43752@{ */
43753/// @}
43754
43755
43756/*! @name ToolTip
43757@{ */
43758/// @}
43759
43760
43761/*! @name Editing
43762@{ */
43763/// @}
43764
43765
43766/*! @name Localization
43767@{ */
43768/// @}
43769
43770
43771/*! @name Ungrouped
43772@{ */
43773/// @}
43774
43775
43776/*! @name Object
43777@{ */
43778/// @}
43779
43780
43781/*! @name Editing
43782@{ */
43783/// @}
43784
43785
43786/*! @name Persistence
43787@{ */
43788/// @}
43789
43790};
43791
43792/*!
43793@brief A container that scrolls its child control up over time.
43794
43795This container can be used to scroll a single child control in either of the four directions.
43796
43797@tsexample
43798// Create a GuiAutoScrollCtrl that scrolls a long text of credits.
43799new GuiAutoScrollCtrl( CreditsScroller )
43800{
43801   position = "0 0";
43802   extent = Canvas.extent.x SPC Canvas.extent.y;
43803
43804   scrollDirection = "Up"; // Scroll upwards.
43805   startDelay = 4; // Wait 4 seconds before starting to scroll.
43806   isLooping = false; // Don't loop the credits.
43807   scrollOutOfSight = true; // Scroll up fully.
43808
43809   new GuiMLTextCtrl()
43810   {
43811      text = $CREDITS;
43812   };
43813};
43814
43815function CreditsScroller::onComplete( %this )
43816{
43817   // Switch back to main menu after credits have rolled.
43818   Canvas.setContent( MainMenu );
43819}
43820
43821// Start rolling credits.
43822Canvas.setContent( CreditsScroller );
43823@endtsexample
43824
43825@note Only the first child will be scrolled.
43826
43827@ingroup GuiContainers
43828*/
43829class GuiAutoScrollCtrl : public GuiTickCtrl {
43830public:
43831/*!
43832@brief Reset scrolling.
43833
43834*/
43835void reset();
43836
43837/*! @name Callbacks
43838@{ */
43839/*!
43840@brief Called every 32ms on the control.
43841
43842*/
43843void onTick();
43844/*!
43845@brief Called when the control starts to scroll.
43846
43847*/
43848void onStart();
43849/*!
43850@brief Called when the child control has been scrolled in entirety.
43851
43852*/
43853void onComplete();
43854/*!
43855@brief Called when the child control is reset to its initial position and the cycle starts again.
43856
43857*/
43858void onReset();
43859/// @}
43860
43861
43862/*! @name Scrolling
43863@{ */
43864/*!
43865@brief Direction in which the child control is moved.
43866*/
43867GuiAutoScrollDirection scrollDirection;
43868/*!
43869@brief Seconds to wait before starting to scroll.
43870*/
43871float startDelay;
43872/*!
43873@brief Seconds to wait after scrolling completes before resetting and starting over.
43874
43875
43876@note Only takes effect if #isLooping is true.
43877*/
43878float resetDelay;
43879/*!
43880@brief Padding to put around child control (in pixels).
43881*/
43882int childBorder;
43883/*!
43884@brief Scrolling speed in pixels per second.
43885*/
43886float scrollSpeed;
43887/*!
43888@brief If true, the scrolling will reset to the beginning once completing a cycle.
43889*/
43890bool isLooping;
43891/*!
43892@brief If true, the child control will be completely scrolled out of sight; otherwise it will only scroll until the other end becomes visible.
43893*/
43894bool scrollOutOfSight;
43895/// @}
43896
43897
43898/*! @name Layout
43899@{ */
43900/// @}
43901
43902
43903/*! @name Control
43904@{ */
43905/// @}
43906
43907
43908/*! @name ToolTip
43909@{ */
43910/// @}
43911
43912
43913/*! @name Editing
43914@{ */
43915/// @}
43916
43917
43918/*! @name Localization
43919@{ */
43920/// @}
43921
43922
43923/*! @name Ungrouped
43924@{ */
43925/// @}
43926
43927
43928/*! @name Object
43929@{ */
43930/// @}
43931
43932
43933/*! @name Editing
43934@{ */
43935/// @}
43936
43937
43938/*! @name Persistence
43939@{ */
43940/// @}
43941
43942};
43943
43944/*!
43945@brief A container control that can be used to implement drag&drop behavior.
43946
43947GuiDragAndDropControl is a special control that can be used to allow drag&drop behavior to be implemented where GuiControls may be dragged across the canvas and the dropped on other GuiControls.
43948
43949To start a drag operation, construct a GuiDragAndDropControl and add the control that should be drag&dropped as a child to it.  Note that this must be a single child control.  To drag multiple controls, wrap them in a new GuiControl object as a temporary container.
43950
43951Then, to initiate the drag, add the GuiDragAndDropControl to the canvas and call startDragging().  You can optionally supply an offset to better position the GuiDragAndDropControl on the mouse cursor.
43952
43953As the GuiDragAndDropControl is then moved across the canvas, it will call the onControlDragEnter(), onControlDragExit(), onControlDragged(), and finally onControlDropped() callbacks on the visible topmost controls that it moves across.  onControlDropped() is called when the mouse button is released and the drag operation thus finished.
43954
43955@tsexample
43956// The following example implements drag&drop behavior for GuiSwatchButtonCtrl so that
43957// one color swatch may be dragged over the other to quickly copy its color.
43958//
43959// This code is taken from the stock scripts.
43960
43961//---------------------------------------------------------------------------------------------
43962
43963// With this method, we start the operation when the mouse is click-dragged away from a color swatch.
43964function GuiSwatchButtonCtrl::onMouseDragged( %this )
43965{
43966   // First we construct a new temporary swatch button that becomes the payload for our
43967   // drag operation and give it the properties of the swatch button we want to copy.
43968
43969   %payload = new GuiSwatchButtonCtrl();
43970   %payload.assignFieldsFrom( %this );
43971   %payload.position = "0 0";
43972   %payload.dragSourceControl = %this; // Remember where the drag originated from so that we don't copy a color swatch onto itself.
43973
43974   // Calculate the offset of the GuiDragAndDropControl from the mouse cursor.  Here we center
43975   // it on the cursor.
43976
43977   %xOffset = getWord( %payload.extent, 0 ) / 2;
43978   %yOffset = getWord( %payload.extent, 1 ) / 2;
43979
43980   // Compute the initial position of the GuiDragAndDrop control on the cavas based on the current
43981   // mouse cursor position.
43982
43983   %cursorpos = Canvas.getCursorPos();
43984   %xPos = getWord( %cursorpos, 0 ) - %xOffset;
43985   %yPos = getWord( %cursorpos, 1 ) - %yOffset;
43986
43987   // Create the drag control.
43988
43989   %ctrl = new GuiDragAndDropControl()
43990   {
43991      canSaveDynamicFields    = "0";
43992      Profile                 = "GuiSolidDefaultProfile";
43993      HorizSizing             = "right";
43994      VertSizing              = "bottom";
43995      Position                = %xPos SPC %yPos;
43996      extent                  = %payload.extent;
43997      MinExtent               = "4 4";
43998      canSave                 = "1";
43999      Visible                 = "1";
44000      hovertime               = "1000";
44001
44002      // Let the GuiDragAndDropControl delete itself on mouse-up.  When the drag is aborted,
44003      // this not only deletes the drag control but also our payload.
44004      deleteOnMouseUp         = true;
44005
44006      // To differentiate drags, use the namespace hierarchy to classify them.
44007      // This will allow a color swatch drag to tell itself apart from a file drag, for example.
44008      class                   = "GuiDragAndDropControlType_ColorSwatch";
44009   };
44010
44011   // Add the temporary color swatch to the drag control as the payload.
44012   %ctrl.add( %payload );
44013
44014   // Start drag by adding the drag control to the canvas and then calling startDragging().
44015
44016   Canvas.getContent().add( %ctrl );
44017   %ctrl.startDragging( %xOffset, %yOffset );
44018}
44019
44020//---------------------------------------------------------------------------------------------
44021
44022// This method receives the drop when the mouse button is released over a color swatch control
44023// during a drag operation.
44024function GuiSwatchButtonCtrl::onControlDropped( %this, %payload, %position )
44025{
44026   // Make sure this is a color swatch drag operation.
44027   if( !%payload.parentGroup.isInNamespaceHierarchy( "GuiDragAndDropControlType_ColorSwatch" ) )
44028      return;
44029
44030   // If dropped on same button whence we came from,
44031   // do nothing.
44032
44033   if( %payload.dragSourceControl == %this )
44034      return;
44035
44036   // If a swatch button control is dropped onto this control,
44037   // copy it's color.
44038
44039   if( %payload.isMemberOfClass( "GuiSwatchButtonCtrl" ) )
44040   {
44041      // If the swatch button is part of a color-type inspector field,
44042      // remember the inspector field so we can later set the color
44043      // through it.
44044
44045      if( %this.parentGroup.isMemberOfClass( "GuiInspectorTypeColorI" ) )
44046         %this.parentGroup.apply( ColorFloatToInt( %payload.color ) );
44047      else if( %this.parentGroup.isMemberOfClass( "GuiInspectorTypeColorF" ) )
44048         %this.parentGroup.apply( %payload.color );
44049      else
44050         %this.setColor( %payload.color );
44051   }
44052}
44053@endtsexample
44054
44055@see GuiControl::onControlDragEnter
44056@see GuiControl::onControlDragExit
44057@see GuiControl::onControlDragged
44058@see GuiControl::onControlDropped
44059
44060@ingroup GuiUtil
44061*/
44062class GuiDragAndDropControl : public GuiControl {
44063public:
44064/*!
44065@brief Start the drag operation.
44066
44067
44068@param x X coordinate for the mouse pointer offset which the drag control should position itself.
44069@param y Y coordinate for the mouse pointer offset which the drag control should position itself.*/
44070void startDragging( int x=0, int y=0 );
44071
44072/*! @name Callbacks
44073@{ */
44074/*!
44075@brief Called when the we cancel out of the drag and drop action.
44076
44077@see GuiDragAndDropControl::onControlDragCancelled*/
44078void onControlDragCancelled();
44079/// @}
44080
44081/*!
44082@brief If true, the control deletes itself when the left mouse button is released.
44083
44084
44085If at this point, the drag&drop control still contains its payload, it will be deleted along with the control.
44086*/
44087bool deleteOnMouseUp;
44088/*!
44089@brief If true, the control can be tested against ANY control active on the canvas instead of just the direct parent.
44090
44091
44092
44093*/
44094bool useWholeCanvas;
44095
44096/*! @name Layout
44097@{ */
44098/// @}
44099
44100
44101/*! @name Control
44102@{ */
44103/// @}
44104
44105
44106/*! @name ToolTip
44107@{ */
44108/// @}
44109
44110
44111/*! @name Editing
44112@{ */
44113/// @}
44114
44115
44116/*! @name Localization
44117@{ */
44118/// @}
44119
44120
44121/*! @name Ungrouped
44122@{ */
44123/// @}
44124
44125
44126/*! @name Object
44127@{ */
44128/// @}
44129
44130
44131/*! @name Editing
44132@{ */
44133/// @}
44134
44135
44136/*! @name Persistence
44137@{ */
44138/// @}
44139
44140};
44141
44142/*!
44143@brief A container that arranges children into a grid.
44144
44145This container maintains a 2D grid of GUI controls. If one is added, deleted, or resized, then the grid is updated. The insertion order into the grid is determined by the internal order of the children (ie. the order of addition).<br>Children are added to the grid by row or column until they fill the assocated GuiDynamicCtrlArrayControl extent (width or height). For example, a GuiDynamicCtrlArrayControl with 15 children, and <i>fillRowFirst</i> set to true may be arranged as follows:
44146
44147<pre>
441481  2  3  4  5  6
441497  8  9  10 11 12
4415013 14 15
44151</pre>
44152If <i>dynamicSize</i> were set to true in this case, the GuiDynamicCtrlArrayControl height would be calculated to fit the 3 rows of child controls.
44153
44154@tsexample
44155new GuiDynamicCtrlArrayControl()
44156{
44157   colSize = "128";
44158   rowSize = "18";
44159   colSpacing = "2";
44160   rowSpacing = "2";
44161   frozen = "0";
44162   autoCellSize = "1";
44163   fillRowFirst = "1";
44164   dynamicSize = "1";
44165   padding = "0 0 0 0";
44166   //Properties not specific to this control have been omitted from this example.
44167};
44168@endtsexample
44169
44170@ingroup GuiContainers
44171*/
44172class GuiDynamicCtrlArrayControl : public GuiControl {
44173public:
44174/*!
44175@brief Recalculates the position and size of this control and all its children.
44176
44177*/
44178void refresh();
44179
44180/*! @name Callbacks
44181@{ */
44182/// @}
44183
44184/*!
44185@brief Number of columns the child controls have been arranged into. This value is calculated automatically when children are added, removed or resized; writing it directly has no effect.
44186*/
44187int colCount;
44188/*!
44189@brief Width of each column. If <i>autoCellSize</i> is set, this will be calculated automatically from the widest child control
44190*/
44191int colSize;
44192/*!
44193@brief Number of rows the child controls have been arranged into. This value is calculated automatically when children are added, removed or resized; writing it directly has no effect.
44194*/
44195int rowCount;
44196/*!
44197@brief Height of each row. If <i>autoCellSize</i> is set, this will be calculated automatically from the tallest child control
44198*/
44199int rowSize;
44200/*!
44201@brief Spacing between rows
44202*/
44203int rowSpacing;
44204/*!
44205@brief Spacing between columns
44206*/
44207int colSpacing;
44208/*!
44209@brief When true, the array will not update when new children are added or in response to child resize events. This is useful to prevent unnecessary resizing when adding, removing or resizing a number of child controls.
44210*/
44211bool frozen;
44212/*!
44213@brief When true, the cell size is set to the widest/tallest child control.
44214*/
44215bool autoCellSize;
44216/*!
44217@brief Controls whether rows or columns are filled first.
44218
44219
44220If true, controls are added to the grid left-to-right (to fill a row); then rows are added top-to-bottom as shown below:
44221<pre>1 2 3 4
442225 6 7 8</pre>
44223If false, controls are added to the grid top-to-bottom (to fill a column); then columns are added left-to-right as shown below:
44224<pre>1 3 5 7
442252 4 6 8</pre>
44226*/
44227bool fillRowFirst;
44228/*!
44229@brief If true, the width or height of this control will be automatically calculated based on the number of child controls (width if <i>fillRowFirst</i> is false, height if <i>fillRowFirst</i> is true).
44230*/
44231bool dynamicSize;
44232/*!
44233@brief Padding around the top, bottom, left, and right of this control. This reduces the area available for child controls.
44234*/
44235RectSpacingI padding;
44236
44237/*! @name Layout
44238@{ */
44239/// @}
44240
44241
44242/*! @name Control
44243@{ */
44244/// @}
44245
44246
44247/*! @name ToolTip
44248@{ */
44249/// @}
44250
44251
44252/*! @name Editing
44253@{ */
44254/// @}
44255
44256
44257/*! @name Localization
44258@{ */
44259/// @}
44260
44261
44262/*! @name Ungrouped
44263@{ */
44264/// @}
44265
44266
44267/*! @name Object
44268@{ */
44269/// @}
44270
44271
44272/*! @name Editing
44273@{ */
44274/// @}
44275
44276
44277/*! @name Persistence
44278@{ */
44279/// @}
44280
44281};
44282
44283/*!
44284@brief A gui control allowing a window to be subdivided into panes, each of which displays a gui control child of the GuiFrameSetCtrl.
44285
44286Each gui control child will have an associated FrameDetail through which frame-specific details can be assigned. Frame-specific values override the values specified for the entire frameset.
44287
44288Note that it is possible to have more children than frames, or more frames than children. In the former case, the extra children will not be visible (they are moved beyond the visible extent of the frameset). In the latter case, frames will be empty. For example, if a frameset had two columns and two rows but only three gui control children they would be assigned to frames as follows:
44289<pre>
44290                 1 | 2
44291                 -----
44292                 3 |
44293</pre>
44294The last frame would be blank.
44295
44296@tsexample
44297new GuiFrameSetCtrl()
44298{
44299   columns = "3";
44300   rows = "2";
44301   borderWidth = "1";
44302   borderColor = "128 128 128";
44303   borderEnable = "dynamic";
44304   borderMovable = "dynamic";
44305   autoBalance = "1";
44306   fudgeFactor = "0";
44307   //Properties not specific to this control have been omitted from this example.
44308};
44309@endtsexample
44310
44311@ingroup GuiContainers
44312*/
44313class GuiFrameSetCtrl : public GuiContainer {
44314public:
44315/*!
44316@brief Override the <i>borderEnable</i> setting for this frame.
44317
44318
44319@param index  Index of the frame to modify
44320@param state  New borderEnable state: "on", "off" or "dynamic"
44321*/
44322void frameBorder( int index, string state="dynamic" );
44323/*!
44324@brief Override the <i>borderMovable</i> setting for this frame.
44325
44326
44327@param index  Index of the frame to modify
44328@param state  New borderEnable state: "on", "off" or "dynamic"
44329*/
44330void frameMovable( int index, string state="dynamic" );
44331/*!
44332@brief Set the minimum width and height for the frame. It will not be possible for the user to resize the frame smaller than this.
44333
44334
44335@param index  Index of the frame to modify
44336@param width  Minimum width in pixels
44337@param height Minimum height in pixels
44338*/
44339void frameMinExtent( int index, int width, int height );
44340/*!
44341@brief Set the padding for this frame. Padding introduces blank space on the inside edge of the frame.
44342
44343
44344@param index     Index of the frame to modify
44345@param padding   Frame top, bottom, left, and right padding
44346*/
44347void framePadding( int index, RectSpacingI padding );
44348/*!
44349@brief Get the padding for this frame.
44350
44351
44352@param index     Index of the frame to query
44353*/
44354RectSpacingI getFramePadding( int index );
44355/*!
44356@brief Add a new column.
44357
44358
44359*/
44360void addColumn();
44361/*!
44362@brief Add a new row.
44363
44364
44365*/
44366void addRow();
44367/*!
44368@brief Remove the last (rightmost) column.
44369
44370
44371*/
44372void removeColumn();
44373/*!
44374@brief Remove the last (bottom) row.
44375
44376
44377*/
44378void removeRow();
44379/*!
44380@brief Get the number of columns.
44381
44382
44383@return The number of columns
44384*/
44385int getColumnCount();
44386/*!
44387@brief Get the number of rows.
44388
44389
44390@return The number of rows
44391*/
44392int getRowCount();
44393/*!
44394@brief Get the horizontal offset of a column.
44395
44396
44397@param index Index of the column to query
44398@return Column offset in pixels
44399*/
44400int getColumnOffset( int index );
44401/*!
44402@brief Get the vertical offset of a row.
44403
44404
44405@param index Index of the row to query
44406@return Row offset in pixels
44407*/
44408int getRowOffset( int index );
44409/*!
44410@brief Set the horizontal offset of a column.
44411
44412
44413Note that column offsets must always be in increasing order, and therefore this offset must be between the offsets of the colunns either side.
44414@param index  Index of the column to modify
44415@param offset New column offset
44416*/
44417void setColumnOffset( int index, int offset );
44418/*!
44419@brief Set the vertical offset of a row.
44420
44421
44422Note that row offsets must always be in increasing order, and therefore this offset must be between the offsets of the rows either side.
44423@param index  Index of the row to modify
44424@param offset New row offset
44425*/
44426void setRowOffset( int index, int offset );
44427/*!
44428@brief Recalculates child control sizes.
44429
44430*/
44431void updateSizes();
44432
44433/*! @name Callbacks
44434@{ */
44435/// @}
44436
44437/*!
44438@brief A vector of column offsets (determines the width of each column).
44439*/
44440intList columns;
44441/*!
44442@brief A vector of row offsets (determines the height of each row).
44443*/
44444intList rows;
44445/*!
44446@brief Width of interior borders between cells in pixels.
44447*/
44448int borderWidth;
44449/*!
44450@brief Color of interior borders between cells.
44451*/
44452ColorI borderColor;
44453/*!
44454@brief Controls whether frame borders are enabled.
44455
44456
44457Frames use this value unless overridden for that frame using <i>%ctrl.frameBorder(index)</i>
44458*/
44459GuiFrameState borderEnable;
44460/*!
44461@brief Controls whether borders can be dynamically repositioned with the mouse by the user.
44462
44463
44464Frames use this value unless overridden for that frame using <i>%ctrl.frameMovable(index)</i>
44465*/
44466GuiFrameState borderMovable;
44467/*!
44468@brief If true, row and column offsets are automatically scaled to match the new extents when the control is resized.
44469*/
44470bool autoBalance;
44471/*!
44472@brief Offset for row and column dividers in pixels
44473*/
44474int fudgeFactor;
44475
44476/*! @name Layout
44477@{ */
44478/// @}
44479
44480
44481/*! @name Layout
44482@{ */
44483/// @}
44484
44485
44486/*! @name Control
44487@{ */
44488/// @}
44489
44490
44491/*! @name ToolTip
44492@{ */
44493/// @}
44494
44495
44496/*! @name Editing
44497@{ */
44498/// @}
44499
44500
44501/*! @name Localization
44502@{ */
44503/// @}
44504
44505
44506/*! @name Ungrouped
44507@{ */
44508/// @}
44509
44510
44511/*! @name Object
44512@{ */
44513/// @}
44514
44515
44516/*! @name Editing
44517@{ */
44518/// @}
44519
44520
44521/*! @name Persistence
44522@{ */
44523/// @}
44524
44525};
44526
44527/*!
44528@brief A collapsable pane control.
44529
44530This class wraps a single child control and displays a header with caption above it. If you click the header it will collapse or expand (if <i>collapsable</i> is enabled). The control resizes itself based on its collapsed/expanded size.<br>In the GUI editor, if you just want the header you can make <i>collapsable</i> false. The caption field lets you set the caption; it expects a bitmap (from the GuiControlProfile) that contains two images - the first is displayed when the control is expanded and the second is displayed when it is collapsed. The header is sized based on the first image.
44531
44532@tsexample
44533new GuiPaneControl()
44534{
44535   caption = "Example Pane";
44536   collapsable = "1";
44537   barBehindText = "1";
44538   //Properties not specific to this control have been omitted from this example.
44539};
44540@endtsexample
44541
44542@ingroup GuiContainers
44543*/
44544class GuiPaneControl : public GuiControl {
44545public:
44546/*!
44547@brief Collapse or un-collapse the control.
44548
44549
44550@param collapse True to collapse the control, false to un-collapse it
44551*/
44552void setCollapsed( bool collapse );
44553
44554/*! @name Callbacks
44555@{ */
44556/// @}
44557
44558
44559/*! @name Pane
44560@{ */
44561/*!
44562@brief Text label to display as the pane header.
44563*/
44564string caption;
44565/*!
44566@brief String table text ID to use as caption string (overrides 'caption').
44567*/
44568string captionID;
44569/*!
44570@brief Whether the pane can be collapsed by clicking its header.
44571*/
44572bool collapsable;
44573/*!
44574@brief Whether to draw the bitmapped pane bar behind the header text, too.
44575*/
44576bool barBehindText;
44577/// @}
44578
44579
44580/*! @name Layout
44581@{ */
44582/// @}
44583
44584
44585/*! @name Control
44586@{ */
44587/// @}
44588
44589
44590/*! @name ToolTip
44591@{ */
44592/// @}
44593
44594
44595/*! @name Editing
44596@{ */
44597/// @}
44598
44599
44600/*! @name Localization
44601@{ */
44602/// @}
44603
44604
44605/*! @name Ungrouped
44606@{ */
44607/// @}
44608
44609
44610/*! @name Object
44611@{ */
44612/// @}
44613
44614
44615/*! @name Editing
44616@{ */
44617/// @}
44618
44619
44620/*! @name Persistence
44621@{ */
44622/// @}
44623
44624};
44625
44626/*!
44627@brief A container that splits its area between two child controls.
44628
44629A GuiSplitContainer can be used to dynamically subdivide an area between two child controls.  A splitter bar is placed between the two controls and allows to dynamically adjust the sizing ratio between the two sides.  Splitting can be either horizontal (subdividing top and bottom) or vertical (subdividing left and right) depending on #orientation.
44630
44631By using #fixedPanel, one of the panels can be chosen to remain at a fixed size (#fixedSize).@tsexample
44632// Create a vertical splitter with a fixed-size left panel.
44633%splitter = new GuiSplitContainer()
44634{
44635   orientation = "Vertical";
44636   fixedPanel = "FirstPanel";
44637   fixedSize = 100;
44638
44639   new GuiScrollCtrl()
44640   {
44641      new GuiMLTextCtrl()
44642      {
44643         text = %longText;
44644      };
44645   };
44646
44647   new GuiScrollCtrl()
44648   {
44649      new GuiMLTextCtrl()
44650      {
44651         text = %moreLongText;
44652      };
44653   };
44654};
44655@endtsexample
44656
44657@note The children placed inside GuiSplitContainers must be GuiContainers.
44658
44659@ingroup GuiContainers
44660*/
44661class GuiSplitContainer : public GuiContainer {
44662public:
44663/*!
44664@brief Set the position of the split handle.
44665
44666*/
44667void setSplitPoint( Point2I splitPoint );
44668
44669/*! @name Callbacks
44670@{ */
44671/// @}
44672
44673
44674/*! @name Splitter
44675Options to configure split panels contained by this control
44676@{ */
44677/*!
44678@brief Whether to split between top and bottom (horizontal) or between left and right (vertical).
44679*/
44680GuiSplitOrientation orientation;
44681/*!
44682@brief Width of the splitter bar between the two sides.  Default is 2.
44683*/
44684int splitterSize;
44685/*!
44686@brief Point on control through which the splitter goes.
44687
44688
44689Changed relatively if size of control changes.
44690*/
44691Point2I splitPoint;
44692/*!
44693@brief Which (if any) side of the splitter to keep at a fixed size.
44694*/
44695GuiSplitFixedPanel fixedPanel;
44696/*!
44697@brief Width of the fixed panel specified by #fixedPanel (if any).
44698*/
44699int fixedSize;
44700/// @}
44701
44702
44703/*! @name Layout
44704@{ */
44705/// @}
44706
44707
44708/*! @name Layout
44709@{ */
44710/// @}
44711
44712
44713/*! @name Control
44714@{ */
44715/// @}
44716
44717
44718/*! @name ToolTip
44719@{ */
44720/// @}
44721
44722
44723/*! @name Editing
44724@{ */
44725/// @}
44726
44727
44728/*! @name Localization
44729@{ */
44730/// @}
44731
44732
44733/*! @name Ungrouped
44734@{ */
44735/// @}
44736
44737
44738/*! @name Object
44739@{ */
44740/// @}
44741
44742
44743/*! @name Editing
44744@{ */
44745/// @}
44746
44747
44748/*! @name Persistence
44749@{ */
44750/// @}
44751
44752};
44753
44754/*!
44755@brief A container that stacks its children horizontally or vertically.
44756
44757This container maintains a horizontal or vertical stack of GUI controls. If one is added, deleted, or resized, then the stack is resized to fit. The order of the stack is determined by the internal order of the children (ie. the order of addition).<br>@tsexample
44758new GuiStackControl()
44759{
44760   stackingType = "Dynamic";
44761   horizStacking = "Left to Right";
44762   vertStacking = "Top to Bottom";
44763   padding = "4";
44764   dynamicSize = "1";
44765   dynamicNonStackExtent = "0";
44766   dynamicPos = "0";
44767   changeChildSizeToFit = "1";
44768   changeChildPosition = "1";
44769   //Properties not specific to this control have been omitted from this example.
44770};
44771@endtsexample
44772
44773@ingroup GuiContainers
44774*/
44775class GuiStackControl : public GuiControl {
44776public:
44777/*!
44778@brief Return whether or not this control is frozen
44779
44780*/
44781bool isFrozen();
44782/*!
44783@brief Prevents control from restacking - useful when adding or removing child controls
44784
44785@param freeze True to freeze the control, false to unfreeze it
44786
44787@tsexample
44788%stackCtrl.freeze(true);
44789// add controls to stack
44790%stackCtrl.freeze(false);
44791@endtsexample
44792*/
44793void freeze( bool freeze );
44794/*!
44795@brief Restack the child controls.
44796
44797*/
44798void updateStack();
44799
44800/*! @name Callbacks
44801@{ */
44802/// @}
44803
44804
44805/*! @name Stacking
44806@{ */
44807/*!
44808@brief Determines the method used to position the child controls.
44809
44810
44811
44812*/
44813GuiStackingType stackingType;
44814/*!
44815@brief Controls the type of horizontal stacking to use (<i>Left to Right</i> or <i>Right to Left</i>)
44816*/
44817GuiHorizontalStackingType horizStacking;
44818/*!
44819@brief Controls the type of vertical stacking to use (<i>Top to Bottom</i> or <i>Bottom to Top</i>)
44820*/
44821GuiVerticalStackingType vertStacking;
44822/*!
44823@brief Distance (in pixels) between stacked child controls.
44824*/
44825int padding;
44826/*!
44827@brief Determines whether to resize the stack control along the stack axis (change width for horizontal stacking, change height for vertical stacking).
44828
44829
44830If true, the stack width/height will be resized to the sum of the child control widths/heights. If false, the stack will not be resized.
44831*/
44832bool dynamicSize;
44833/*!
44834@brief Determines whether to resize the stack control along the non-stack axis (change height for horizontal stacking, change width for vertical stacking). No effect if dynamicSize is false.
44835
44836
44837If true, the stack will be resized to the maximum of the child control widths/heights. If false, the stack will not be resized.
44838*/
44839bool dynamicNonStackExtent;
44840/*!
44841@brief Determines whether to reposition the stack along the stack axis when it is auto-resized. No effect if dynamicSize is false.
44842
44843
44844If true, the stack will grow left for horizontal stacking, and grow up for vertical stacking.
44845If false, the stack will grow right for horizontal stacking, and grow down for vertical stacking.
44846
44847*/
44848bool dynamicPos;
44849/*!
44850@brief Determines whether to resize child controls.
44851
44852
44853If true, horizontally stacked children keep their width, but have their height set to the stack control height. Vertically stacked children keep their height, but have their width set to the stack control width. If false, child controls are not resized.
44854*/
44855bool changeChildSizeToFit;
44856/*!
44857@brief Determines whether to reposition child controls.
44858
44859
44860If true, horizontally stacked children are aligned along the top edge of the stack control. Vertically stacked children are aligned along the left edge of the stack control. If false, horizontally stacked children retain their Y position, and vertically stacked children retain their X position.
44861*/
44862bool changeChildPosition;
44863/// @}
44864
44865
44866/*! @name Layout
44867@{ */
44868/// @}
44869
44870
44871/*! @name Control
44872@{ */
44873/// @}
44874
44875
44876/*! @name ToolTip
44877@{ */
44878/// @}
44879
44880
44881/*! @name Editing
44882@{ */
44883/// @}
44884
44885
44886/*! @name Localization
44887@{ */
44888/// @}
44889
44890
44891/*! @name Ungrouped
44892@{ */
44893/// @}
44894
44895
44896/*! @name Object
44897@{ */
44898/// @}
44899
44900
44901/*! @name Editing
44902@{ */
44903/// @}
44904
44905
44906/*! @name Persistence
44907@{ */
44908/// @}
44909
44910};
44911
44912/*!
44913@brief A container 
44914
44915@tsexample
44916// Create 
44917@endtsexample
44918
44919@note Only GuiTabPageCtrls must be added to GuiTabBookCtrls.  If an object of a different class is added to the control, it will be reassigned to either the active page or the tab book's parent.
44920
44921@see GuiTabPageCtrl
44922@ingroup GuiContainers
44923*/
44924class GuiTabBookCtrl : public GuiContainer {
44925public:
44926/*!
44927@brief Add a new tab page to the control.
44928
44929
44930@param title Title text for the tab page header.*/
44931void addPage( string title="" );
44932/*!
44933@brief Set the selected tab page.
44934
44935
44936@param index Index of the tab page.*/
44937void selectPage( int index );
44938/*!
44939@brief Get the index of the currently selected tab page.
44940
44941
44942@return Index of the selected tab page or -1 if no tab page is selected.*/
44943int getSelectedPage();
44944
44945/*! @name Callbacks
44946@{ */
44947/*!
44948@brief Called when a new tab page is selected.
44949
44950
44951@param text Text of the page header for the tab that is being selected.
44952@param index Index of the tab page being selected.*/
44953void onTabSelected( String text, uint index );
44954/*!
44955@brief Called when the user right-clicks on a tab page header.
44956
44957
44958@param text Text of the page header for the tab that is being selected.
44959@param index Index of the tab page being selected.*/
44960void onTabRightClick( String text, uint index );
44961/// @}
44962
44963
44964/*! @name TabBook
44965@{ */
44966/*!
44967@brief Where to place the tab page headers.
44968*/
44969GuiTabPosition tabPosition;
44970/*!
44971@brief Spacing to put between individual tab page headers.
44972*/
44973int tabMargin;
44974/*!
44975@brief Minimum width allocated to a tab page header.
44976*/
44977int minTabWidth;
44978/*!
44979@brief Height of tab page headers.
44980*/
44981int tabHeight;
44982/*!
44983@brief Whether reordering tabs with the mouse is allowed.
44984*/
44985bool allowReorder;
44986/*!
44987@brief Index of page to select on first onWake() call (-1 to disable).
44988*/
44989int defaultPage;
44990/*!
44991@brief Index of currently selected page.
44992*/
44993int selectedPage;
44994/*!
44995@brief X offset of first tab page header.
44996*/
44997int frontTabPadding;
44998/// @}
44999
45000
45001/*! @name Layout
45002@{ */
45003/// @}
45004
45005
45006/*! @name Layout
45007@{ */
45008/// @}
45009
45010
45011/*! @name Control
45012@{ */
45013/// @}
45014
45015
45016/*! @name ToolTip
45017@{ */
45018/// @}
45019
45020
45021/*! @name Editing
45022@{ */
45023/// @}
45024
45025
45026/*! @name Localization
45027@{ */
45028/// @}
45029
45030
45031/*! @name Ungrouped
45032@{ */
45033/// @}
45034
45035
45036/*! @name Object
45037@{ */
45038/// @}
45039
45040
45041/*! @name Editing
45042@{ */
45043/// @}
45044
45045
45046/*! @name Persistence
45047@{ */
45048/// @}
45049
45050};
45051
45052/*! UNDOCUMENTED!
45053@ingroup UNDOCUMENTED
45054 */
45055class Gui3DProjectionCtrl : public GuiControl {
45056public:
45057void setAttachedTo( SceneObject target=nullAsType<SceneObject*>() );
45058int getAttachedTo();
45059
45060/*! @name Callbacks
45061@{ */
45062/// @}
45063
45064
45065/*! @name Layout
45066@{ */
45067/// @}
45068
45069
45070/*! @name Control
45071@{ */
45072/// @}
45073
45074
45075/*! @name ToolTip
45076@{ */
45077/// @}
45078
45079
45080/*! @name Editing
45081@{ */
45082/// @}
45083
45084
45085/*! @name Localization
45086@{ */
45087/// @}
45088
45089
45090/*! @name Ungrouped
45091@{ */
45092/// @}
45093
45094
45095/*! @name Object
45096@{ */
45097/// @}
45098
45099
45100/*! @name Editing
45101@{ */
45102/// @}
45103
45104
45105/*! @name Persistence
45106@{ */
45107/// @}
45108
45109
45110/*! @name 3DProjection
45111@{ */
45112/*!
45113*/
45114Point3F pointWorld;
45115/*!
45116*/
45117Point3F offsetObject;
45118/*!
45119*/
45120Point3F offsetWorld;
45121/*!
45122*/
45123Point2I offsetScreen;
45124/*!
45125*/
45126int hAlign;
45127/*!
45128*/
45129int vAlign;
45130/*!
45131*/
45132Point2I useEyePoint;
45133/*!
45134*/
45135bool autoDelete;
45136/// @}
45137
45138};
45139
45140/*! UNDOCUMENTED!
45141@ingroup UNDOCUMENTED
45142 */
45143class guiAnimBitmapCtrl : public GuiBitmapCtrl {
45144public:
45145
45146/*! @name Callbacks
45147@{ */
45148/*!
45149@brief triggered when a loop completes
45150
45151*/
45152void onLoop();
45153/*!
45154@brief triggered when an animation completes
45155
45156*/
45157void onCompleted();
45158/*!
45159@brief triggered when a frame increments
45160
45161*/
45162void onFrame( int frameIndex, int frame );
45163/// @}
45164
45165/*!
45166@brief @brief The number of frames, in rows and columns stored in textureName (when animateTexture is true).
45167
45168
45169A maximum of 256 frames can be stored in a single texture when using mAnimTexTiling. Value should be "NumColumns NumRows", for example "4 4".
45170*/
45171Point2I animTexTiling;
45172/*!
45173@brief @brief A list of frames and/or frame ranges to use for particle animation if animateTexture is true.
45174
45175
45176Each frame token must be separated by whitespace. A frame token must be a positive integer frame number or a range of frame numbers separated with a '-'. The range separator, '-', cannot have any whitspace around it.
45177
45178Ranges can be specified to move through the frames in reverse as well as forward (eg. 19-14). Frame numbers exceeding the number of tiles will wrap.
45179@tsexample
45180mAnimTexFrames = "0-16 20 19 18 17 31-21";
45181@endtsexample
45182
45183*/
45184string animTexFrames;
45185/*!
45186@brief loop?
45187*/
45188bool Loop;
45189/*!
45190@brief play?
45191*/
45192bool play;
45193/*!
45194@brief play reversed?
45195*/
45196bool reverse;
45197/*!
45198@brief Frame Rate
45199*/
45200int fps;
45201/*!
45202@brief Index of currently Displaying Frame 
45203*/
45204int curFrame;
45205
45206/*! @name Bitmap
45207@{ */
45208/// @}
45209
45210
45211/*! @name Layout
45212@{ */
45213/// @}
45214
45215
45216/*! @name Control
45217@{ */
45218/// @}
45219
45220
45221/*! @name ToolTip
45222@{ */
45223/// @}
45224
45225
45226/*! @name Editing
45227@{ */
45228/// @}
45229
45230
45231/*! @name Localization
45232@{ */
45233/// @}
45234
45235
45236/*! @name Ungrouped
45237@{ */
45238/// @}
45239
45240
45241/*! @name Object
45242@{ */
45243/// @}
45244
45245
45246/*! @name Editing
45247@{ */
45248/// @}
45249
45250
45251/*! @name Persistence
45252@{ */
45253/// @}
45254
45255};
45256
45257/*!
45258@brief The on-screen, in-game console. Calls getLog() to get the on-screen console entries, then renders them as needed.
45259
45260@tsexample
45261   new GuiConsole()
45262      {
45263         //Properties not specific to this control have been omitted from this example.
45264      };
45265@endtsexample
45266
45267@see GuiControl
45268
45269@ingroup GuiCore
45270*/
45271class GuiConsole : public GuiArrayCtrl {
45272public:
45273/*!
45274@brief Sets the current display filters for the console gui. Allows you to indicate if it should display errors, warns and/or normal messages.
45275
45276
45277@param errors If true, the console gui will display any error messages that were emitted.
45278
45279@param warns If true, the console gui will display any warning messages that were emitted.
45280
45281@param normal If true, the console gui will display any regular messages that were emitted.
45282
45283*/
45284void setDisplayFilters( bool errors=true, bool warns=true, bool normal=true );
45285/*!
45286@brief Returns if the error filter is on or not.
45287
45288*/
45289bool getErrorFilter();
45290/*!
45291@brief Returns if the warning filter is on or not.
45292
45293*/
45294bool getWarnFilter();
45295/*!
45296@brief Returns if the normal message filter is on or not.
45297
45298*/
45299bool getNormalFilter();
45300/*!
45301@brief Toggles the error filter.
45302
45303*/
45304void toggleErrorFilter();
45305/*!
45306@brief Toggles the warning filter.
45307
45308*/
45309void toggleWarnFilter();
45310/*!
45311@brief Toggles the normal messages filter.
45312
45313*/
45314void toggleNormalFilter();
45315/*!
45316@brief Refreshes the displayed messages.
45317
45318*/
45319void refresh();
45320
45321/*! @name Callbacks
45322@{ */
45323/*!
45324@brief Called when a message in the log is clicked.
45325
45326
45327@param level Diagnostic level of the message.
45328@param message Message text.
45329*/
45330void onMessageSelected( ConsoleLogEntry::Level level, string message );
45331/*!
45332@brief Called when a new message is logged.
45333
45334
45335@param errorCount The number of error messages logged.
45336@param warnCount The number of warning messages logged.
45337@param normalCount The number of normal messages logged.
45338*/
45339void onNewMessage( uint errorCount, uint warnCount, uint normalCount );
45340/// @}
45341
45342
45343/*! @name Layout
45344@{ */
45345/// @}
45346
45347
45348/*! @name Control
45349@{ */
45350/// @}
45351
45352
45353/*! @name ToolTip
45354@{ */
45355/// @}
45356
45357
45358/*! @name Editing
45359@{ */
45360/// @}
45361
45362
45363/*! @name Localization
45364@{ */
45365/// @}
45366
45367
45368/*! @name Ungrouped
45369@{ */
45370/// @}
45371
45372
45373/*! @name Object
45374@{ */
45375/// @}
45376
45377
45378/*! @name Editing
45379@{ */
45380/// @}
45381
45382
45383/*! @name Persistence
45384@{ */
45385/// @}
45386
45387};
45388
45389/*!
45390@brief A list of text items.
45391
45392A list of text items where each individual entry can have its own text value, text color and associated SimObject.
45393
45394@tsexample
45395new GuiListBoxCtrl(GuiMusicPlayerMusicList)
45396{
45397   allowMultipleSelections = "true";
45398   fitParentWidth = "true";
45399   mirrorSet = "AnotherGuiListBoxCtrl";
45400   makeNameCallback = "";
45401   colorBullet = "1";
45402   //Properties not specific to this control have been omitted from this example.
45403};
45404@endtsexample
45405
45406@see GuiControl
45407
45408@ingroup GuiCore
45409
45410*/
45411class GuiListBoxCtrl : public GuiControl {
45412public:
45413/*!
45414@brief Enable or disable multiple selections for this GuiListBoxCtrl object.
45415
45416@param allowMultSelections Boolean variable to set the use of multiple selections or not.
45417@tsexample
45418// Define the multiple selection use state.
45419%allowMultSelections = "true";
45420
45421// Set the allow  multiple selection state on the GuiListBoxCtrl object.
45422%thisGuiListBoxCtrl.setMultipleSelection(%allowMultSelections);
45423@endtsexample
45424
45425@see GuiControl*/
45426void setMultipleSelection( bool allowMultSelections );
45427/*!
45428@brief Clears all the items in the listbox.
45429
45430@tsexample
45431// Inform the GuiListBoxCtrl object to clear all items from its list.
45432%thisGuiListBoxCtrl.clearItems();
45433@endtsexample
45434
45435@see GuiControl*/
45436void clearItems();
45437/*!
45438@brief Sets all currently selected items to unselected.
45439
45440Detailed description
45441
45442@tsexample
45443// Inform the GuiListBoxCtrl object to set all of its items to unselected./n%thisGuiListBoxCtrl.clearSelection();
45444@endtsexample
45445
45446@see GuiControl*/
45447void clearSelection();
45448/*!
45449@brief Sets the item at the index specified to selected or not.
45450
45451Detailed description
45452
45453@param index Item index to set selected or unselected.
45454@param setSelected Boolean selection state to set the requested item index.
45455@tsexample
45456// Define the index
45457%index = "5";
45458
45459// Define the selection state
45460%selected = "true"
45461
45462// Inform the GuiListBoxCtrl object of the new selection state for the requested index entry.
45463%thisGuiListBoxCtrl.setSelected(%index,%selected);
45464@endtsexample
45465
45466@see GuiControl*/
45467void setSelected( int index, bool setSelected=true );
45468/*!
45469@brief Returns the number of items in the list.
45470
45471@tsexample
45472// Request the number of items in the list of the GuiListBoxCtrl object.
45473%listItemCount = %thisGuiListBoxCtrl.getItemCount();
45474@endtsexample
45475
45476@return The number of items in the list.
45477
45478@see GuiControl*/
45479int getItemCount();
45480/*!
45481@brief Returns the number of items currently selected.
45482
45483@tsexample
45484// Request the number of currently selected items
45485%selectedItemCount = %thisGuiListBoxCtrl.getSelCount();
45486@endtsexample
45487
45488@return Number of currently selected items.
45489
45490@see GuiControl*/
45491int getSelCount();
45492/*!
45493@brief Returns the selected items index or -1 if none selected. If multiple selections exist it returns the first selected item. 
45494
45495@tsexample
45496// Request the index id of the currently selected item
45497%selectedItemId = %thisGuiListBoxCtrl.getSelectedItem();
45498@endtsexample
45499
45500@return The selected items index or -1 if none selected.
45501
45502@see GuiControl*/
45503int getSelectedItem();
45504/*!
45505@brief Returns a space delimited list of the selected items indexes in the list.
45506
45507@tsexample
45508// Request a space delimited list of the items in the GuiListBoxCtrl object.
45509%selectionList = %thisGuiListBoxCtrl.getSelectedItems();
45510@endtsexample
45511
45512@return Space delimited list of the selected items indexes in the list
45513
45514@see GuiControl*/
45515string getSelectedItems();
45516/*!
45517@brief Returns index of item with matching text or -1 if none found.
45518
45519@param findText Text in the list to find.
45520@param isCaseSensitive If true, the search will be case sensitive.
45521@tsexample
45522// Define the text we wish to find in the list.
45523%findText = "Hickory Smoked Gideon"/n/n// Define if this is a case sensitive search or not.
45524%isCaseSensitive = "false";
45525
45526// Ask the GuiListBoxCtrl object what item id in the list matches the requested text.
45527%matchingId = %thisGuiListBoxCtrl.findItemText(%findText,%isCaseSensitive);
45528@endtsexample
45529
45530@return Index id of item with matching text or -1 if none found.
45531
45532@see GuiControl*/
45533int findItemText( string findText, bool bCaseSensitive=false );
45534/*!
45535@brief Sets the currently selected item at the specified index.
45536
45537@param indexId Index Id to set selected.
45538@tsexample
45539// Define the index id that we wish to select.
45540%selectId = "4";
45541
45542// Inform the GuiListBoxCtrl object to set the requested index as selected.
45543%thisGuiListBoxCtrl.setCurSel(%selectId);
45544@endtsexample
45545
45546@see GuiControl*/
45547void setCurSel( int indexId );
45548/*!
45549@brief Sets the current selection range from index start to stop. If no stop is specified it sets from start index to the end of the list
45550
45551@param indexStart Index Id to start selection.
45552@param indexStop Index Id to end selection.
45553@tsexample
45554// Set start id
45555%indexStart = "3";
45556
45557// Set end id
45558%indexEnd = "6";
45559
45560// Request the GuiListBoxCtrl object to select the defined range.
45561%thisGuiListBoxCtrl.setCurSelRange(%indexStart,%indexEnd);
45562@endtsexample
45563
45564@see GuiControl*/
45565void setCurSelRange( int indexStart, int indexStop=999999 );
45566/*!
45567@brief Sets the color of a single list entry at the specified index id.
45568
45569@param index Index id to modify the color of in the list.
45570@param color Color value to set the list entry to.
45571@tsexample
45572// Define the index id value
45573%index = "5";
45574
45575// Define the color value
45576%color = "1.0 0.0 0.0";
45577
45578// Inform the GuiListBoxCtrl object to change the color of the requested index
45579%thisGuiListBoxCtrl.setItemColor(%index,%color);
45580@endtsexample
45581
45582@see GuiControl*/
45583void setItemColor( int index, LinearColorF color );
45584/*!
45585@brief Removes any custom coloring from an item at the defined index id in the list.
45586
45587@param index Index id for the item to clear any custom color from.
45588@tsexample
45589// Define the index id
45590%index = "4";
45591
45592// Request the GuiListBoxCtrl object to remove any custom coloring from the defined index entry
45593%thisGuiListBoxCtrl.clearItemColor(%index);
45594@endtsexample
45595
45596@see GuiControl*/
45597void clearItemColor( int index );
45598/*!
45599@brief Inserts an item into the list at the specified index and returns the index assigned or -1 on error.
45600
45601@param text Text item to add.
45602@param index Index id to insert the list item text at.
45603@tsexample
45604// Define the text to insert
45605%text = "Secret Agent Gideon";
45606
45607// Define the index entry to insert the text at
45608%index = "14";
45609
45610// In form the GuiListBoxCtrl object to insert the text at the defined index.
45611%assignedId = %thisGuiListBoxCtrl.insertItem(%text,%index);
45612@endtsexample
45613
45614@return If successful will return the index id assigned. If unsuccessful, will return -1.
45615
45616@see GuiControl*/
45617void insertItem( string text, int index );
45618/*!
45619@brief Removes the list entry at the requested index id from the control and clears the memory associated with it.
45620
45621@param itemIndex Index id location to remove the item from.
45622@tsexample
45623// Define the index id we want to remove from the list
45624%itemIndex = "8";
45625
45626// Inform the GuiListBoxCtrl object to remove the item at the defined index id.
45627%thisGuiListBoxCtrl.deleteItem(%itemIndex);
45628@endtsexample
45629
45630@see References*/
45631void deleteItem( int itemIndex );
45632/*!
45633@brief Returns the text of the item at the specified index.
45634
45635@param index Index id to return the item text from.
45636@tsexample
45637// Define the index id entry to request the text from
45638%index = "12";
45639
45640// Request the item id text from the GuiListBoxCtrl object.
45641%text = %thisGuiListBoxCtrl.getItemText(%index);
45642@endtsexample
45643
45644@return The text of the requested index id.
45645
45646@see GuiControl*/
45647string getItemText( int index );
45648/*!
45649@brief Returns the object associated with an item. This only makes sense if you are mirroring a simset.
45650
45651@param index Index id to request the associated item from.
45652@tsexample
45653// Define the index id
45654%index = "12";
45655
45656// Request the item from the GuiListBoxCtrl object
45657%object = %thisGuiListBoxCtrl.getItemObject(%index);
45658@endtsexample
45659
45660@return The object associated with the item in the list.
45661
45662@see References*/
45663string getItemObject( int index );
45664/*!
45665@brief Sets the items text at the specified index.
45666
45667@param index Index id to set the item text at.
45668@param newtext Text to change the list item at index id to.
45669@tsexample
45670// Define the index id/n%index = "12";
45671
45672// Define the text to set the list item to
45673%newtext = "Gideon's Fancy Goggles";
45674
45675// Inform the GuiListBoxCtrl object to change the text at the requested index
45676%thisGuiListBoxCtrl.setItemText(%index,%newText);
45677@endtsexample
45678
45679@see GuiControl*/
45680void setItemText( int index, string newtext );
45681/*!
45682@brief Set the tooltip text to display for the given list item.
45683
45684@param index Index id to change the tooltip text
45685@param text Text for the tooltip.
45686@tsexample
45687// Define the index id
45688%index = "12";
45689
45690// Define the tooltip text
45691%tooltip = "Gideon's goggles can see through space and time."
45692
45693// Inform the GuiListBoxCtrl object to set the tooltop for the item at the defined index id
45694%thisGuiListBoxCtrl.setItemToolTip(%index,%tooltip);
45695@endtsexample
45696
45697@see GuiControl*/
45698void setItemTooltip( int index, string text );
45699/*!
45700@brief Request the item index for the item that was last clicked.
45701
45702@tsexample
45703// Request the item index for the last clicked item in the list
45704%lastClickedIndex = %thisGuiListBoxCtrl.getLastClickItem();
45705@endtsexample
45706
45707@return Index id for the last clicked item in the list.
45708
45709@see GuiControl*/
45710int getLastClickItem();
45711/*!
45712@brief Informs the GuiListBoxCtrl object to mirror the contents of the GuiListBoxCtrl stored in the mirrorSet field.
45713
45714@tsexample
45715\ Inform the object to mirror the object located at %thisGuiListBox.mirrorSet
45716%thisGuiListBox.doMirror();
45717@endtsexample
45718
45719@see GuiCore*/
45720void doMirror();
45721/*!
45722@brief Checks if there is an item with the exact text of what is passed in, and if so
45723the item is removed from the list and adds that item's data to the filtered list.
45724
45725@param itemName Name of the item that we wish to add to the filtered item list of the GuiListBoxCtrl.
45726@tsexample
45727// Define the itemName that we wish to add to the filtered item list.
45728%itemName = "This Item Name";
45729
45730// Add the item name to the filtered item list.
45731%thisGuiListBoxCtrl.addFilteredItem(%filteredItemName);
45732@endtsexample
45733
45734@see GuiControl*/
45735void addFilteredItem( string newItem );
45736/*!
45737@brief Removes an item of the entered name from the filtered items list.
45738
45739@param itemName Name of the item to remove from the filtered list.
45740@tsexample
45741// Define the itemName that you wish to remove.
45742%itemName = "This Item Name";
45743
45744// Remove the itemName from the GuiListBoxCtrl
45745%thisGuiListBoxCtrl.removeFilteredItem(%itemName);
45746@endtsexample
45747
45748@see GuiControl*/
45749void removeFilteredItem( string itemName );
45750
45751/*! @name Callbacks
45752@{ */
45753/*!
45754@brief Called whenever the mouse is dragged across the control.
45755
45756@tsexample
45757// Mouse is dragged across the control, causing the callback to occur.
45758GuiListBoxCtrl::onMouseDragged(%this)
45759  {
45760     // Code to run whenever the mouse is dragged across the control
45761  }
45762@endtsexample
45763
45764@see GuiControl*/
45765void onMouseDragged();
45766/*!
45767@brief Called whenever a selected item in the list is cleared.
45768
45769@tsexample
45770// A selected item is cleared, causing the callback to occur.
45771GuiListBoxCtrl::onClearSelection(%this)
45772  {
45773     // Code to run whenever a selected item is cleared
45774  }
45775@endtsexample
45776
45777@see GuiControl*/
45778void onClearSelection();
45779/*!
45780@brief Called whenever a selected item in the list has been unselected.
45781
45782@param index Index id of the item that was unselected
45783@param itemText Text for the list entry at the index id that was unselected
45784
45785@tsexample
45786// A selected item is unselected, causing the callback to occur
45787GuiListBoxCtrl::onUnSelect(%this, %indexId, %itemText)
45788  {
45789     // Code to run whenever a selected list item is unselected
45790  }
45791@endtsexample
45792
45793@see GuiControl*/
45794void onUnselect( int index, string itemText );
45795/*!
45796@brief Called whenever an item in the list is selected.
45797
45798@param index Index id for the item in the list that was selected.
45799@param itemText Text for the list item at the index that was selected.
45800
45801@tsexample
45802// An item in the list is selected, causing the callback to occur
45803GuiListBoxCtrl::onSelect(%this, %index, %itemText)
45804  {
45805     // Code to run whenever an item in the list is selected
45806  }
45807@endtsexample
45808
45809@see GuiControl*/
45810void onSelect( int index, string itemText );
45811/*!
45812@brief Called whenever an item in the list has been double clicked.
45813
45814@tsexample
45815// An item in the list is double clicked, causing the callback to occur.
45816GuiListBoxCtrl::onDoubleClick(%this)
45817  {
45818     // Code to run whenever an item in the control has been double clicked
45819  }
45820@endtsexample
45821
45822@see GuiControl*/
45823void onDoubleClick();
45824/*!
45825@brief Called whenever the mouse has previously been clicked down (onMouseDown) and has now been raised on the control.
45826If an item in the list was hit during the click cycle, then the index id of the clicked object along with how many clicks occured are passed
45827into the callback.
45828
45829Detailed description
45830
45831@param itemHit Index id for the list item that was hit
45832@param mouseClickCount How many mouse clicks occured on this list item
45833
45834@tsexample
45835// Mouse was previously clicked down, and now has been released, causing the callback to occur.
45836GuiListBoxCtrl::onMouseUp(%this, %itemHit, %mouseClickCount)
45837  {
45838     // Code to call whenever the mouse has been clicked and released on the control
45839  }
45840@endtsexample
45841
45842@see GuiControl*/
45843void onMouseUp( int itemHit, int mouseClickCount );
45844/*!
45845@brief Called whenever the Delete key on the keyboard has been pressed while in this control.
45846
45847@tsexample
45848// The delete key on the keyboard has been pressed while this control is in focus, causing the callback to occur.
45849GuiListBoxCtrl::onDeleteKey(%this)
45850  {
45851     // Code to call whenever the delete key is pressed
45852  }
45853@endtsexample
45854
45855@see GuiControl*/
45856void onDeleteKey();
45857/*!
45858@brief Checks if a list item at a defined index id is mirrored, and returns the result.
45859
45860@param indexIdString Index id of the list to check.
45861@tsexample
45862// Engine has requested of the script level to determine if a list entry is mirrored or not.
45863GuiListBoxCtrl::isObjectMirrored(%this, %indexIdString)
45864  {
45865     // Perform code required to check and see if the list item at the index id is mirrored or not.
45866     return %isMirrored;
45867  }
45868@endtsexample
45869
45870@return A boolean value on if the list item is mirrored or not.
45871
45872@see GuiControl*/
45873bool isObjectMirrored( string indexIdString );
45874/// @}
45875
45876/*!
45877@brief If true, will allow the selection of multiple items in the listbox.
45878
45879
45880*/
45881bool allowMultipleSelections;
45882/*!
45883@brief If true, the width of the listbox will match the width of its parent control.
45884
45885
45886*/
45887bool fitParentWidth;
45888/*!
45889@brief If true, colored items will render a colored rectangular bullet next to the item text.
45890
45891
45892*/
45893bool colorBullet;
45894/*!
45895@brief If populated with the name of another GuiListBoxCtrl, then this list box will mirror the contents of the mirrorSet listbox.
45896
45897
45898*/
45899string mirrorSet;
45900/*!
45901@brief A script snippet to control what is displayed in the list for a SimObject. Within this snippet, $ThisControl is bound to the guiListBoxCtrl and $ThisObject to the contained object in question.
45902
45903
45904*/
45905string makeNameCallback;
45906
45907/*! @name Layout
45908@{ */
45909/// @}
45910
45911
45912/*! @name Control
45913@{ */
45914/// @}
45915
45916
45917/*! @name ToolTip
45918@{ */
45919/// @}
45920
45921
45922/*! @name Editing
45923@{ */
45924/// @}
45925
45926
45927/*! @name Localization
45928@{ */
45929/// @}
45930
45931
45932/*! @name Ungrouped
45933@{ */
45934/// @}
45935
45936
45937/*! @name Object
45938@{ */
45939/// @}
45940
45941
45942/*! @name Editing
45943@{ */
45944/// @}
45945
45946
45947/*! @name Persistence
45948@{ */
45949/// @}
45950
45951};
45952
45953/*!
45954@brief A control that displays a list of files from within a single directory in the game file system.
45955
45956@tsexample
45957
45958new GuiDirectoryFileListCtrl()
45959{
45960   filePath = "art/shapes";
45961   fileFilter = "*.dts" TAB "*.dae";
45962   //Properties not specific to this control have been omitted from this example.
45963};
45964@endtsexample
45965
45966@ingroup GuiControls
45967
45968*/
45969class GuiDirectoryFileListCtrl : public GuiListBoxCtrl {
45970public:
45971/*!
45972@brief Set the file filter.
45973
45974
45975@param filter Tab-delimited list of file name patterns. Only matched files will be displayed.
45976*/
45977void setFilter( string filter );
45978/*!
45979@brief Update the file list.
45980
45981*/
45982void reload();
45983/*!
45984@brief Set the search path and file filter.
45985
45986
45987@param path   Path in game directory from which to list files.
45988@param filter Tab-delimited list of file name patterns. Only matched files will be displayed.
45989*/
45990bool setPath( string path, string filter );
45991/*!
45992@brief Get the list of selected files.
45993
45994
45995@return A space separated list of selected files*/
45996string getSelectedFiles();
45997/*!
45998@brief Get the currently selected filename.
45999
46000
46001@return The filename of the currently selected file
46002*/
46003string getSelectedFile();
46004
46005/*! @name Callbacks
46006@{ */
46007/// @}
46008
46009/*!
46010@brief Path in game directory from which to list files.
46011*/
46012string filePath;
46013/*!
46014@brief Tab-delimited list of file name patterns. Only matched files will be displayed.
46015*/
46016string fileFilter;
46017
46018/*! @name Layout
46019@{ */
46020/// @}
46021
46022
46023/*! @name Control
46024@{ */
46025/// @}
46026
46027
46028/*! @name ToolTip
46029@{ */
46030/// @}
46031
46032
46033/*! @name Editing
46034@{ */
46035/// @}
46036
46037
46038/*! @name Localization
46039@{ */
46040/// @}
46041
46042
46043/*! @name Ungrouped
46044@{ */
46045/// @}
46046
46047
46048/*! @name Object
46049@{ */
46050/// @}
46051
46052
46053/*! @name Editing
46054@{ */
46055/// @}
46056
46057
46058/*! @name Persistence
46059@{ */
46060/// @}
46061
46062};
46063
46064/*!
46065@brief Hierarchical list of text items with optional icons.
46066
46067Can also be used to inspect SimObject hierarchies, primarily within editors.
46068
46069GuiTreeViewCtrls can either display arbitrary user-defined trees or can be used to display SimObject hierarchies where each parent node in the tree is a SimSet or SimGroup and each leaf node is a SimObject.
46070
46071Each item in the tree has a text and a value.  For trees that display SimObject hierarchies, the text for each item is automatically derived from objects while the value for each item is the ID of the respective SimObject.  For trees that are not tied to SimObjects, both text and value of each item are set by the user.
46072
46073Additionally, items in the tree can have icons.
46074
46075Each item in the tree has a distinct numeric ID that is unique within its tree.  The ID of the root item, which is always present on a tree, is 0.
46076
46077@tsexample
46078new GuiTreeViewCtrl(DatablockEditorTree)
46079{
46080  tabSize = "16";
46081  textOffset = "2";
46082  fullRowSelect = "0";
46083  itemHeight = "21";
46084  destroyTreeOnSleep = "0";
46085  MouseDragging = "0";
46086  MultipleSelections = "1";
46087  DeleteObjectAllowed = "1";
46088  DragToItemAllowed = "0";
46089  ClearAllOnSingleSelection = "1";
46090  showRoot = "1";
46091  internalNamesOnly = "0";
46092  objectNamesOnly = "0";
46093  compareToObjectID = "0";
46094  Profile = "GuiTreeViewProfile";
46095  tooltipprofile = "GuiToolTipProfile";
46096  hovertime = "1000";
46097};
46098@endtsexample
46099
46100@ingroup GuiContainers
46101
46102*/
46103class GuiTreeViewCtrl : public GuiArrayCtrl {
46104public:
46105/*!
46106@brief Get the ID of the item whose text matches the given @a text.
46107
46108
46109@param text Item text to match.
46110@return ID of the item or -1 if no item matches the given text.*/
46111int findItemByName( string text );
46112/*!
46113@brief Get the ID of the item whose value matches @a value.
46114
46115
46116@param value Value text to match.
46117@return ID of the item or -1 if no item has the given value.*/
46118int findItemByValue( string value );
46119/*!
46120@brief Get the child item of the given parent item whose text matches @a childName.
46121
46122
46123@param parentId Item ID of the parent in which to look for the child.
46124@param childName Text of the child item to find.
46125@return ID of the child item or -1 if no child in @a parentId has the given text @a childName.
46126
46127@note This method does not recurse, i.e. it only looks for direct children.*/
46128int findChildItemByName( int parentId, string childName );
46129/*!
46130@brief Add a new item to the tree.
46131
46132
46133@param parentId Item ID of parent to which to add the item as a child.  0 is root item.
46134@param text Text to display on the item in the tree.
46135@param value Behind-the-scenes value of the item.
46136@param icon
46137@param normalImage
46138@param expandedImage
46139@return The ID of the newly added item.*/
46140int insertItem( int parentId, string text, string value="", string icon="", int normalImage=0, int expandedImage=0 );
46141/*!
46142@brief Inserts object as a child to the given parent.
46143
46144*/
46145int insertObject( int parentId, SimObject obj, bool OKToEdit=false );
46146/*!
46147@brief Set whether the current selection can be changed by the user or not.
46148
46149
46150@param lock If true, the current selection is frozen and cannot be changed.  If false, the selection may be modified.*/
46151void lockSelection( bool lock=true );
46152/*!
46153@brief Call SimObject::setHidden( @a state ) on all objects in the current selection.
46154
46155
46156@param state Visibility state to set objects in selection to.*/
46157void hideSelection( bool state=true );
46158/*!
46159@brief Toggle the locked state of all objects in the current selection.
46160
46161*/
46162void toggleLockSelection();
46163/*!
46164@brief Toggle the hidden state of all objects in the current selection.
46165
46166*/
46167void toggleHideSelection();
46168/*!
46169@brief Unselect all currently selected items.
46170
46171*/
46172void clearSelection();
46173/*!
46174@brief Delete all items/objects in the current selection.
46175
46176*/
46177void deleteSelection();
46178/*!
46179@brief Add an item/object to the current selection.
46180
46181
46182@param id ID of item/object to add to the selection.
46183@param isLastSelection Whether there are more pending items/objects to be added to the selection.  If false, the control will defer refreshing the tree and wait until addSelection() is called with this parameter set to true.*/
46184void addSelection( int id, bool isLastSelection=true );
46185/*!
46186@brief Add a child selection by it's value.
46187
46188
46189@param parentId Parent TreeItemId.
46190@param value Value to search for.
46191*/
46192void addChildSelectionByValue( int parentId, string value );
46193/*!
46194@brief Deselect an item or remove it from the selection.
46195
46196
46197@param itemId Item Id to deselect.
46198*/
46199void removeSelection( int itemId );
46200/*!
46201@brief Deselect a child item or remove it from the selection based on its parent and its value.
46202
46203
46204@param parentId Parent TreeItemId.
46205@param value Value to search for.
46206@param performCallback True to notify script of the change, false to not.
46207*/
46208void removeChildSelectionByValue( int parentId, string value );
46209/*!
46210@brief Select or deselect and item.
46211
46212
46213@param itemID TreeItemId of item to select or deselect.
46214@param select True to select the item, false to deselect it.
46215@return True if it was successful, false if not.*/
46216bool selectItem( int itemID, bool select=true );
46217/*!
46218@brief Expand/contract item, item's sub-tree.
46219
46220
46221@param itemID TreeItemId of item to expand or contract.
46222@param expand True to expand the item, false to contract it.
46223@return True if it was successful, false if not.*/
46224bool expandItem( int itemID, bool expand=true );
46225/*!
46226@brief Mark/unmark item.
46227
46228
46229@param itemID TreeItemId of item to Mark or unmark.
46230@param mark True to Mark the item, false to unmark it.
46231@return True if it was successful, false if not.*/
46232bool markItem( int itemID, bool mark=true );
46233/*!
46234@brief Make the given item visible.
46235
46236
46237@param itemID TreeItemId of item to scroll to/make visible.
46238@return True if it was successful, false if not.*/
46239bool scrollVisible( int itemID );
46240/*!
46241@brief Builds an icon table.
46242
46243
46244@param icons Name of icons to build, Icons should be designated by the bitmap/png file names (minus the file extensions)and separated by colons (:). This list should be synchronized with the Icons enum
46245@return True if it was successful, false if not.*/
46246bool buildIconTable( string icons );
46247/*!
46248@brief Set the root of the tree view to the specified object, or to the root set.
46249
46250
46251@param objName Name or id of SimSet or object to set the tree root equal to.
46252*/
46253void open( string objName, bool okToEdit=true );
46254/*!
46255@brief Set the tooltip to show for the given item.
46256
46257
46258@param itemId  TreeItemID of item to set the tooltip for.
46259@param tooltip   String tooltip to set for the item.@return True if successfully found the item, false if not*/
46260bool setItemTooltip( int itemId, string tooltip );
46261/*!
46262@brief Sets the normal and expanded images to show for the given item.
46263
46264
46265@param itemId TreeItemID of item to set images for.
46266@param normalImage Normal image to set for the given item.@param expandedImage Expanded image to set for the given item.*/
46267void setItemImages( int itemId, S8 normalImage, S8 expandedImage );
46268/*!
46269@brief Returns true if the given item contains child items.
46270
46271
46272@param itemId TreeItemID to check for children.
46273@return True if the given item contains child items, false if not.*/
46274bool isParentItem( int itemId );
46275/*!
46276@brief Gets the text for a given item.
46277
46278
46279@param itemId TreeItemID to get text of.
46280@return Text for a given item.*/
46281string getItemText( int itemId );
46282/*!
46283@brief Gets the value for a given item.
46284
46285
46286@param itemId TreeItemID to get value of.
46287@return Value for a given item.*/
46288string getItemValue( int itemId );
46289/*!
46290@brief Edits the text and value for a given tree item.
46291
46292
46293@param itemId TreeItemID to edit.
46294@return True if successful, false if not.*/
46295bool editItem( int itemId, string newText, string newValue );
46296/*!
46297@brief Remove an item from the tree with the given id.
46298
46299
46300@param itemId TreeItemID of item to remove.
46301@param deleteObjects Whether the object on the item is deleted when the item is.
46302@return True if successful, false if not.*/
46303bool removeItem( int itemId=0, bool deleteObjects=true );
46304/*!
46305@brief Remove all children of an item from the tree with the given id.
46306
46307
46308@param itemId TreeItemID of item that has children we should remove.
46309*/
46310void removeAllChildren( int itemId );
46311/*!
46312@brief Empty the tree.
46313
46314*/
46315void clear();
46316/*!
46317@brief Get id for root item.
46318
46319@return Id for root item.*/
46320int getFirstRootItem();
46321/*!
46322@brief Get the child of the parent with the given id.
46323
46324
46325@param itemId TreeItemID of item that a child we should get.
46326@return Id of child of given item.*/
46327int getChild( int itemId );
46328/*!
46329@brief Build the visible tree.
46330
46331
46332@param forceFullUpdate True to force a full update of the tree, false to only update the new stuff.
46333*/
46334void buildVisibleTree( bool forceFullUpdate=false );
46335/*!
46336@brief Get the parent of a given id in the tree.
46337
46338
46339@param itemId TreeItemID of item that has a parent we should get.
46340@return Id of parent of given item.*/
46341int getParentItem( int itemId );
46342/*!
46343@brief Get the next sibling of the given item id in the tree.
46344
46345
46346@param itemId TreeItemID of item that we want the next sibling of.
46347@return Id of next sibling of the given item.*/
46348int getNextSibling( int itemId );
46349/*!
46350@brief Get the previous sibling of the given item id in the tree.
46351
46352
46353@param itemId TreeItemID of item that we want the previous sibling of.
46354@return Id of previous sibling of the given item.*/
46355int getPrevSibling( int itemId );
46356/*!
46357@brief Get the total number of items in the tree or item count.
46358
46359
46360@return total number of items in the tree.*/
46361int getItemCount();
46362/*!
46363@brief Return the selected item at the given index.
46364
46365
46366@param index Given index to look for selected item.@return selected item at the given index.*/
46367int getSelectedItem( int index=0 );
46368/*!
46369@brief Return the currently selected SimObject at the given index in inspector mode or -1.
46370
46371
46372@param index Given index to look for selected object.@return currently selected SimObject at the given index in inspector mode or -1.*/
46373int getSelectedObject( int index=0 );
46374/*!
46375@brief Returns a space separated list of all selected object ids.
46376
46377
46378@return space separated list of all selected object ids.*/
46379string getSelectedObjectList();
46380/*!
46381@brief Move the specified item up in the tree.
46382
46383
46384@param itemId TreeItemId of item to move up in the tree.*/
46385void moveItemUp( int itemId );
46386/*!
46387@brief Get the selected number of items.
46388
46389
46390@return number of selected items.*/
46391int getSelectedItemsCount();
46392/*!
46393@brief Move the specified item down in the tree.
46394
46395
46396@param itemId TreeItemId of item to move down in the tree.*/
46397void moveItemDown( int itemId );
46398/*!
46399@brief Gets the text from the current node to the root, concatenating at each branch upward, with a specified delimiter optionally.
46400
46401
46402@param itemId TreeItemId of node to start at.@param delimiter (Optional) delimiter to use between each branch concatenation.@return text from the current node to the root.*/
46403string getTextToRoot( int itemId, string delimiter="" );
46404/*!
46405@brief Returns a space separated list if ids of all selected items.
46406
46407
46408@return space separated list of selected item ids.*/
46409string getSelectedItemList();
46410/*!
46411@brief Find an item by its object id and returns the Tree Item ID for it.
46412
46413
46414@param objectId  Object id you want the item id for.@return Tree Item Id for the given object ID.*/
46415int findItemByObjectId( int objectId );
46416/*!
46417@brief Gets the object for a particular item.
46418
46419
46420@param itemId  Item id you want the object id for.@return Object Id for the given tree item ID.*/
46421int getItemObject( int itemId );
46422/*!
46423@brief Show item by object id.
46424
46425
46426@param objectId  Object id you want to scroll to.@return True if successful, false if not.*/
46427int scrollVisibleByObjectId( int objectId );
46428/*!
46429@brief Sorts all items of the given parent (or root).  With 'hierarchy', traverses hierarchy.@param parentId  TreeItemID of parent/root to sort all the items under. Use 0 to sort the entire tree.@param traverseHierarchy True to traverse the hierarchy, false to not.@param parentsFirst True to sort the parents first.@param caseSensitive True to pay attention to case, false to ignore it.
46430
46431*/
46432void sort( int parentId=0, bool traverseHierarchy=false, bool parentsFirst=false, bool caseSensitive=true );
46433/*!
46434@brief Cancel renaming an item (For internal use).
46435
46436*/
46437void cancelRename();
46438/*!
46439@brief Validate the new name for an object (For internal use).
46440
46441*/
46442void onRenameValidate();
46443/*!
46444@brief Show the rename text field for the given item (only one at a time).@param itemId TreeItemId of item to show rename text field for.
46445
46446*/
46447void showItemRenameCtrl( int itemId );
46448/*!
46449@brief Enable/disable debug output.@param value True to enable debug output, false to disable it.
46450
46451*/
46452void setDebug( bool value=true );
46453/*!
46454@brief Check whether the given item is currently selected in the tree.
46455
46456
46457@param id Item/object ID.
46458@return True if the given item/object is currently selected in the tree.*/
46459bool isItemSelected( int id );
46460/*!
46461@brief Get the current filter expression.  Only tree items whose text matches this expression are displayed.  By default, the expression is empty and all items are shown.
46462
46463
46464@return The current filter pattern or an empty string if no filter pattern is currently active.
46465
46466@see setFilterText
46467@see clearFilterText*/
46468string getFilterText();
46469/*!
46470@brief Set the pattern by which to filter items in the tree.  Only items in the tree whose text matches this pattern are displayed.
46471
46472
46473@param pattern New pattern based on which visible items in the tree should be filtered.  If empty, all items become visible.
46474
46475@see getFilterText
46476@see clearFilterText*/
46477void setFilterText( string pattern );
46478/*!
46479@brief Set the pattern by which to filter items in the tree.  Only items in the tree whose text matches this pattern are displayed.
46480
46481
46482@param pattern New pattern based on which visible items in the tree should be filtered.  If empty, all items become visible.
46483
46484@see getFilterText
46485@see clearFilterText*/
46486void setFilterChildren( bool doFilterChildren=true );
46487/*!
46488@brief Set the pattern by which to filter items in the tree.  Only items in the tree whose text matches this pattern are displayed.
46489
46490
46491@param pattern New pattern based on which visible items in the tree should be filtered.  If empty, all items become visible.
46492
46493@see getFilterText
46494@see clearFilterText*/
46495void setItemFilterException( uint item=0, bool isExempt=true );
46496/*!
46497@brief Set the pattern by which to filter items in the tree.  Only items in the tree whose text matches this pattern are displayed.
46498
46499
46500@param pattern New pattern based on which visible items in the tree should be filtered.  If empty, all items become visible.
46501
46502@see getFilterText
46503@see clearFilterText*/
46504void setItemHidden( uint item=0, bool hidden=true );
46505/*!
46506@brief Set the pattern by which to filter items in the tree.  Only items in the tree whose text matches this pattern are displayed.
46507
46508
46509@param pattern New pattern based on which visible items in the tree should be filtered.  If empty, all items become visible.
46510
46511@see getFilterText
46512@see clearFilterText*/
46513void clearHiddenItems();
46514/*!
46515@brief Clear the current item filtering pattern.
46516
46517
46518@see setFilterText
46519@see getFilterText*/
46520void clearFilterText();
46521/*!
46522@brief Get the tree item at the passed in position.
46523
46524
46525@param position The position to check for what item is below it.
46526@return The id of the item under the position.*/
46527int getItemAtPosition( Point2I position=Point2I::Zero );
46528/*!
46529@brief Check whether the given item is currently selected in the tree.
46530
46531
46532@param id Item/object ID.
46533@return True if the given item/object is currently selected in the tree.*/
46534void reparentItem( int itemId=0, int parentId=0 );
46535/*!
46536@brief Get the tree item at the passed in position.
46537
46538
46539@param position The position to check for what item is below it.
46540@return The id of the item under the position.*/
46541int getTabLevel( int itemId=0 );
46542
46543/*! @name Callbacks
46544@{ */
46545bool onDeleteObject( SimObject object );
46546bool isValidDragTarget( int id, string value );
46547void onDefineIcons();
46548void onAddGroupSelected( SimGroup group );
46549void onAddSelection( int itemOrObjectId, bool isLastSelection );
46550void onSelect( int itemOrObjectId );
46551void onInspect( int itemOrObjectId );
46552void onRemoveSelection( int itemOrObjectId );
46553void onUnselect( int itemOrObjectId );
46554void onDeleteSelection();
46555void onObjectDeleteCompleted();
46556void onKeyDown( int modifier, int keyCode );
46557void onMouseUp( int hitItemId, int mouseClickCount );
46558void onMouseDragged();
46559void onRightMouseDown( int itemId, Point2I mousePos, SimObject object );
46560void onRightMouseUp( int itemId, Point2I mousePos, SimObject object );
46561void onBeginReparenting();
46562void onEndReparenting();
46563void onReparent( int itemOrObjectId, int oldParentItemOrObjectId, int newParentItemOrObjectId );
46564void onDragDropped();
46565void onAddMultipleSelectionBegin();
46566void onAddMultipleSelectionEnd();
46567bool canRenameObject( SimObject object );
46568bool handleRenameObject( string newName, SimObject object );
46569void onClearSelection();
46570/// @}
46571
46572
46573/*! @name TreeView
46574@{ */
46575/*!
46576*/
46577int tabSize;
46578/*!
46579*/
46580int textOffset;
46581/*!
46582*/
46583bool fullRowSelect;
46584/*!
46585*/
46586int itemHeight;
46587/*!
46588@brief If true, the entire tree item hierarchy is deleted when the control goes to sleep.
46589*/
46590bool destroyTreeOnSleep;
46591/*!
46592*/
46593bool mouseDragging;
46594/*!
46595@brief If true, multiple items can be selected concurrently.
46596*/
46597bool multipleSelections;
46598/*!
46599*/
46600bool deleteObjectAllowed;
46601/*!
46602*/
46603bool dragToItemAllowed;
46604/*!
46605*/
46606bool clearAllOnSingleSelection;
46607/*!
46608@brief If true, the root item is shown in the tree.
46609*/
46610bool showRoot;
46611/*!
46612*/
46613bool useInspectorTooltips;
46614/*!
46615*/
46616bool tooltipOnWidthOnly;
46617/// @}
46618
46619
46620/*! @name Inspector Trees
46621@{ */
46622/*!
46623@brief If true, item text labels for objects will include object IDs.
46624*/
46625bool showObjectIds;
46626/*!
46627@brief If true, item text labels for objects will include class names.
46628*/
46629bool showClassNames;
46630/*!
46631@brief If true, item text labels for objects will include object names.
46632*/
46633bool showObjectNames;
46634/*!
46635@brief If true, item text labels for obje ts will include internal names.
46636*/
46637bool showInternalNames;
46638/*!
46639@brief If true, class names will be used as object names for unnamed objects.
46640*/
46641bool showClassNameForUnnamedObjects;
46642/*!
46643*/
46644bool compareToObjectID;
46645/*!
46646@brief If true clicking on a selected item ( that is an object and not the root ) will allow you to rename it.
46647*/
46648bool canRenameObjects;
46649/*!
46650@brief If true then object renaming operates on the internalName rather than the object name.
46651*/
46652bool renameInternal;
46653/// @}
46654
46655
46656/*! @name Layout
46657@{ */
46658/// @}
46659
46660
46661/*! @name Control
46662@{ */
46663/// @}
46664
46665
46666/*! @name ToolTip
46667@{ */
46668/// @}
46669
46670
46671/*! @name Editing
46672@{ */
46673/// @}
46674
46675
46676/*! @name Localization
46677@{ */
46678/// @}
46679
46680
46681/*! @name Ungrouped
46682@{ */
46683/// @}
46684
46685
46686/*! @name Object
46687@{ */
46688/// @}
46689
46690
46691/*! @name Editing
46692@{ */
46693/// @}
46694
46695
46696/*! @name Persistence
46697@{ */
46698/// @}
46699
46700};
46701
46702/*!
46703@brief A base class for cross platform menu controls that are gamepad friendly.
46704
46705This class is used to build row-based menu GUIs that can be easily navigated using the keyboard, mouse or gamepad. The desired row can be selected using the mouse, or by navigating using the Up and Down buttons.
46706
46707@tsexample
46708
46709new GuiGameListMenuCtrl()
46710{
46711   debugRender = "0";
46712   callbackOnA = "applyOptions();";
46713   callbackOnB = "Canvas.setContent(MainMenuGui);";
46714   callbackOnX = "";
46715   callbackOnY = "revertOptions();";
46716   //Properties not specific to this control have been omitted from this example.
46717};
46718@endtsexample
46719
46720@see GuiGameListMenuProfile
46721
46722@ingroup GuiGame
46723*/
46724class GuiGameListMenuCtrl : public GuiControl {
46725public:
46726/*!
46727@brief Add a row to the list control.
46728
46729
46730@param label The text to display on the row as a label.
46731@param callback Name of a script function to use as a callback when this row is activated.
46732@param icon [optional] Index of the icon to use as a marker.
46733@param yPad [optional] An extra amount of height padding before the row. Does nothing on the first row.
46734@param useHighlightIcon [optional] Does this row use the highlight icon?.
46735@param enabled [optional] If this row is initially enabled.
46736@param mode [optional] What option mode the row is in. 0 = Default, 1 = OptionList, 2 == Keybind*/
46737void addRow( string label, string callback, int icon=-1, int yPad=0, bool useHighlightIcon=true, bool enabled=true, int mode=0 );
46738/*!
46739@brief Determines if the specified row is enabled or disabled.
46740
46741
46742@param row The row to set the enabled status of.
46743@return True if the specified row is enabled. False if the row is not enabled or the given index was not valid.*/
46744bool isRowEnabled( int row );
46745/*!
46746@brief Sets a row's enabled status according to the given parameters.
46747
46748
46749@param row The index to check for validity.
46750@param enabled Indicate true to enable the row or false to disable it.*/
46751void setRowEnabled( int row, bool enabled );
46752/*!
46753@brief Activates the current row. The script callback of  the current row will be called (if it has one).
46754
46755*/
46756void activateRow();
46757/*!
46758@brief Gets the number of rows on the control.
46759
46760
46761@return (int) The number of rows on the control.*/
46762int getRowCount();
46763/*!
46764@brief Gets the label displayed on the specified row.
46765
46766
46767@param row Index of the row to get the label of.
46768@return The label for the row.*/
46769string getRowLabel( int row );
46770/*!
46771@brief Sets the label on the given row.
46772
46773
46774@param row Index of the row to set the label on.
46775@param label Text to set as the label of the row.
46776*/
46777void setRowLabel( int row, string label );
46778/*!
46779@brief Sets the selected row. Only rows that are enabled can be selected.
46780
46781
46782@param row Index of the row to set as selected.*/
46783void setSelected( int row );
46784/*!
46785@brief Gets the index of the currently selected row.
46786
46787
46788@return Index of the selected row.*/
46789int getSelectedRow();
46790/*!
46791@brief Gets the index of the currently selected row.
46792
46793
46794@return Index of the selected row.*/
46795void clearRows();
46796/*!
46797@brief Gets the index of the currently selected row.
46798
46799
46800@return Index of the selected row.*/
46801void refresh();
46802/*!
46803@brief Add a row to the list control.
46804
46805
46806@param label The text to display on the row as a label.
46807@param options A tab separated list of options.
46808@param wrapOptions Specify true to allow options to wrap at each end or false to prevent wrapping.
46809@param callback Name of a script function to use as a callback when this row is activated.
46810@param icon [optional] Index of the icon to use as a marker.
46811@param yPad [optional] An extra amount of height padding before the row. Does nothing on the first row.
46812@param enabled [optional] If this row is initially enabled.*/
46813void addOptionRow( string label, string options, bool wrapOptions, string callback, int icon=-1, int yPad=0, bool enabled=true, string tooltip="", string defaultValue="" );
46814/*!
46815@brief Add a row to the list control.
46816
46817
46818@param label The text to display on the row as a label.
46819@param options A tab separated list of options.
46820@param wrapOptions Specify true to allow options to wrap at each end or false to prevent wrapping.
46821@param callback Name of a script function to use as a callback when this row is activated.
46822@param icon [optional] Index of the icon to use as a marker.
46823@param yPad [optional] An extra amount of height padding before the row. Does nothing on the first row.
46824@param enabled [optional] If this row is initially enabled.*/
46825void addSliderRow( string label, float defaultValue, float increment, Point2F range, string callback, int icon=-1, int yPad=0, bool enabled=true, string tooltip="" );
46826/*!
46827@brief Add a row to the list control.
46828
46829
46830@param label The text to display on the row as a label.
46831@param options A tab separated list of options.
46832@param wrapOptions Specify true to allow options to wrap at each end or false to prevent wrapping.
46833@param callback Name of a script function to use as a callback when this row is activated.
46834@param icon [optional] Index of the icon to use as a marker.
46835@param yPad [optional] An extra amount of height padding before the row. Does nothing on the first row.
46836@param enabled [optional] If this row is initially enabled.*/
46837void addKeybindRow( string label, string bitmapName, string callback, int icon=-1, int yPad=0, bool enabled=true, string tooltip="" );
46838/*!
46839@brief Removes the row at the provided index
46840
46841*/
46842void removeRow( int row );
46843/*!
46844@brief Gets the text for the currently selected option of the given row.
46845
46846
46847@param row Index of the row to get the option from.
46848@return A string representing the text currently displayed as the selected option on the given row. If there is no such displayed text then the empty string is returned.*/
46849string getCurrentOption( int row );
46850/*!
46851@brief Set the row's current option to the one specified
46852
46853
46854@param row Index of the row to set an option on.
46855@param option The option to be made active.
46856@return True if the row contained the option and was set, false otherwise.*/
46857bool selectOption( int row, string option );
46858/*!
46859@brief Sets the list of options on the given row.
46860
46861
46862@param row Index of the row to set options on.@param optionsList A tab separated list of options for the control.*/
46863void setOptions( int row, string optionsList );
46864/*!
46865@brief Sets the list of options on the given row.
46866
46867
46868@param row Index of the row to set options on.@param optionsList A tab separated list of options for the control.*/
46869float getValue( int row );
46870/*!
46871@brief Sets the list of options on the given row.
46872
46873
46874@param row Index of the row to set options on.@param optionsList A tab separated list of options for the control.*/
46875void setValue( int row, float value );
46876/*!
46877@brief Sets the list of options on the given row.
46878
46879
46880@param row Index of the row to set options on.@param optionsList A tab separated list of options for the control.*/
46881string getTooltip( int row );
46882
46883/*! @name Callbacks
46884@{ */
46885/*!
46886@brief Called when the selected row changes.
46887
46888*/
46889void onChange();
46890/*!
46891@brief Callback that occurs when an input is triggered on this control
46892
46893@param device The device type triggering the input, such as keyboard, mouse, etc
46894@param action The actual event occuring, such as a key or button
46895@param state True if the action is being pressed, false if it is being release*/
46896void onInputEvent( string device, string action, bool state );
46897/*!
46898@brief Callback that occurs when an axis event is triggered on this control
46899
46900@param device The device type triggering the input, such as mouse, joystick, gamepad, etc
46901@param action The ActionMap code for the axis
46902@param axisValue The current value of the axis*/
46903void onAxisEvent( string device, string action, float axisValue );
46904/// @}
46905
46906/*!
46907@brief Enable debug rendering
46908*/
46909bool debugRender;
46910/*!
46911@brief Script callback when the 'A' button is pressed. 'A' inputs are Keyboard: A, Return, Space; Gamepad: A, Start
46912*/
46913string callbackOnA;
46914/*!
46915@brief Script callback when the 'B' button is pressed. 'B' inputs are Keyboard: B, Esc, Backspace, Delete; Gamepad: B, Back
46916*/
46917string callbackOnB;
46918/*!
46919@brief Script callback when the 'X' button is pressed. 'X' inputs are Keyboard: X; Gamepad: X
46920*/
46921string callbackOnX;
46922/*!
46923@brief Script callback when the 'Y' button is pressed. 'Y' inputs are Keyboard: Y; Gamepad: Y
46924*/
46925string callbackOnY;
46926/*!
46927@brief Script callback when any inputs are detected, even if they aren't the regular 4 face buttons. Useful for secondary/speciality handling of menu navigation.
46928*/
46929bool callbackOnInputs;
46930/*!
46931@brief When callbackOnInputs is active, this indicates if the input event should be consumed, or allowed 'through' to let other things respond to the event as well.
46932*/
46933bool consumeKeyInputEvents;
46934
46935/*! @name Layout
46936@{ */
46937/// @}
46938
46939
46940/*! @name Control
46941@{ */
46942/// @}
46943
46944
46945/*! @name ToolTip
46946@{ */
46947/// @}
46948
46949
46950/*! @name Editing
46951@{ */
46952/// @}
46953
46954
46955/*! @name Localization
46956@{ */
46957/// @}
46958
46959
46960/*! @name Ungrouped
46961@{ */
46962/// @}
46963
46964
46965/*! @name Object
46966@{ */
46967/// @}
46968
46969
46970/*! @name Editing
46971@{ */
46972/// @}
46973
46974
46975/*! @name Persistence
46976@{ */
46977/// @}
46978
46979};
46980
46981/*!
46982@brief A control for showing pages of options that are gamepad friendly.
46983
46984Each row in this control allows the selection of one value from a set of options using the keyboard, gamepad or mouse. The row is rendered as 2 columns: the first column contains the row label, the second column contains left and right arrows (for mouse picking) and the currently selected value.
46985
46986@see GuiGameListOptionsProfile
46987
46988@ingroup GuiGame
46989*/
46990class GuiGameListOptionsCtrl : public GuiGameListMenuCtrl {
46991public:
46992/*!
46993@brief Add a row to the list control.
46994
46995
46996@param label The text to display on the row as a label.
46997@param options A tab separated list of options.
46998@param wrapOptions Specify true to allow options to wrap at each end or false to prevent wrapping.
46999@param callback Name of a script function to use as a callback when this row is activated.
47000@param icon [optional] Index of the icon to use as a marker.
47001@param yPad [optional] An extra amount of height padding before the row. Does nothing on the first row.
47002@param enabled [optional] If this row is initially enabled.*/
47003void addRow( string label, string options, bool wrapOptions, string callback, int icon=-1, int yPad=0, bool enabled=true );
47004/*!
47005@brief Gets the text for the currently selected option of the given row.
47006
47007
47008@param row Index of the row to get the option from.
47009@return A string representing the text currently displayed as the selected option on the given row. If there is no such displayed text then the empty string is returned.*/
47010string getCurrentOption( int row );
47011/*!
47012@brief Set the row's current option to the one specified
47013
47014
47015@param row Index of the row to set an option on.
47016@param option The option to be made active.
47017@return True if the row contained the option and was set, false otherwise.*/
47018bool selectOption( int row, string option );
47019/*!
47020@brief Sets the list of options on the given row.
47021
47022
47023@param row Index of the row to set options on.@param optionsList A tab separated list of options for the control.*/
47024void setOptions( int row, string optionsList );
47025/*!
47026@brief Sets the list of options on the given row.
47027
47028
47029@param row Index of the row to set options on.@param optionsList A tab separated list of options for the control.*/
47030void clearOptions();
47031
47032/*! @name Callbacks
47033@{ */
47034/// @}
47035
47036
47037/*! @name Layout
47038@{ */
47039/// @}
47040
47041
47042/*! @name Control
47043@{ */
47044/// @}
47045
47046
47047/*! @name ToolTip
47048@{ */
47049/// @}
47050
47051
47052/*! @name Editing
47053@{ */
47054/// @}
47055
47056
47057/*! @name Localization
47058@{ */
47059/// @}
47060
47061
47062/*! @name Ungrouped
47063@{ */
47064/// @}
47065
47066
47067/*! @name Object
47068@{ */
47069/// @}
47070
47071
47072/*! @name Editing
47073@{ */
47074/// @}
47075
47076
47077/*! @name Persistence
47078@{ */
47079/// @}
47080
47081};
47082
47083/*!
47084@brief A control that allows to select a value from a drop-down list.
47085
47086For a nearly identical GUI with additional features, use GuiPopUpMenuCtrlEx.
47087
47088@tsexample
47089new GuiPopUpMenuCtrl()
47090{
47091  maxPopupHeight = "200";
47092  sbUsesNAColor = "0";
47093  reverseTextList = "0";
47094  bitmapBounds = "16 16";
47095  maxLength = "1024";
47096  position = "56 31";
47097  extent = "64 64";
47098  minExtent = "8 2";
47099  profile = "GuiPopUpMenuProfile";
47100  tooltipProfile = "GuiToolTipProfile";
47101};
47102@endtsexample
47103
47104@note This is definitely going to be deprecated soon.
47105
47106@see GuiPopUpMenuCtrlEx for more features and better explanations.
47107@ingroup GuiControls
47108
47109*/
47110class GuiPopUpMenuCtrl : public GuiTextCtrl {
47111public:
47112void add( string name="", int idNum=-1, uint scheme=0 );
47113void addScheme( uint id, ColorI fontColor, ColorI fontColorHL, ColorI fontColorSEL );
47114string getText();
47115/*!
47116@brief Clear the popup list.
47117
47118*/
47119void clear();
47120/*!
47121@brief Sort the list alphabetically.
47122
47123*/
47124void sort();
47125/*!
47126@brief Sort the list by ID.
47127
47128*/
47129void sortID();
47130void forceOnAction();
47131void forceClose();
47132/*!
47133@brief Gets the selected index
47134
47135*/
47136int getSelected();
47137void setSelected( int id, bool scriptCallback=true );
47138void setFirstSelected( bool scriptCallback=true );
47139void setNoneSelected();
47140string getTextById( int id );
47141void changeTextById( int id, string text );
47142/*!
47143@brief This fills the popup with a classrep's field enumeration type info.
47144
47145
47146More of a helper function than anything.   If console access to the field list is added, at least for the enumerated types, then this should go away..*/
47147void setEnumContent( string className, string enumName );
47148/*!
47149@brief Returns the position of the first entry containing the specified text or -1 if not found.
47150
47151*/
47152int findText( string text );
47153/*!
47154@brief Get the size of the menu - the number of entries in it.
47155
47156*/
47157int size();
47158void replaceText( bool doReplaceText );
47159void clearEntry( int entry );
47160
47161/*! @name Callbacks
47162@{ */
47163/// @}
47164
47165/*!
47166*/
47167int maxPopupHeight;
47168/*!
47169*/
47170bool sbUsesNAColor;
47171/*!
47172*/
47173bool reverseTextList;
47174/*!
47175*/
47176filename bitmap;
47177/*!
47178*/
47179Point2I bitmapBounds;
47180
47181/*! @name Layout
47182@{ */
47183/// @}
47184
47185
47186/*! @name Layout
47187@{ */
47188/// @}
47189
47190
47191/*! @name Control
47192@{ */
47193/// @}
47194
47195
47196/*! @name ToolTip
47197@{ */
47198/// @}
47199
47200
47201/*! @name Editing
47202@{ */
47203/// @}
47204
47205
47206/*! @name Localization
47207@{ */
47208/// @}
47209
47210
47211/*! @name Ungrouped
47212@{ */
47213/// @}
47214
47215
47216/*! @name Object
47217@{ */
47218/// @}
47219
47220
47221/*! @name Editing
47222@{ */
47223/// @}
47224
47225
47226/*! @name Persistence
47227@{ */
47228/// @}
47229
47230};
47231
47232/*!
47233@brief A control that allows to select a value from a drop-down list.
47234
47235This is essentially a GuiPopUpMenuCtrl, but with quite a few more features.
47236
47237@tsexample
47238new GuiPopUpMenuCtrlEx()
47239{
47240  maxPopupHeight = "200";
47241  sbUsesNAColor = "0";
47242  reverseTextList = "0";
47243  bitmapBounds = "16 16";
47244  hotTrackCallback = "0";
47245  extent = "64 64";
47246  profile = "GuiDefaultProfile";
47247  tooltipProfile = "GuiToolTipProfile";
47248};
47249@endtsexample
47250
47251@see GuiPopUpMenuCtrl
47252@ingroup GuiControls
47253
47254*/
47255class GuiPopUpMenuCtrlEx : public GuiTextCtrl {
47256public:
47257/*!
47258brief Manually set the selection to the first entry
47259
47260@param scripCallback Optional boolean that forces the script callback if true
47261*/
47262
47263setSelected(bool scriptCallback=true);
47264/*!
47265brief Manually set an entry as selected int his control
47266
47267@param id The ID of the entry to select
47268@param scripCallback Optional boolean that forces the script callback if true
47269*/
47270
47271setSelected(int id, bool scriptCallback=true);
47272/*!
47273@brief Adds an entry to the list
47274
47275@param name String containing the name of the entry
47276@param idNum Numerical value assigned to the name
47277@param scheme Optional ID associated with a scheme for font coloring, highlight coloring, and selection coloring
47278
47279*/
47280
47281void add(string name, S32 idNum, S32 scheme=0);
47282void add( string name="", int idNum=-1, uint scheme=0 );
47283/*!
47284@brief Add a category to the list.
47285
47286Acts as a separator between entries, allowing for sub-lists
47287
47288@param text Name of the new category*/
47289void addCategory( string text );
47290/*!
47291@brief Create a new scheme and add it to the list of choices for when a new text entry is added.
47292
47293@param id Numerical id associated with this scheme
47294@param fontColor The base text font color. Formatted as "Red Green Blue", each a numerical between 0 and 255.
47295@param fontColorHL Color of text when being highlighted. Formatted as "Red Green Blue", each a numerical between 0 and 255.
47296@param fontColorSel Color of text when being selected. Formatted as "Red Green Blue", each a numerical between 0 and 255.*/
47297void addScheme( int id, ColorI fontColor, ColorI fontColorHL, ColorI fontColorSEL );
47298/*!
47299@brief Set the current text to a specified value.
47300
47301@param text String containing new text to set*/
47302void setText( string text );
47303/*!
47304@brief Get the.
47305
47306Detailed description
47307
47308@param param Description
47309
47310@tsexample
47311// Comment
47312code();
47313@endtsexample
47314
47315@return Returns current text in string format*/
47316string getText();
47317/*!
47318@brief Clear the popup list.*/
47319void clear();
47320/*!
47321@brief Sort the list alphabetically.*/
47322void sort();
47323/*!
47324@brief Sort the list by ID.*/
47325void sortID();
47326/*!
47327@brief Manually for the onAction function, which updates everything in this control.*/
47328void forceOnAction();
47329/*!
47330@brief Manually force this control to collapse and close.*/
47331void forceClose();
47332/*!
47333@brief Get the current selection of the menu.
47334
47335@return Returns the ID of the currently selected entry*/
47336int getSelected();
47337/*!
47338@brief Clears selection in the menu.*/
47339void setNoneSelected( int param );
47340/*!
47341@brief Get the text of an entry based on an ID.
47342
47343@param id The ID assigned to the entry being queried
47344
47345@return String contained by the specified entry, NULL if empty or bad ID*/
47346string getTextById( int id );
47347/*!
47348@brief Get color of an entry's box
47349
47350@param id ID number of entry to query
47351
47352@return ColorI in the format of "Red Green Blue Alpha", each of with is a value between 0 - 255*/
47353ColorI getColorById( int id );
47354/*!
47355@brief This fills the popup with a classrep's field enumeration type info.
47356
47357More of a helper function than anything.   If console access to the field list is added, at least for the enumerated types, then this should go away.
47358
47359@param class Name of the class containing the enum
47360@param enum Name of the enum value to acces*/
47361void setEnumContent( string className, string enumName );
47362/*!
47363@brief Returns the id of the first entry containing the specified text or -1 if not found.@param text String value used for the query
47364
47365
47366@return Numerical ID of entry containing the text.*/
47367int findText( string text );
47368/*!
47369@brief Get the size of the menu
47370
47371@return Number of entries in the menu*/
47372int size();
47373/*!
47374@brief Flag that causes each new text addition to replace the current entry
47375
47376@param True to turn on replacing, false to disable it*/
47377void replaceText( int boolVal );
47378void clearEntry( int entry );
47379
47380/*! @name Callbacks
47381@{ */
47382/// @}
47383
47384/*!
47385@brief Length of menu when it extends
47386*/
47387int maxPopupHeight;
47388/*!
47389@brief Deprecated@internal
47390*/
47391bool sbUsesNAColor;
47392/*!
47393@brief Reverses text list if popup extends up, instead of down
47394*/
47395bool reverseTextList;
47396/*!
47397@brief File name of bitmap to use
47398*/
47399filename bitmap;
47400/*!
47401@brief Boundaries of bitmap displayed
47402*/
47403Point2I bitmapBounds;
47404/*!
47405@brief Whether to provide a 'onHotTrackItem' callback when a list item is hovered over
47406*/
47407bool hotTrackCallback;
47408
47409/*! @name Layout
47410@{ */
47411/// @}
47412
47413
47414/*! @name Layout
47415@{ */
47416/// @}
47417
47418
47419/*! @name Control
47420@{ */
47421/// @}
47422
47423
47424/*! @name ToolTip
47425@{ */
47426/// @}
47427
47428
47429/*! @name Editing
47430@{ */
47431/// @}
47432
47433
47434/*! @name Localization
47435@{ */
47436/// @}
47437
47438
47439/*! @name Ungrouped
47440@{ */
47441/// @}
47442
47443
47444/*! @name Object
47445@{ */
47446/// @}
47447
47448
47449/*! @name Editing
47450@{ */
47451/// @}
47452
47453
47454/*! @name Persistence
47455@{ */
47456/// @}
47457
47458};
47459
47460/*!
47461@brief A control that displays a value between its minimal and maximal bounds using a slider placed on a vertical or horizontal axis.
47462
47463A slider displays a value and allows that value to be changed by dragging a thumb control along the axis of the slider.  In this way, the value is changed between its allowed minimum and maximum.
47464
47465To hook up script code to the value changes of a slider, use the #command and #altCommand properties.  #command is executed once the thumb is released by the user whereas #altCommand is called any time the slider value changes. When changing the slider value from script, however, trigger of #altCommand is suppressed by default.
47466
47467The orientation of a slider is automatically determined from the ratio of its width to its height.  If a slider is taller than it is wide, it will be rendered with a vertical orientation.  If it is wider than it is tall, it will be rendered with a horizontal orientation.
47468
47469The rendering of a slider depends on the bitmap in the slider's profile.  This bitmap must be a bitmap array comprised of at least five bitmap rectangles.  The rectangles are used such that:
47470
47471- Rectangle #1: Left edge of slider
47472- Rectangle #2: Center piece of slider; this is stretched between the left and right edge
47473- Rectangle #3: Right edge of slider
47474- Rectangle #4: Thumb button in normal state
47475- Rectangle #5: Thumb button in highlighted (mouse-over) state
47476
47477@tsexample
47478// Create a sound source and a slider that changes the volume of the source.
47479
47480%source = sfxPlayOnce( "art/sound/testing", AudioLoop2D );
47481
47482new GuiSlider()
47483{
47484   // Update the sound source volume when the slider is being dragged and released.
47485   command = %source @ ".setVolume( $ThisControl.value );";
47486
47487   // Limit the range to 0..1 since that is the allowable range for sound volumes.
47488   range = "0 1";
47489};
47490@endtsexample
47491
47492@see GuiTextEditSliderCtrl
47493@see GuiTextEditSliderBitmapCtrl
47494
47495@ingroup GuiValues
47496*/
47497class GuiSliderCtrl : public GuiControl {
47498public:
47499/*!
47500@brief Get the current value of the slider based on the position of the thumb.
47501
47502@return Slider position (from range.x to range.y).*/
47503float getValue();
47504/*!
47505@brief Set position of the thumb on the slider.
47506
47507@param pos New slider position (from range.x to range.y)
47508@param doCallback If true, the altCommand callback will be invoked
47509*/
47510void setValue( float pos, bool doCallback=false );
47511/*!
47512@brief Returns true if the thumb is currently being dragged by the user.  This method is mainly useful for scrubbing type sliders where the slider position is sync'd to a changing value.  When the user is dragging the thumb, however, the sync'ing should pause and not get in the way of the user.
47513
47514*/
47515bool isThumbBeingDragged();
47516
47517/*! @name Callbacks
47518@{ */
47519/*!
47520@brief Called when the left mouse button is dragged across the slider.
47521
47522*/
47523void onMouseDragged();
47524/// @}
47525
47526
47527/*! @name Slider
47528@{ */
47529/*!
47530@brief Min and max values corresponding to left and right slider position.
47531*/
47532Point2F range;
47533/*!
47534@brief Spacing between tick marks in pixels. 0=off.
47535*/
47536int ticks;
47537/*!
47538@brief Whether to snap the slider to tick marks.
47539*/
47540bool snap;
47541/*!
47542@brief The value corresponding to the current slider position.
47543*/
47544float value;
47545/*!
47546@brief Whether to render the tick marks.
47547*/
47548bool useFillBar;
47549/*!
47550@brief Whether to render the tick marks.
47551*/
47552ColorI fillBarColor;
47553/*!
47554@brief Whether to render the tick marks.
47555*/
47556bool renderTicks;
47557/// @}
47558
47559
47560/*! @name Layout
47561@{ */
47562/// @}
47563
47564
47565/*! @name Control
47566@{ */
47567/// @}
47568
47569
47570/*! @name ToolTip
47571@{ */
47572/// @}
47573
47574
47575/*! @name Editing
47576@{ */
47577/// @}
47578
47579
47580/*! @name Localization
47581@{ */
47582/// @}
47583
47584
47585/*! @name Ungrouped
47586@{ */
47587/// @}
47588
47589
47590/*! @name Object
47591@{ */
47592/// @}
47593
47594
47595/*! @name Editing
47596@{ */
47597/// @}
47598
47599
47600/*! @name Persistence
47601@{ */
47602/// @}
47603
47604};
47605
47606/*!
47607@brief A single page in a GuiTabBookCtrl.
47608
47609@tsexample
47610
47611new GuiTabPageCtrl()
47612{
47613   fitBook = "1";
47614   //Properties not specific to this control have been omitted from this example.
47615};
47616@endtsexample
47617
47618@ingroup GuiContainers
47619*/
47620class GuiTabPageCtrl : public GuiTextCtrl {
47621public:
47622/*!
47623@brief Select this page in its tab book.
47624
47625*/
47626void select();
47627
47628/*! @name Callbacks
47629@{ */
47630/// @}
47631
47632/*!
47633@brief Determines whether to resize this page when it is added to the tab book. If true, the page will be resized according to the tab book extents and <i>tabPosition</i> property.
47634*/
47635bool fitBook;
47636
47637/*! @name Layout
47638@{ */
47639/// @}
47640
47641
47642/*! @name Layout
47643@{ */
47644/// @}
47645
47646
47647/*! @name Control
47648@{ */
47649/// @}
47650
47651
47652/*! @name ToolTip
47653@{ */
47654/// @}
47655
47656
47657/*! @name Editing
47658@{ */
47659/// @}
47660
47661
47662/*! @name Localization
47663@{ */
47664/// @}
47665
47666
47667/*! @name Ungrouped
47668@{ */
47669/// @}
47670
47671
47672/*! @name Object
47673@{ */
47674/// @}
47675
47676
47677/*! @name Editing
47678@{ */
47679/// @}
47680
47681
47682/*! @name Persistence
47683@{ */
47684/// @}
47685
47686};
47687
47688/*!
47689@brief GUI control that displays a list of text. Text items in the list can be individually selected.
47690
47691@tsexample
47692      new GuiTextListCtrl(EndGameGuiList)
47693      {
47694         columns = "0 256";
47695           fitParentWidth = "1";
47696         clipColumnText = "0";
47697          //Properties not specific to this control have been omitted from this example.
47698      };
47699@endtsexample
47700
47701@see Reference
47702
47703@ingroup GuiControls
47704
47705*/
47706class GuiTextListCtrl : public GuiArrayCtrl {
47707public:
47708/*!
47709@brief Get the ID of the currently selected item.
47710
47711@tsexample
47712// Acquire the ID of the selected item in the list.
47713%id = %thisGuiTextListCtrl.getSelectedId();
47714@endtsexample
47715
47716@return The id of the selected item in the list.
47717
47718@see GuiControl*/
47719int getSelectedId();
47720/*!
47721@brief Finds the specified entry by id, then marks its row as selected.
47722
47723@param id Entry within the text list to make selected.
47724@tsexample
47725// Define the id
47726%id = "5";
47727
47728// Inform the GuiTextListCtrl control to set the defined id entry as selected
47729%thisGuiTextListCtrl.setSelectedById(%id);
47730@endtsexample
47731
47732@see GuiControl*/
47733void setSelectedById( int id );
47734/*!
47735@briefSelects the specified row.
47736
47737@param rowNum Row number to set selected.
47738@tsexample
47739// Define the row number to set selected
47740%rowNum = "4";
47741
47742%guiTextListCtrl.setSelectedRow(%rowNum);
47743@endtsexample
47744
47745@see GuiControl*/
47746void setSelectedRow( int rowNum );
47747/*!
47748@brief Returns the selected row index (not the row ID).
47749
47750@tsexample
47751// Acquire the selected row index
47752%rowIndex = %thisGuiTextListCtrl.getSelectedRow();
47753@endtsexample
47754
47755@return Index of the selected row
47756
47757@see GuiControl*/
47758int getSelectedRow();
47759/*!
47760@brief Set the selection to nothing.
47761
47762@tsexample
47763// Deselect anything that is currently selected
47764%thisGuiTextListCtrl.clearSelection();
47765@endtsexample
47766
47767@see GuiControl*/
47768void clearSelection();
47769/*!
47770@brief Adds a new row at end of the list with the defined id and text.
47771If index is used, then the new row is inserted at the row location of 'index'.
47772
47773@param id Id of the new row.
47774@param text Text to display at the new row.
47775@param index Index to insert the new row at. If not used, new row will be placed at the end of the list.
47776@tsexample
47777// Define the id
47778%id = "4";
47779
47780// Define the text to display
47781%text = "Display Text"
47782
47783// Define the index (optional)
47784%index = "2"
47785
47786// Inform the GuiTextListCtrl control to add the new row with the defined information.
47787%rowIndex = %thisGuiTextListCtrl.addRow(%id,%text,%index);
47788@endtsexample
47789
47790@return Returns the row index of the new row. If 'index' was defined, then this just returns the number of rows in the list.
47791
47792@see References*/
47793int addRow( int id=0, string text="", int index=-1 );
47794/*!
47795@brief Sets the text at the defined id.
47796
47797@param id Id to change.
47798@param text Text to use at the Id.
47799@tsexample
47800// Define the id
47801%id = "4";
47802
47803// Define the text
47804%text = "Text To Display";
47805
47806// Inform the GuiTextListCtrl control to display the defined text at the defined id
47807%thisGuiTextListCtrl.setRowById(%id,%text);
47808@endtsexample
47809
47810@see GuiControl*/
47811void setRowById( int id, string text );
47812/*!
47813@brief Performs a standard (alphabetical) sort on the values in the specified column.
47814
47815@param columnId Column ID to perform the sort on.
47816@param increasing If false, sort will be performed in reverse.
47817@tsexample
47818// Define the columnId
47819%id = "1";
47820
47821// Define if we are increasing or not
47822%increasing = "false";
47823
47824// Inform the GuiTextListCtrl to perform the sort operation
47825%thisGuiTextListCtrl.sort(%id,%increasing);
47826@endtsexample
47827
47828@see GuiControl*/
47829void sort( int columnId, bool increasing=true );
47830/*!
47831@brief Perform a numerical sort on the values in the specified column.
47832
47833Detailed description
47834
47835@param columnId Column ID to perform the sort on.
47836@param increasing If false, sort will be performed in reverse.
47837@tsexample
47838// Define the columnId
47839%id = "1";
47840
47841// Define if we are increasing or not
47842%increasing = "false";
47843
47844// Inform the GuiTextListCtrl to perform the sort operation
47845%thisGuiTextListCtrl.sortNumerical(%id,%increasing);
47846@endtsexample
47847
47848@see GuiControl*/
47849void sortNumerical( int columnID, bool increasing=true );
47850/*!
47851@brief Clear the list.
47852
47853@tsexample
47854// Inform the GuiTextListCtrl control to clear its contents
47855%thisGuiTextListCtrl.clear();
47856@endtsexample
47857
47858@see GuiControl*/
47859void clear();
47860/*!
47861@brief Get the number of rows.
47862
47863@tsexample
47864// Get the number of rows in the list
47865%rowCount = %thisGuiTextListCtrl.rowCount();
47866@endtsexample
47867
47868@return Number of rows in the list.
47869
47870@see GuiControl*/
47871int rowCount();
47872/*!
47873@brief Get the row ID for an index.
47874
47875@param index Index to get the RowID at
47876@tsexample
47877// Define the index
47878%index = "3";
47879
47880// Request the row ID at the defined index
47881%rowId = %thisGuiTextListCtrl.getRowId(%index);
47882@endtsexample
47883
47884@return RowId at the defined index.
47885
47886@see GuiControl*/
47887int getRowId( int index );
47888/*!
47889@brief Get the text of a row with the specified id.
47890
47891@tsexample
47892// Define the id
47893%id = "4";
47894
47895// Inform the GuiTextListCtrl control to return the text at the defined row id
47896%rowText = %thisGuiTextListCtrl.getRowTextById(%id);
47897@endtsexample
47898
47899@return Row text at the requested row id.
47900
47901@see GuiControl*/
47902string getRowTextById( int id );
47903/*!
47904@brief Get the row number for a specified id.
47905
47906@param id Id to get the row number at
47907@tsexample
47908// Define the id
47909%id = "4";
47910
47911// Request the row number from the GuiTextListCtrl control at the defined id.
47912%rowNumber = %thisGuiTextListCtrl.getRowNumById(%id);
47913@endtsexample
47914
47915@see GuiControl*/
47916int getRowNumById( int id );
47917/*!
47918@brief Get the text of the row with the specified index.
47919
47920@param index Row index to acquire the text at.
47921@tsexample
47922// Define the row index
47923%index = "5";
47924
47925// Request the text from the row at the defined index
47926%rowText = %thisGuiTextListCtrl.getRowText(%index);
47927@endtsexample
47928
47929@return Text at the defined row index.
47930
47931@see GuiControl*/
47932string getRowText( int index );
47933/*!
47934@brief Remove row with the specified id.
47935
47936@param id Id to remove the row entry at
47937@tsexample
47938// Define the id
47939%id = "4";
47940
47941// Inform the GuiTextListCtrl control to remove the row at the defined id
47942%thisGuiTextListCtrl.removeRowById(%id);
47943@endtsexample
47944
47945@see GuiControl*/
47946void removeRowById( int id );
47947/*!
47948@brief Remove a row from the table, based on its index.
47949
47950@param index Row index to remove from the list.
47951@tsexample
47952// Define the row index
47953%index = "4";
47954
47955// Inform the GuiTextListCtrl control to remove the row at the defined row index
47956%thisGuiTextListCtrl.removeRow(%index);
47957@endtsexample
47958
47959@see GuiControl*/
47960void removeRow( int index );
47961/*!
47962@brief Scroll so the specified row is visible
47963
47964@param rowNum Row number to make visible
47965@tsexample
47966// Define the row number to make visible
47967%rowNum = "4";
47968
47969// Inform the GuiTextListCtrl control to scroll the list so the defined rowNum is visible.
47970%thisGuiTextListCtrl.scrollVisible(%rowNum);
47971@endtsexample
47972
47973@see GuiControl*/
47974void scrollVisible( int rowNum );
47975/*!
47976@brief Find needle in the list, and return the row number it was found in.
47977
47978@param needle Text to find in the list.
47979@tsexample
47980// Define the text to find in the list
47981%needle = "Text To Find";
47982
47983// Request the row number that contains the defined text to find
47984
47985%rowNumber = %thisGuiTextListCtrl.findTextIndex(%needle);
47986
47987@endtsexample
47988
47989@return Row number that the defined text was found in,
47990
47991@see GuiControl*/
47992int findTextIndex( string needle );
47993/*!
47994@brief Mark a specified row as active/not.
47995
47996@param rowNum Row number to change the active state.
47997@param active Boolean active state to set the row number.
47998@tsexample
47999// Define the row number
48000%rowNum = "4";
48001
48002// Define the boolean active state
48003%active = "true";
48004
48005// Informthe GuiTextListCtrl control to set the defined active state at the defined row number.
48006%thisGuiTextListCtrl.setRowActive(%rowNum,%active);
48007@endtsexample
48008
48009@see GuiControl*/
48010void setRowActive( int rowNum, bool active );
48011/*!
48012@brief Check if the specified row is currently active or not.
48013
48014@param rowNum Row number to check the active state.
48015@tsexample
48016// Define the row number
48017%rowNum = "5";
48018
48019// Request the active state of the defined row number from the GuiTextListCtrl control.
48020%rowActiveState = %thisGuiTextListCtrl.isRowActive(%rowNum);
48021@endtsexample
48022
48023@return Active state of the defined row number.
48024
48025@see GuiControl*/
48026bool isRowActive( int rowNum );
48027
48028/*! @name Callbacks
48029@{ */
48030/*!
48031@brief Called whenever an item in the list is selected.
48032
48033@param cellid The ID of the cell that was selected
48034@param text The text in the selected cel
48035
48036@tsexample
48037// A cel in the control was selected, causing the callback to occur
48038GuiTextListCtrl::onSelect(%this,%callid,%text)
48039   {
48040      // Code to run when a cel item is selected
48041   }
48042@endtsexample
48043
48044@see GuiControl*/
48045void onSelect( int cellid, string text );
48046/*!
48047@brief Called when the delete key has been pressed.
48048
48049@param id Id of the selected item in the list
48050@tsexample
48051// The delete key was pressed while the GuiTextListCtrl was in focus, causing the callback to occur.
48052GuiTextListCtrl::onDeleteKey(%this,%id)
48053   {
48054      // Code to run when the delete key is pressed
48055   }
48056@endtsexample
48057
48058@see GuiControl*/
48059void onDeleteKey( int id );
48060/// @}
48061
48062/*!
48063@brief A vector of column offsets.  The number of values determines the number of columns in the table.
48064
48065
48066*/
48067intList columns;
48068/*!
48069@brief If true, the width of this control will match the width of its parent.
48070
48071
48072*/
48073bool fitParentWidth;
48074/*!
48075@brief If true, text exceeding a column's given width will get clipped.
48076
48077
48078*/
48079bool clipColumnText;
48080/*!
48081@brief Sets how much padding to add to the row heights on top of the font height
48082*/
48083int rowHeightPadding;
48084
48085/*! @name Layout
48086@{ */
48087/// @}
48088
48089
48090/*! @name Control
48091@{ */
48092/// @}
48093
48094
48095/*! @name ToolTip
48096@{ */
48097/// @}
48098
48099
48100/*! @name Editing
48101@{ */
48102/// @}
48103
48104
48105/*! @name Localization
48106@{ */
48107/// @}
48108
48109
48110/*! @name Ungrouped
48111@{ */
48112/// @}
48113
48114
48115/*! @name Object
48116@{ */
48117/// @}
48118
48119
48120/*! @name Editing
48121@{ */
48122/// @}
48123
48124
48125/*! @name Persistence
48126@{ */
48127/// @}
48128
48129};
48130
48131/*!
48132@brief A canvas on which rendering occurs.
48133
48134@section GuiCanvas_contents What a GUICanvas Can Contain...
48135
48136@subsection GuiCanvas_content_contentcontrol Content Control
48137A content control is the top level GuiControl for a screen. This GuiControl will be the parent control for all other GuiControls on that particular screen.
48138
48139@subsection GuiCanvas_content_dialogs Dialogs
48140
48141A dialog is essentially another screen, only it gets overlaid on top of the current content control, and all input goes to the dialog. This is most akin to the "Open File" dialog box found in most operating systems. When you choose to open a file, and the "Open File" dialog pops up, you can no longer send input to the application, and must complete or cancel the open file request. Torque keeps track of layers of dialogs. The dialog with the highest layer is on top and will get all the input, unless the dialog is modeless, which is a profile option.
48142
48143@see GuiControlProfile
48144
48145@section GuiCanvas_dirty Dirty Rectangles
48146
48147The GuiCanvas is based on dirty regions. Every frame the canvas paints only the areas of the canvas that are 'dirty' or need updating. In most cases, this only is the area under the mouse cursor. This is why if you look in guiCanvas.cc the call to glClear is commented out. What you will see is a black screen, except in the dirty regions, where the screen will be painted normally. If you are making an animated GuiControl you need to add your control to the dirty areas of the canvas.
48148
48149@see GuiControl
48150
48151@ingroup GuiCore
48152
48153*/
48154class GuiCanvas : public GuiControl {
48155public:
48156/*!
48157@brief Sets the position of the cursor
48158
48159@param posX X-coordinate, in screenspace for the cursor.
48160@param posY Y-coordinate, in screenspace for the cursor.
48161
48162@tsexample
48163Canvas.setCursorPos(0,0);
48164@endtsexample
48165
48166*/
48167
48168bool setCursorPos( F32 posX, F32 posY);
48169/*!
48170@brief Sets the position of the cursor
48171
48172@param pos Point, in screenspace for the cursor. Formatted as ("x y")
48173
48174@tsexample
48175Canvas.setCursorPos("0 0");
48176@endtsexample
48177
48178*/
48179
48180bool setCursorPos( Point2I pos );
48181/*!
48182@brief Removes a specified layer of dialogs
48183
48184@param layer Number of the layer to pop
48185
48186@tsexample
48187Canvas.popLayer(1);
48188@endtsexample
48189
48190*/
48191
48192void popLayer(S32 layer);
48193/*!
48194@brief Removes the top most layer of dialogs
48195
48196@tsexample
48197Canvas.popLayer();
48198@endtsexample
48199
48200*/
48201
48202void popLayer();
48203/*!
48204@brief Removes a dialog at the front most layer
48205
48206@tsexample
48207// Pops whatever is on layer 0
48208Canvas.popDialog();
48209@endtsexample
48210
48211*/
48212
48213void popDialog();
48214/*!
48215@brief Removes a specific dialog control
48216
48217@param ctrl Dialog to pop
48218@tsexample
48219Canvas.popDialog(RecordingsDlg);
48220@endtsexample
48221
48222*/
48223
48224void popDialog( GuiControl ctrl);
48225/*!
48226@brief Adds a dialog control onto the stack of dialogs
48227
48228@param ctrl Dialog to add
48229@param layer Layer to put dialog on (optional)
48230@param center True to center dialog on canvas (optional)
48231
48232@tsexample
48233Canvas.pushDialog(RecordingsDlg);
48234@endtsexample
48235
48236*/
48237
48238void pushDialog( GuiControl ctrl, int layer=0, bool center=false);
48239/*!
48240@brief Get the GuiControl which is being used as the content.
48241
48242@tsexample
48243Canvas.getContent();
48244@endtsexample
48245
48246@return ID of current content control*/
48247int getContent();
48248/*!
48249@brief Set the content of the canvas to a specified control.
48250
48251@param ctrl ID or name of GuiControl to set content to
48252
48253@tsexample
48254Canvas.setContent(PlayGui);
48255@endtsexample*/
48256void setContent( GuiControl ctrl );
48257/*!
48258@brief Turns on the mouse cursor.
48259
48260@tsexample
48261Canvas.cursorOn();
48262@endtsexample*/
48263void cursorOn();
48264/*!
48265@brief Turns on the mouse off.
48266
48267@tsexample
48268Canvas.cursorOff();
48269@endtsexample*/
48270void cursorOff();
48271/*!
48272@brief Sets the cursor for the canvas.
48273
48274@param cursor Name of the GuiCursor to use
48275
48276@tsexample
48277Canvas.setCursor("DefaultCursor");
48278@endtsexample*/
48279void setCursor( GuiCursor cursor );
48280/*!
48281@brief This turns on/off front-buffer rendering.
48282
48283@param enable True if all rendering should be done to the front buffer
48284
48285@tsexample
48286Canvas.renderFront(false);
48287@endtsexample*/
48288void renderFront( bool enable );
48289/*!
48290@brief Enable rendering of the cursor.
48291
48292@tsexample
48293Canvas.showCursor();
48294@endtsexample*/
48295void showCursor();
48296/*!
48297@brief Disable rendering of the cursor.
48298
48299@tsexample
48300Canvas.hideCursor();
48301@endtsexample*/
48302void hideCursor();
48303/*!
48304@brief Determines if mouse cursor is enabled.
48305
48306@tsexample
48307// Is cursor on?
48308if(Canvas.isCursorOn())
48309  echo("Canvas cursor is on");
48310@endtsexample
48311
48312@return Returns true if the cursor is on.*/
48313bool isCursorOn();
48314/*!
48315@brief Determines if mouse cursor is rendering.
48316
48317@tsexample
48318// Is cursor rendering?
48319if(Canvas.isCursorShown())
48320  echo("Canvas cursor is rendering");
48321@endtsexample
48322
48323@return Returns true if the cursor is rendering.*/
48324bool isCursorShown();
48325/*!
48326@brief Force canvas to redraw.
48327If the elapsed time is greater than the time since the last paint then the repaint will be skipped.
48328@param elapsedMS The optional elapsed time in milliseconds.
48329
48330@tsexample
48331Canvas.repaint();
48332@endtsexample*/
48333void repaint( int elapsedMS=0 );
48334/*!
48335@brief Reset the update regions for the canvas.
48336
48337@tsexample
48338Canvas.reset();
48339@endtsexample*/
48340void reset();
48341/*!
48342@brief Get the current position of the cursor in screen-space. Note that this position might be outside the Torque window. If you want to get the position within the Canvas, call screenToClient on the result.
48343
48344@see Canvas::screenToClient()
48345
48346@param param Description
48347
48348@tsexample
48349%cursorPos = Canvas.getCursorPos();
48350@endtsexample
48351
48352@return Screen coordinates of mouse cursor, in format "X Y"*/
48353Point2I getCursorPos();
48354/*!
48355@brief Gets the gui control under the mouse.
48356
48357@tsexample
48358%underMouse = Canvas.getMouseControl();
48359@endtsexample
48360
48361@return ID of the gui control, if one was found. NULL otherwise*/
48362int getMouseControl();
48363/*!
48364@brief Returns the dimensions of the canvas
48365
48366@tsexample
48367%extent = Canvas.getExtent();
48368@endtsexample
48369
48370@return Width and height of canvas. Formatted as numerical values in a single string "# #"*/
48371Point2I getExtent();
48372/*!
48373@brief Change the title of the OS window.
48374
48375@param newTitle String containing the new name
48376
48377@tsexample
48378Canvas.setWindowTitle("Documentation Rocks!");
48379@endtsexample*/
48380void setWindowTitle( string newTitle );
48381/*!
48382@brief Find the first monitor index that matches the given name.
48383
48384The actual match algorithm depends on the implementation.
48385@param name The name to search for.
48386
48387@return The number of monitors attached to the system, including the default monoitor.*/
48388int findFirstMatchingMonitor( string name );
48389/*!
48390@brief Gets the number of monitors attached to the system.
48391
48392@return The number of monitors attached to the system, including the default monoitor.*/
48393int getMonitorCount();
48394/*!
48395@brief Gets the name of the requested monitor.
48396
48397@param index The monitor index.
48398
48399@return The name of the requested monitor.*/
48400string getMonitorName( int index );
48401/*!
48402@brief Gets the region of the requested monitor.
48403
48404@param index The monitor index.
48405
48406@return The rectangular region of the requested monitor.*/
48407RectI getMonitorRect( int index );
48408/*!
48409@brief Use this function to get the usable desktop area represented by a display, with the primary display located at 0,0.
48410
48411This is the same area as Canvas.getMonitorRect() reports, but with portions reserved by the system removed. For example, on Apple Mac OS X, this subtracts the area occupied by the menu bar and dock.
48412Setting a window to be fullscreen generally bypasses these unusable areas, so these are good guidelines for the maximum space available to a non - fullscreen window.@param index The monitor index.
48413
48414@return The rectangular region of the requested monitor.*/
48415RectI getMonitorUsableRect( int index );
48416/*!
48417@brief Gets the number of video modes available on the selected monitor.
48418
48419
48420*/
48421int getMonitorModeCount( int monitorIndex=0 );
48422/*!
48423@brief Gets a video mode string from the selected monitor.
48424
48425
48426*/
48427string getMonitorMode( int monitorIndex, int modeIndex=0 );
48428/*!
48429@brief Gets the current desktop mode for the selected monitor.
48430
48431
48432*/
48433string getMonitorDesktopMode( int monitorIndex=0 );
48434/*!
48435@brief Gets the current screen mode as a string.
48436
48437The return string will contain 5 values (width, height, fullscreen, bitdepth, refreshRate). You will need to parse out each one for individual use.
48438
48439@tsexample
48440%screenWidth = getWord(Canvas.getVideoMode(), 0);
48441%screenHeight = getWord(Canvas.getVideoMode(), 1);
48442%isFullscreen = getWord(Canvas.getVideoMode(), 2);
48443%bitdepth = getWord(Canvas.getVideoMode(), 3);
48444%refreshRate = getWord(Canvas.getVideoMode(), 4);
48445@endtsexample
48446
48447@return String formatted with screen width, screen height, screen mode, bit depth, and refresh rate.*/
48448string getVideoMode();
48449/*!
48450@brief Gets the number of modes available on this device.
48451
48452@param param Description
48453
48454@tsexample
48455%modeCount = Canvas.getModeCount()
48456@endtsexample
48457
48458@return The number of video modes supported by the device*/
48459int getModeCount();
48460/*!
48461@brief Gets information on the specified mode of this device.
48462
48463@param modeId Index of the mode to get data from.
48464@return A video mode string given an adapter and mode index.
48465
48466@see GuiCanvas::getVideoMode()*/
48467string getMode( int modeId );
48468/*!
48469@brief toggle canvas from fullscreen to windowed mode or back.
48470
48471@tsexample
48472// If we are in windowed mode, the following will put is in fullscreen
48473Canvas.toggleFullscreen();@endtsexample*/
48474void toggleFullscreen();
48475/*!
48476@brief Translate a coordinate from canvas window-space to screen-space.
48477
48478@param coordinate The coordinate in window-space.
48479@return The given coordinate translated to screen-space.*/
48480Point2I clientToScreen( Point2I coordinate );
48481/*!
48482@brief Translate a coordinate from screen-space to canvas window-space.
48483
48484@param coordinate The coordinate in screen-space.
48485@return The given coordinate translated to window-space.*/
48486Point2I screenToClient( Point2I coordinate );
48487/*!
48488@brief Get the current position of the platform window associated with the canvas.
48489
48490@return The window position of the canvas in screen-space.*/
48491Point2I getWindowPosition();
48492/*!
48493@brief Set the position of the platform window associated with the canvas.
48494
48495@param position The new position of the window in screen-space.*/
48496void setWindowPosition( Point2I position );
48497/*!
48498@brief Is this canvas currently fullscreen?
48499
48500*/
48501bool isFullscreen();
48502/*!
48503@brief minimize this canvas' window.
48504
48505*/
48506void minimizeWindow();
48507bool isMinimized();
48508bool isMaximized();
48509/*!
48510@brief maximize this canvas' window.
48511
48512*/
48513void maximizeWindow();
48514/*!
48515@brief restore this canvas' window.
48516
48517*/
48518void restoreWindow();
48519/*!
48520@brief Claim OS input focus for this canvas' window.
48521
48522*/
48523void setFocus();
48524/*!
48525@brief Translate a coordinate from canvas window-space to screen-space.
48526
48527@param coordinate The coordinate in window-space.
48528@return The given coordinate translated to screen-space.*/
48529void setMenuBar( GuiControl menu );
48530/*!
48531@brief Change the video mode of this canvas. This method has the side effect of setting the $pref::Video::mode to the new values.
48532
48533
48534\param width The screen width to set.
48535\param height The screen height to set.
48536\param fullscreen Specify true to run fullscreen or false to run in a window
48537\param bitDepth [optional] The desired bit-depth. Defaults to the current setting. This parameter is ignored if you are running in a window.
48538\param refreshRate [optional] The desired refresh rate. Defaults to the current setting. This parameter is ignored if you are running in a window\param antialiasLevel [optional] The level of anti-aliasing to apply 0 = none*/
48539void setVideoMode( uint width, uint height, bool fullscreen=false, uint bitDepth=0, uint refreshRate=0, uint antialiasLevel=0 );
48540void showWindow();
48541void hideWindow();
48542void cursorClick( int buttonId, bool isDown );
48543void cursorNudge( float x, float y );
48544void resetVideoMode();
48545
48546/*! @name Callbacks
48547@{ */
48548/// @}
48549
48550
48551/*! @name Mouse Handling
48552@{ */
48553/*!
48554@brief Deal with mouse buttons, even if the cursor is hidden.
48555*/
48556bool alwaysHandleMouseButtons;
48557/// @}
48558
48559
48560/*! @name Canvas Rendering
48561@{ */
48562/*!
48563@brief The number of GFX fences to use.
48564*/
48565int numFences;
48566/*!
48567@brief Controls if the canvas window is rendered or not.
48568*/
48569bool displayWindow;
48570/// @}
48571
48572
48573/*! @name Layout
48574@{ */
48575/// @}
48576
48577
48578/*! @name Control
48579@{ */
48580/// @}
48581
48582
48583/*! @name ToolTip
48584@{ */
48585/// @}
48586
48587
48588/*! @name Editing
48589@{ */
48590/// @}
48591
48592
48593/*! @name Localization
48594@{ */
48595/// @}
48596
48597
48598/*! @name Ungrouped
48599@{ */
48600/// @}
48601
48602
48603/*! @name Object
48604@{ */
48605/// @}
48606
48607
48608/*! @name Editing
48609@{ */
48610/// @}
48611
48612
48613/*! @name Persistence
48614@{ */
48615/// @}
48616
48617};
48618
48619/*! UNDOCUMENTED!
48620@ingroup UNDOCUMENTED
48621 */
48622class GuiOffscreenCanvas : public GuiCanvas {
48623public:
48624void resetTarget();
48625void markDirty();
48626
48627/*! @name Callbacks
48628@{ */
48629/// @}
48630
48631/*!
48632*/
48633Point2I targetSize;
48634/*!
48635*/
48636GFXFormat targetFormat;
48637/*!
48638*/
48639string targetName;
48640/*!
48641*/
48642bool dynamicTarget;
48643/*!
48644*/
48645bool useDepth;
48646
48647/*! @name Mouse Handling
48648@{ */
48649/// @}
48650
48651
48652/*! @name Canvas Rendering
48653@{ */
48654/// @}
48655
48656
48657/*! @name Layout
48658@{ */
48659/// @}
48660
48661
48662/*! @name Control
48663@{ */
48664/// @}
48665
48666
48667/*! @name ToolTip
48668@{ */
48669/// @}
48670
48671
48672/*! @name Editing
48673@{ */
48674/// @}
48675
48676
48677/*! @name Localization
48678@{ */
48679/// @}
48680
48681
48682/*! @name Ungrouped
48683@{ */
48684/// @}
48685
48686
48687/*! @name Object
48688@{ */
48689/// @}
48690
48691
48692/*! @name Editing
48693@{ */
48694/// @}
48695
48696
48697/*! @name Persistence
48698@{ */
48699/// @}
48700
48701};
48702
48703/*!
48704@brief A control which adds several reactions to other GUIs via callbacks.
48705
48706GuiScriptNotifyCtrl does not exist to render anything. When parented or made a child of other controls, you can toggle flags on or off to make use of its specialized callbacks. Normally these callbacks are used as utility functions by the GUI Editor, or other container classes. However, for very fancy GUI work where controls interact with each other constantly, this is a handy utility to make use of.
48707
48708 @tsexample
48709// Common member fields left out for sake of example
48710new GuiScriptNotifyCtrl()
48711{
48712   onChildAdded = "0";
48713   onChildRemoved = "0";
48714   onChildResized = "0";
48715   onParentResized = "0";
48716};
48717@endtsexample
48718
48719@ingroup GuiUtil
48720
48721*/
48722class GuiScriptNotifyCtrl : public GuiControl {
48723public:
48724
48725/*! @name Callbacks
48726@{ */
48727/*!
48728@brief Called when this GUI is resized.
48729
48730
48731@param ID Unique object ID assigned when created (%this in script).
48732*/
48733void onResize( SimObjectId ID );
48734/*!
48735@brief Called when a child is added to this GUI.
48736
48737
48738@param ID Unique object ID assigned when created (%this in script).
48739@param childID Unique object ID of child being added.
48740*/
48741void onChildAdded( SimObjectId ID, SimObjectId childID );
48742/*!
48743@brief Called when a child is removed from this GUI.
48744
48745
48746@param ID Unique object ID assigned when created (%this in script).
48747@param childID Unique object ID of child being removed.
48748*/
48749void onChildRemoved( SimObjectId ID, SimObjectId childID );
48750/*!
48751@brief Called when a child is of this GUI is being resized.
48752
48753
48754@param ID Unique object ID assigned when created (%this in script).
48755@param childID Unique object ID of child being resized.
48756*/
48757void onChildResized( SimObjectId ID, SimObjectId childID );
48758/*!
48759@brief Called when this GUI's parent is resized.
48760
48761
48762@param ID Unique object ID assigned when created (%this in script).
48763*/
48764void onParentResized( SimObjectId ID );
48765/*!
48766@brief Called when this GUI loses focus.
48767
48768
48769@param ID Unique object ID assigned when created (%this in script).
48770*/
48771void onLoseFirstResponder( SimObjectId ID );
48772/*!
48773@brief Called when this GUI gains focus.
48774
48775
48776@param ID Unique object ID assigned when created (%this in script).
48777*/
48778void onGainFirstResponder( SimObjectId ID );
48779/// @}
48780
48781
48782/*! @name Callbacks
48783@{ */
48784/*!
48785@brief Enables/disables onChildAdded callback
48786*/
48787bool notifyOnChildAdded;
48788/*!
48789@brief Enables/disables onChildRemoved callback
48790*/
48791bool notifyOnChildRemoved;
48792/*!
48793@brief Enables/disables onChildResized callback
48794*/
48795bool notifyOnChildResized;
48796/*!
48797@brief Enables/disables onParentResized callback
48798*/
48799bool notifyOnParentResized;
48800/*!
48801@brief Enables/disables onResize callback
48802*/
48803bool notifyOnResize;
48804/*!
48805@brief Enables/disables onLoseFirstResponder callback
48806*/
48807bool notifyOnLoseFirstResponder;
48808/*!
48809@brief Enables/disables onGainFirstResponder callback
48810*/
48811bool notifyOnGainFirstResponder;
48812/// @}
48813
48814
48815/*! @name Layout
48816@{ */
48817/// @}
48818
48819
48820/*! @name Control
48821@{ */
48822/// @}
48823
48824
48825/*! @name ToolTip
48826@{ */
48827/// @}
48828
48829
48830/*! @name Editing
48831@{ */
48832/// @}
48833
48834
48835/*! @name Localization
48836@{ */
48837/// @}
48838
48839
48840/*! @name Ungrouped
48841@{ */
48842/// @}
48843
48844
48845/*! @name Object
48846@{ */
48847/// @}
48848
48849
48850/*! @name Editing
48851@{ */
48852/// @}
48853
48854
48855/*! @name Persistence
48856@{ */
48857/// @}
48858
48859};
48860
48861/*!
48862@brief This is a control that will render a specified bitmap or a bitmap specified in a referenced variable.
48863
48864This control allows you to either set a bitmap with the "bitmap" field or with the setBitmap method.  You can also choose to reference a variable in the "variable" field such as "$image" and then set "useVariable" to true.  This will cause it to synchronize the variable with the bitmap displayed (if the variable holds a valid image).  You can then change the variable and effectively changed the displayed image.
48865
48866@tsexample
48867$image = "anotherbackground.png";
48868new GuiChunkedBitmapCtrl(ChunkedBitmap)
48869{
48870   bitmap = "background.png";
48871   variable = "$image";
48872   useVariable = false;
48873}
48874
48875// This will result in the control rendering "background.png"
48876// If we now set the useVariable to true it will now render "anotherbackground.png"
48877ChunkedBitmap.useVariable = true;
48878@endtsexample
48879
48880@see GuiControl::variable
48881
48882@ingroup GuiImages
48883
48884*/
48885class GuiChunkedBitmapCtrl : public GuiControl {
48886public:
48887/*!
48888@brief Set the image rendered in this control.
48889
48890@param filename The image name you want to set
48891@tsexample
48892ChunkedBitmap.setBitmap("images/background.png");@endtsexample*/
48893void setBitmap( string filename );
48894
48895/*! @name Callbacks
48896@{ */
48897/// @}
48898
48899
48900/*! @name GuiChunkedBitmapCtrl
48901@{ */
48902/*!
48903@brief This is the bitmap to render to the control.
48904*/
48905filename bitmap;
48906/*!
48907@brief This decides whether to use the "bitmap" file or a bitmap stored in "variable"
48908*/
48909bool useVariable;
48910/*!
48911@brief This is no longer in use
48912*/
48913bool tile;
48914/// @}
48915
48916
48917/*! @name Layout
48918@{ */
48919/// @}
48920
48921
48922/*! @name Control
48923@{ */
48924/// @}
48925
48926
48927/*! @name ToolTip
48928@{ */
48929/// @}
48930
48931
48932/*! @name Editing
48933@{ */
48934/// @}
48935
48936
48937/*! @name Localization
48938@{ */
48939/// @}
48940
48941
48942/*! @name Ungrouped
48943@{ */
48944/// @}
48945
48946
48947/*! @name Object
48948@{ */
48949/// @}
48950
48951
48952/*! @name Editing
48953@{ */
48954/// @}
48955
48956
48957/*! @name Persistence
48958@{ */
48959/// @}
48960
48961};
48962
48963/*!
48964@brief A GUI control which renders a black square over a bitmap image. The black square will fade out, then fade back in after a determined time.
48965This control is especially useful for transitions and splash screens.
48966
48967@tsexample
48968new GuiFadeinBitmapCtrl()
48969   {
48970      fadeinTime = "1000";
48971      waitTime = "2000";
48972      fadeoutTime = "1000";
48973      done = "1";
48974      // Additional GUI properties that are not specific to GuiFadeinBitmapCtrl have been omitted from this example.
48975   };
48976@endtsexample
48977
48978@see GuiBitmapCtrl
48979
48980@ingroup GuiCore
48981
48982*/
48983class GuiFadeinBitmapCtrl : public GuiBitmapCtrl {
48984public:
48985
48986/*! @name Callbacks
48987@{ */
48988/*!
48989@brief Informs the script level that this object received a Click event from the cursor or keyboard.
48990
48991@tsexample
48992GuiFadeInBitmapCtrl::click(%this)
48993   {
48994      // Code to run when click occurs
48995   }
48996@endtsexample
48997
48998@see GuiCore*/
48999void click();
49000/*!
49001@brief Informs the script level that this object has completed is fade cycle.
49002
49003@tsexample
49004GuiFadeInBitmapCtrl::onDone(%this)
49005   {
49006      // Code to run when the fade cycle completes
49007   }
49008@endtsexample
49009
49010@see GuiCore*/
49011void onDone();
49012/// @}
49013
49014
49015/*! @name Fading
49016@{ */
49017/*!
49018@brief Color to fade in from and fade out to.
49019*/
49020LinearColorF fadeColor;
49021/*!
49022@brief Milliseconds for the bitmap to fade in.
49023*/
49024int fadeInTime;
49025/*!
49026@brief Milliseconds to wait after fading in before fading out the bitmap.
49027*/
49028int waitTime;
49029/*!
49030@brief Milliseconds for the bitmap to fade out.
49031*/
49032int fadeOutTime;
49033/*!
49034@brief Easing curve for fade-in.
49035*/
49036EaseF fadeInEase;
49037/*!
49038@brief Easing curve for fade-out.
49039*/
49040EaseF fadeOutEase;
49041/*!
49042@brief Whether the fade cycle has finished running.
49043*/
49044bool done;
49045/// @}
49046
49047
49048/*! @name Bitmap
49049@{ */
49050/// @}
49051
49052
49053/*! @name Layout
49054@{ */
49055/// @}
49056
49057
49058/*! @name Control
49059@{ */
49060/// @}
49061
49062
49063/*! @name ToolTip
49064@{ */
49065/// @}
49066
49067
49068/*! @name Editing
49069@{ */
49070/// @}
49071
49072
49073/*! @name Localization
49074@{ */
49075/// @}
49076
49077
49078/*! @name Ungrouped
49079@{ */
49080/// @}
49081
49082
49083/*! @name Object
49084@{ */
49085/// @}
49086
49087
49088/*! @name Editing
49089@{ */
49090/// @}
49091
49092
49093/*! @name Persistence
49094@{ */
49095/// @}
49096
49097};
49098
49099/*!
49100@brief A chat HUD control that displays messages from a MessageVector.
49101
49102This renders messages from a MessageVector; the important thing here is that the MessageVector holds all the messages we care about, while we can destroy and create these GUI controls as needed.
49103
49104@tsexample
49105// Declare ChatHud, which is what will display the actual chat from a MessageVector
49106new GuiMessageVectorCtrl(ChatHud) {
49107   profile = "ChatHudMessageProfile";
49108   horizSizing = "width";
49109   vertSizing = "height";
49110   position = "1 1";
49111   extent = "252 16";
49112   minExtent = "8 8";
49113   visible = "1";
49114   helpTag = "0";
49115   lineSpacing = "0";
49116   lineContinuedIndex = "10";
49117   matchColor = "0 0 255 255";
49118   maxColorIndex = "5";
49119};
49120
49121// All messages are stored in this HudMessageVector, the actual
49122// MainChatHud only displays the contents of this vector.
49123new MessageVector(HudMessageVector);
49124
49125// Attach the MessageVector to the chat control
49126chatHud.attach(HudMessageVector);
49127@endtsexample
49128
49129@see MessageVector for more details on how this is used
49130@ingroup GuiUtil
49131
49132*/
49133class GuiMessageVectorCtrl : public GuiControl {
49134public:
49135/*!
49136@brief Push a line onto the back of the list.
49137
49138@param item The GUI element being pushed into the control
49139
49140@tsexample
49141// All messages are stored in this HudMessageVector, the actual
49142// MainChatHud only displays the contents of this vector.
49143new MessageVector(HudMessageVector);
49144
49145// Attach the MessageVector to the chat control
49146chatHud.attach(HudMessageVector);
49147@endtsexample
49148
49149@return Value*/
49150bool attach( MessageVector item );
49151/*!
49152@brief Stop listing messages from the MessageVector previously attached to, if any.
49153
49154Detailed description
49155
49156@param param Description
49157
49158@tsexample
49159// Deatch the MessageVector from HudMessageVector
49160// HudMessageVector will no longer render the text
49161chatHud.detach();
49162@endtsexample*/
49163void detach();
49164
49165/*! @name Callbacks
49166@{ */
49167/// @}
49168
49169/*!
49170*/
49171int lineSpacing;
49172/*!
49173*/
49174int lineContinuedIndex;
49175/*!
49176*/
49177string allowedMatches[ 16 ];
49178/*!
49179*/
49180ColorI matchColor;
49181/*!
49182*/
49183int maxColorIndex;
49184
49185/*! @name Layout
49186@{ */
49187/// @}
49188
49189
49190/*! @name Control
49191@{ */
49192/// @}
49193
49194
49195/*! @name ToolTip
49196@{ */
49197/// @}
49198
49199
49200/*! @name Editing
49201@{ */
49202/// @}
49203
49204
49205/*! @name Localization
49206@{ */
49207/// @}
49208
49209
49210/*! @name Ungrouped
49211@{ */
49212/// @}
49213
49214
49215/*! @name Object
49216@{ */
49217/// @}
49218
49219
49220/*! @name Editing
49221@{ */
49222/// @}
49223
49224
49225/*! @name Persistence
49226@{ */
49227/// @}
49228
49229};
49230
49231/*!
49232@brief A horizontal progress bar rendered from a repeating image.
49233
49234This class is used give progress feedback to the user.  Unlike GuiProgressCtrl which simply renders a filled rectangle, GuiProgressBitmapCtrl renders the bar using a bitmap.
49235
49236This bitmap can either be simple, plain image which is then stretched into the current extents of the bar as it fills up or it can be a bitmap array with three entries.  In the case of a bitmap array, the first entry in the array is used to render the left cap of the bar and the third entry in the array is used to render the right cap of the bar.  The second entry is streched in-between the two caps.
49237
49238@tsexample
49239// This example shows one way to break down a long-running computation into phases
49240// and incrementally update a progress bar between the phases.
49241
49242new GuiProgressBitmapCtrl( Progress )
49243{
49244   bitmap = "core/art/gui/images/loading";
49245   extent = "300 50";
49246   position = "100 100";
49247};
49248
49249// Put the control on the canvas.
49250%wrapper = new GuiControl();
49251%wrapper.addObject( Progress );
49252Canvas.pushDialog( %wrapper );
49253
49254// Start the computation.
49255schedule( 1, 0, "phase1" );
49256
49257function phase1()
49258{
49259   Progress.setValue( 0 );
49260
49261   // Perform some computation.
49262   //...
49263
49264   // Update progress.
49265   Progress.setValue( 0.25 );
49266
49267   // Schedule next phase.  Don't call directly so engine gets a change to run refresh.
49268   schedule( 1, 0, "phase2" );
49269}
49270
49271function phase2()
49272{
49273   // Perform some computation.
49274   //...
49275
49276   // Update progress.
49277   Progress.setValue( 0.7 );
49278
49279   // Schedule next phase.  Don't call directly so engine gets a change to run refresh.
49280   schedule( 1, 0, "phase3" );
49281}
49282
49283function phase3()
49284{
49285   // Perform some computation.
49286   //...
49287
49288   // Update progress.
49289   Progress.setValue( 0.9 );
49290
49291   // Schedule next phase.  Don't call directly so engine gets a change to run refresh.
49292   schedule( 1, 0, "phase4" );
49293}
49294
49295function phase4()
49296{
49297   // Perform some computation.
49298   //...
49299
49300   // Final update of progress.
49301   Progress.setValue( 1.0 );
49302}
49303@endtsexample
49304
49305@see GuiProgressCtrl
49306
49307@ingroup GuiValues
49308*/
49309class GuiProgressBitmapCtrl : public GuiTextCtrl {
49310public:
49311/*!
49312@brief Set the bitmap to use for rendering the progress bar.
49313
49314
49315@param filename ~Path to the bitmap file.
49316
49317@note Directly assign to #bitmap rather than using this method.
49318
49319@see GuiProgressBitmapCtrl::setBitmap*/
49320void setBitmap( string filename );
49321
49322/*! @name Callbacks
49323@{ */
49324/// @}
49325
49326/*!
49327@brief ~Path to the bitmap file to use for rendering the progress bar.
49328
49329
49330If the profile assigned to the control already has a bitmap assigned, this property need not be set in which case the bitmap from the profile is used.
49331*/
49332filename bitmap;
49333
49334/*! @name Layout
49335@{ */
49336/// @}
49337
49338
49339/*! @name Layout
49340@{ */
49341/// @}
49342
49343
49344/*! @name Control
49345@{ */
49346/// @}
49347
49348
49349/*! @name ToolTip
49350@{ */
49351/// @}
49352
49353
49354/*! @name Editing
49355@{ */
49356/// @}
49357
49358
49359/*! @name Localization
49360@{ */
49361/// @}
49362
49363
49364/*! @name Ungrouped
49365@{ */
49366/// @}
49367
49368
49369/*! @name Object
49370@{ */
49371/// @}
49372
49373
49374/*! @name Editing
49375@{ */
49376/// @}
49377
49378
49379/*! @name Persistence
49380@{ */
49381/// @}
49382
49383};
49384
49385/*!
49386@brief Used to overlaps a 'hot region' where you want to catch inputs with and have specific events occur based on individual callbacks.
49387
49388Mouse event callbacks supported by this control are: onMouseUp, onMouseDown, onMouseMove, onMouseDragged, onMouseEnter, onMouseLeave,
49389onRightMouseDown, onRightMouseUp and onRightMouseDragged.
49390
49391@tsexample
49392new GuiMouseEventCtrl()
49393{
49394   lockMouse = "0";
49395   //Properties not specific to this control have been omitted from this example.
49396};
49397@endtsexample
49398
49399@see GuiControl
49400
49401@ingroup GuiCore
49402
49403*/
49404class GuiMouseEventCtrl : public GuiControl {
49405public:
49406
49407/*! @name Callbacks
49408@{ */
49409/*!
49410@brief Callback that occurs whenever the mouse is pressed down while in this control.
49411
49412@param modifier Key that was pressed during this callback. Values are:
49413
49414$EventModifier::RSHIFT
49415
49416$EventModifier::SHIFT
49417
49418$EventModifier::LCTRL
49419
49420$EventModifier::RCTRL
49421
49422$EventModifier::CTRL
49423
49424$EventModifier::CTRL
49425
49426$EventModifier::RALT
49427
49428$EventModifier::ALT
49429
49430@param mousePoint X/Y location of the mouse point
49431@param mouseClickCount How many mouse clicks have occured for this event
49432
49433@tsexample
49434// Mouse was pressed down in this control, causing the callback
49435GuiMouseEventCtrl::onMouseDown(%this,%modifier,%mousePoint,%mouseClickCount)
49436{
49437   // Code to call when a mouse event occurs.
49438}
49439@endtsexample
49440
49441@see GuiControl*/
49442void onMouseDown( int modifier, Point2I mousePoint, int mouseClickCount );
49443/*!
49444@brief Callback that occurs whenever the mouse is released while in this control.
49445
49446@param modifier Key that was pressed during this callback. Values are:
49447
49448$EventModifier::RSHIFT
49449
49450$EventModifier::SHIFT
49451
49452$EventModifier::LCTRL
49453
49454$EventModifier::RCTRL
49455
49456$EventModifier::CTRL
49457
49458$EventModifier::CTRL
49459
49460$EventModifier::RALT
49461
49462$EventModifier::ALT
49463
49464@param mousePoint X/Y location of the mouse point
49465@param mouseClickCount How many mouse clicks have occured for this event
49466
49467@tsexample
49468// Mouse was released in this control, causing the callback
49469GuiMouseEventCtrl::onMouseUp(%this,%modifier,%mousePoint,%mouseClickCount)
49470{
49471   // Code to call when a mouse event occurs.
49472}
49473@endtsexample
49474
49475@see GuiControl*/
49476void onMouseUp( int modifier, Point2I mousePoint, int mouseClickCount );
49477/*!
49478@brief Callback that occurs whenever the mouse is moved (without dragging) while in this control.
49479
49480@param modifier Key that was pressed during this callback. Values are:
49481
49482$EventModifier::RSHIFT
49483
49484$EventModifier::SHIFT
49485
49486$EventModifier::LCTRL
49487
49488$EventModifier::RCTRL
49489
49490$EventModifier::CTRL
49491
49492$EventModifier::CTRL
49493
49494$EventModifier::RALT
49495
49496$EventModifier::ALT
49497
49498@param mousePoint X/Y location of the mouse point
49499@param mouseClickCount How many mouse clicks have occured for this event
49500
49501@tsexample
49502// Mouse was moved in this control, causing the callback
49503GuiMouseEventCtrl::onMouseMove(%this,%modifier,%mousePoint,%mouseClickCount)
49504{
49505   // Code to call when a mouse event occurs.
49506}
49507@endtsexample
49508
49509@see GuiControl*/
49510void onMouseMove( int modifier, Point2I mousePoint, int mouseClickCount );
49511/*!
49512@brief Callback that occurs whenever the mouse is dragged while in this control.
49513
49514@param modifier Key that was pressed during this callback. Values are:
49515
49516$EventModifier::RSHIFT
49517
49518$EventModifier::SHIFT
49519
49520$EventModifier::LCTRL
49521
49522$EventModifier::RCTRL
49523
49524$EventModifier::CTRL
49525
49526$EventModifier::CTRL
49527
49528$EventModifier::RALT
49529
49530$EventModifier::ALT
49531
49532@param mousePoint X/Y location of the mouse point
49533@param mouseClickCount How many mouse clicks have occured for this event
49534
49535@tsexample
49536// Mouse was dragged in this control, causing the callback
49537GuiMouseEventCtrl::onMouseDragged(%this,%modifier,%mousePoint,%mouseClickCount)
49538{
49539   // Code to call when a mouse event occurs.
49540}
49541@endtsexample
49542
49543@see GuiControl*/
49544void onMouseDragged( int modifier, Point2I mousePoint, int mouseClickCount );
49545/*!
49546@brief Callback that occurs whenever the mouse enters this control.
49547
49548@param modifier Key that was pressed during this callback. Values are:
49549
49550$EventModifier::RSHIFT
49551
49552$EventModifier::SHIFT
49553
49554$EventModifier::LCTRL
49555
49556$EventModifier::RCTRL
49557
49558$EventModifier::CTRL
49559
49560$EventModifier::CTRL
49561
49562$EventModifier::RALT
49563
49564$EventModifier::ALT
49565
49566@param mousePoint X/Y location of the mouse point
49567@param mouseClickCount How many mouse clicks have occured for this event
49568
49569@tsexample
49570// Mouse entered this control, causing the callback
49571GuiMouseEventCtrl::onMouseEnter(%this,%modifier,%mousePoint,%mouseClickCount)
49572{
49573   // Code to call when a mouse event occurs.
49574}
49575@endtsexample
49576
49577@see GuiControl*/
49578void onMouseEnter( int modifier, Point2I mousePoint, int mouseClickCount );
49579/*!
49580@brief Callback that occurs whenever the mouse leaves this control.
49581
49582@param modifier Key that was pressed during this callback. Values are:
49583
49584$EventModifier::RSHIFT
49585
49586$EventModifier::SHIFT
49587
49588$EventModifier::LCTRL
49589
49590$EventModifier::RCTRL
49591
49592$EventModifier::CTRL
49593
49594$EventModifier::CTRL
49595
49596$EventModifier::RALT
49597
49598$EventModifier::ALT
49599
49600@param mousePoint X/Y location of the mouse point
49601@param mouseClickCount How many mouse clicks have occured for this event
49602
49603@tsexample
49604// Mouse left this control, causing the callback
49605GuiMouseEventCtrl::onMouseLeave(%this,%modifier,%mousePoint,%mouseClickCount)
49606{
49607   // Code to call when a mouse event occurs.
49608}
49609@endtsexample
49610
49611@see GuiControl*/
49612void onMouseLeave( int modifier, Point2I mousePoint, int mouseClickCount );
49613/*!
49614@brief Callback that occurs whenever the right mouse button is pressed while in this control.
49615
49616@param modifier Key that was pressed during this callback. Values are:
49617
49618$EventModifier::RSHIFT
49619
49620$EventModifier::SHIFT
49621
49622$EventModifier::LCTRL
49623
49624$EventModifier::RCTRL
49625
49626$EventModifier::CTRL
49627
49628$EventModifier::CTRL
49629
49630$EventModifier::RALT
49631
49632$EventModifier::ALT
49633
49634@param mousePoint X/Y location of the mouse point
49635@param mouseClickCount How many mouse clicks have occured for this event
49636
49637@tsexample
49638// Right mouse button was pressed in this control, causing the callback
49639GuiMouseEventCtrl::onRightMouseDown(%this,%modifier,%mousePoint,%mouseClickCount)
49640{
49641   // Code to call when a mouse event occurs.
49642}
49643@endtsexample
49644
49645@see GuiControl*/
49646void onRightMouseDown( int modifier, Point2I mousePoint, int mouseClickCount );
49647/*!
49648@brief Callback that occurs whenever the right mouse button is released while in this control.
49649
49650@param modifier Key that was pressed during this callback. Values are:
49651
49652$EventModifier::RSHIFT
49653
49654$EventModifier::SHIFT
49655
49656$EventModifier::LCTRL
49657
49658$EventModifier::RCTRL
49659
49660$EventModifier::CTRL
49661
49662$EventModifier::CTRL
49663
49664$EventModifier::RALT
49665
49666$EventModifier::ALT
49667
49668@param mousePoint X/Y location of the mouse point
49669@param mouseClickCount How many mouse clicks have occured for this event
49670
49671@tsexample
49672// Right mouse button was released in this control, causing the callback
49673GuiMouseEventCtrl::onRightMouseUp(%this,%modifier,%mousePoint,%mouseClickCount)
49674{
49675   // Code to call when a mouse event occurs.
49676}
49677@endtsexample
49678
49679@see GuiControl*/
49680void onRightMouseUp( int modifier, Point2I mousePoint, int mouseClickCount );
49681/*!
49682@brief Callback that occurs whenever the mouse is dragged in this control while the right mouse button is pressed.
49683
49684@param modifier Key that was pressed during this callback. Values are:
49685
49686$EventModifier::RSHIFT
49687
49688$EventModifier::SHIFT
49689
49690$EventModifier::LCTRL
49691
49692$EventModifier::RCTRL
49693
49694$EventModifier::CTRL
49695
49696$EventModifier::CTRL
49697
49698$EventModifier::RALT
49699
49700$EventModifier::ALT
49701
49702@param mousePoint X/Y location of the mouse point
49703@param mouseClickCount How many mouse clicks have occured for this event
49704
49705@tsexample
49706// Right mouse button was dragged in this control, causing the callback
49707GuiMouseEventCtrl::onRightMouseDragged(%this,%modifier,%mousePoint,%mouseClickCount)
49708{
49709   // Code to call when a mouse event occurs.
49710}
49711@endtsexample
49712
49713@see GuiControl*/
49714void onRightMouseDragged( int modifier, Point2I mousePoint, int mouseClickCount );
49715/// @}
49716
49717
49718/*! @name Input
49719@{ */
49720/*!
49721@brief Whether the control should lock the mouse between up and down button events.
49722*/
49723bool lockMouse;
49724/// @}
49725
49726
49727/*! @name Layout
49728@{ */
49729/// @}
49730
49731
49732/*! @name Control
49733@{ */
49734/// @}
49735
49736
49737/*! @name ToolTip
49738@{ */
49739/// @}
49740
49741
49742/*! @name Editing
49743@{ */
49744/// @}
49745
49746
49747/*! @name Localization
49748@{ */
49749/// @}
49750
49751
49752/*! @name Ungrouped
49753@{ */
49754/// @}
49755
49756
49757/*! @name Object
49758@{ */
49759/// @}
49760
49761
49762/*! @name Editing
49763@{ */
49764/// @}
49765
49766
49767/*! @name Persistence
49768@{ */
49769/// @}
49770
49771};
49772
49773/*!
49774@brief A control that locks the mouse and reports all keyboard input events to script.
49775
49776This is useful for implementing custom keyboard handling code, and most commonly used in Torque for a menu that allows a user to remap their in-game controls
49777
49778 @tsexample
49779new GuiInputCtrl(OptRemapInputCtrl)
49780{
49781   lockMouse = "0";
49782   position = "0 0";
49783   extent = "64 64";
49784   minExtent = "8 8";
49785   horizSizing = "center";
49786   vertSizing = "bottom";
49787   profile = "GuiInputCtrlProfile";
49788   visible = "1";
49789   active = "1";
49790   tooltipProfile = "GuiToolTipProfile";
49791   hovertime = "1000";
49792   isContainer = "0";
49793   canSave = "1";
49794   canSaveDynamicFields = "0";
49795};
49796@endtsexample
49797
49798@see GuiMouseEventCtrl
49799@ingroup GuiUtil
49800
49801*/
49802class GuiInputCtrl : public GuiMouseEventCtrl {
49803public:
49804
49805/*! @name Callbacks
49806@{ */
49807/*!
49808@brief Callback that occurs when an input is triggered on this control
49809
49810@param device The device type triggering the input, such as keyboard, mouse, etc
49811@param action The actual event occuring, such as a key or button
49812@param state True if the action is being pressed, false if it is being release*/
49813void onInputEvent( string device, string action, bool state );
49814/*!
49815@brief Callback that occurs when an axis event is triggered on this control
49816
49817@param device The device type triggering the input, such as mouse, joystick, gamepad, etc
49818@param action The ActionMap code for the axis
49819@param axisValue The current value of the axis*/
49820void onAxisEvent( string device, string action, float axisValue );
49821/// @}
49822
49823
49824/*! @name GuiInputCtrl
49825@{ */
49826/*!
49827@brief If true, onAxisEvent callbacks will be sent for SI_AXIS Move events (Default false).
49828*/
49829bool sendAxisEvents;
49830/*!
49831@brief If true, break events for all devices will generate callbacks (Default false).
49832*/
49833bool sendBreakEvents;
49834/*!
49835@brief If true, Make events will be sent for modifier keys (Default false).
49836*/
49837bool sendModifierEvents;
49838/// @}
49839
49840
49841/*! @name Input
49842@{ */
49843/// @}
49844
49845
49846/*! @name Layout
49847@{ */
49848/// @}
49849
49850
49851/*! @name Control
49852@{ */
49853/// @}
49854
49855
49856/*! @name ToolTip
49857@{ */
49858/// @}
49859
49860
49861/*! @name Editing
49862@{ */
49863/// @}
49864
49865
49866/*! @name Localization
49867@{ */
49868/// @}
49869
49870
49871/*! @name Ungrouped
49872@{ */
49873/// @}
49874
49875
49876/*! @name Object
49877@{ */
49878/// @}
49879
49880
49881/*! @name Editing
49882@{ */
49883/// @}
49884
49885
49886/*! @name Persistence
49887@{ */
49888/// @}
49889
49890};
49891
49892/*!
49893@brief Store a list of chat messages.
49894
49895This is responsible for managing messages which appear in the chat HUD, not the actual control rendered to the screen
49896
49897@tsexample
49898// Declare ChatHud, which is what will display the actual chat from a MessageVector
49899new GuiMessageVectorCtrl(ChatHud) {
49900   profile = "ChatHudMessageProfile";
49901   horizSizing = "width";
49902   vertSizing = "height";
49903   position = "1 1";
49904   extent = "252 16";
49905   minExtent = "8 8";
49906   visible = "1";
49907   helpTag = "0";
49908   lineSpacing = "0";
49909   lineContinuedIndex = "10";
49910   matchColor = "0 0 255 255";
49911   maxColorIndex = "5";
49912};
49913
49914// All messages are stored in this HudMessageVector, the actual
49915// MainChatHud only displays the contents of this vector.
49916new MessageVector(HudMessageVector);
49917
49918// Attach the MessageVector to the chat control
49919chatHud.attach(HudMessageVector);
49920@endtsexample
49921
49922@see GuiMessageVectorCtrl for more details on how this is used.@ingroup GuiUtil
49923
49924*/
49925class MessageVector : public SimObject {
49926public:
49927/*!
49928@brief Dump the message vector to a file with a header.
49929
49930@param filename Name and path of file to dump text to.
49931@param header Prefix information for write out
49932
49933@tsexample
49934// Arbitrary header data
49935%headerInfo = "Ars Moriendi Chat Log";
49936
49937// Dump the entire chat log to a text file
49938HudMessageVector.dump("./chatLog.txt", %headerInfo);
49939@endtsexample
49940
49941
49942*/
49943
49944void dump( string filename, string header);
49945/*!
49946@brief Dump the message vector to a file without a header.
49947
49948@param filename Name and path of file to dump text to.
49949@tsexample
49950// Dump the entire chat log to a text file
49951HudMessageVector.dump("./chatLog.txt");
49952@endtsexample
49953
49954
49955*/
49956
49957void dump( string filename);
49958/*!
49959@brief Clear all messages in the vector
49960
49961
49962@tsexample
49963HudMessageVector.clear();
49964@endtsexample
49965
49966*/
49967void clear();
49968/*!
49969@brief Push a line onto the back of the list.
49970
49971
49972@param msg Text that makes up the message
49973@param tag Numerical value associated with this message, useful for searching.
49974
49975@tsexample
49976// Add the message...
49977HudMessageVector.pushBackLine("Hello World", 0);
49978@endtsexample
49979
49980*/
49981void pushBackLine( string msg, int tag );
49982/*!
49983@brief Pop a line from the back of the list; destroys the line.
49984
49985
49986@tsexample
49987HudMessageVector.popBackLine();
49988@endtsexample
49989
49990@return False if there are no lines to pop (underflow), true otherwise*/
49991bool popBackLine();
49992/*!
49993@brief Push a line onto the front of the vector.
49994
49995
49996@param msg Text that makes up the message
49997@param tag Numerical value associated with this message, useful for searching.
49998
49999@tsexample
50000// Add the message...
50001HudMessageVector.pushFrontLine("Hello World", 0);
50002@endtsexample
50003
50004*/
50005void pushFrontLine( string msg, int tag );
50006/*!
50007@brief Pop a line from the front of the vector, destroying the line.
50008
50009
50010@tsexample
50011HudMessageVector.popFrontLine();
50012@endtsexample
50013
50014@return False if there are no lines to pop (underflow), true otherwise*/
50015bool popFrontLine();
50016/*!
50017@brief Push a line onto the back of the list.
50018
50019
50020@param msg Text that makes up the message
50021@param tag Numerical value associated with this message, useful for searching.
50022
50023@tsexample
50024// Add the message...
50025HudMessageVector.insertLine(1, "Hello World", 0);
50026@endtsexample
50027
50028@return False if insertPos is greater than the number of lines in the current vector*/
50029bool insertLine( int insertPos, string msg, int tag );
50030/*!
50031@brief Delete the line at the specified position.
50032
50033
50034@param deletePos Position in the vector containing the line to be deleted
50035@tsexample
50036// Delete the first line (index 0) in the vector...
50037HudMessageVector.deleteLine(0);
50038@endtsexample
50039
50040@return False if deletePos is greater than the number of lines in the current vector*/
50041bool deleteLine( int deletePos );
50042/*!
50043@brief Get the number of lines in the vector.
50044
50045
50046@tsexample
50047// Find out how many lines have been stored in HudMessageVector
50048%chatLines = HudMessageVector.getNumLines();
50049echo(%chatLines);
50050@endtsexample
50051
50052*/
50053int getNumLines();
50054/*!
50055@brief Scan through the lines in the vector, returning the first line that has a matching tag.
50056
50057
50058@param tag Numerical value assigned to a message when it was added or inserted
50059@tsexample
50060// Locate text in the vector tagged with the value "1", then print it
50061%taggedText = HudMessageVector.getLineTextByTag(1);
50062echo(%taggedText);
50063@endtsexample
50064
50065@return Text from a line with matching tag, other wise ""*/
50066string getLineTextByTag( int tag );
50067/*!
50068@brief Scan through the vector, returning the line number of the first line that matches the specified tag; else returns -1 if no match was found.
50069
50070
50071@param tag Numerical value assigned to a message when it was added or inserted
50072@tsexample
50073// Locate a line of text tagged with the value "1", then delete it.
50074%taggedLine = HudMessageVector.getLineIndexByTag(1);
50075HudMessageVector.deleteLine(%taggedLine);
50076@endtsexample
50077
50078@return Line with matching tag, other wise -1*/
50079int getLineIndexByTag( int tag );
50080/*!
50081@brief Get the text at a specified line.
50082
50083
50084@param pos Position in vector to grab text from
50085@tsexample
50086// Print a line of text at position 1.
50087%text = HudMessageVector.getLineText(1);
50088echo(%text);
50089@endtsexample
50090
50091@return Text at specified line, if the position is greater than the number of lines return ""*/
50092string getLineText( int pos );
50093/*!
50094@brief Get the tag of a specified line.
50095
50096
50097@param pos Position in vector to grab tag from
50098@tsexample
50099// Remove all lines that do not have a tag value of 1.
50100while( HudMessageVector.getNumLines())
50101{
50102   %tag = HudMessageVector.getLineTag(1);
50103   if(%tag != 1)
50104      %tag.delete();
50105   HudMessageVector.popFrontLine();
50106}
50107@endtsexample
50108
50109@return Tag value of a given line, if the position is greater than the number of lines return 0*/
50110int getLineTag( int pos );
50111
50112/*! @name Callbacks
50113@{ */
50114/// @}
50115
50116
50117/*! @name Ungrouped
50118@{ */
50119/// @}
50120
50121
50122/*! @name Object
50123@{ */
50124/// @}
50125
50126
50127/*! @name Editing
50128@{ */
50129/// @}
50130
50131
50132/*! @name Persistence
50133@{ */
50134/// @}
50135
50136};
50137
50138/*!
50139@brief Special type of data block that stores information about a handwritten shader.
50140
50141To use hand written shaders, a ShaderData datablock must be used. This datablock refers only to the vertex and pixel shader filenames and a hardware target level. Shaders are API specific, so DirectX and OpenGL shaders must be explicitly identified.
50142
50143 @tsexample
50144// Used for the procedural clould system
50145singleton ShaderData( CloudLayerShader )
50146{
50147   DXVertexShaderFile   = $Core::CommonShaderPath @ "/cloudLayerV.hlsl";
50148   DXPixelShaderFile    = $Core::CommonShaderPath @ "/cloudLayerP.hlsl";
50149   OGLVertexShaderFile = $Core::CommonShaderPath @ "/gl/cloudLayerV.glsl";
50150   OGLPixelShaderFile = $Core::CommonShaderPath @ "/gl/cloudLayerP.glsl";
50151   pixVersion = 2.0;
50152};
50153@endtsexample
50154
50155@ingroup Shaders
50156
50157*/
50158class ShaderData : public SimObject {
50159public:
50160/*!
50161@brief Rebuilds all the vertex and pixel shader instances created from this ShaderData.
50162
50163@tsexample
50164// Rebuild the shader instances from ShaderData CloudLayerShader
50165CloudLayerShader.reload();
50166@endtsexample*/
50167void reload();
50168
50169/*! @name Callbacks
50170@{ */
50171/// @}
50172
50173/*!
50174@brief @brief %Path to the DirectX vertex shader file to use for this ShaderData.
50175
50176
50177It must contain only one program and no pixel shader, just the vertex shader.It can be either an HLSL or assembly level shader. HLSL's must have a filename extension of .hlsl, otherwise its assumed to be an assembly file.
50178*/
50179filename DXVertexShaderFile;
50180/*!
50181@brief @brief %Path to the DirectX pixel shader file to use for this ShaderData.
50182
50183
50184It must contain only one program and no vertex shader, just the pixel shader. It can be either an HLSL or assembly level shader. HLSL's must have a filename extension of .hlsl, otherwise its assumed to be an assembly file.
50185*/
50186filename DXPixelShaderFile;
50187/*!
50188@brief @brief %Path to an OpenGL vertex shader file to use for this ShaderData.
50189
50190
50191It must contain only one program and no pixel shader, just the vertex shader.
50192*/
50193filename OGLVertexShaderFile;
50194/*!
50195@brief @brief %Path to an OpenGL pixel shader file to use for this ShaderData.
50196
50197
50198It must contain only one program and no vertex shader, just the pixel shader.
50199*/
50200filename OGLPixelShaderFile;
50201/*!
50202@brief @brief If true, the maximum pixel shader version offered by the graphics card will be used.
50203
50204
50205Otherwise, the script-defined pixel shader version will be used.
50206
50207
50208*/
50209bool useDevicePixVersion;
50210/*!
50211@brief @brief Indicates target level the shader should be compiled.
50212
50213
50214Valid numbers at the time of this writing are 1.1, 1.4, 2.0, and 3.0. The shader will not run properly if the hardware does not support the level of shader compiled.
50215*/
50216float pixVersion;
50217/*!
50218@brief @brief String of case-sensitive defines passed to the shader compiler.
50219
50220
50221The string should be delimited by a semicolon, tab, or newline character.@tsexample
50222singleton ShaderData( FlashShader )
50223{
50224DXVertexShaderFile   = $shaderGen::cachePath @ "/postFx/flashV.hlsl";
50225DXPixelShaderFile    = $shaderGen::cachePath @ "/postFx/flashP.hlsl";
50226
50227 //Define setting the color of WHITE_COLOR.
50228defines = "WHITE_COLOR=float4(1.0,1.0,1.0,0.0)";
50229
50230pixVersion = 2.0
50231}
50232@endtsexample
50233
50234
50235*/
50236string defines;
50237/*!
50238@brief @brief Indicates names of samplers present in shader. Order is important.
50239
50240
50241Order of sampler names are used to assert correct sampler register/locationOther objects (GFXStateBlockData, PostEffect...) use index number to link samplers.
50242*/
50243string samplerNames[ 8 ];
50244/*!
50245*/
50246bool rtParams[ 8 ];
50247
50248/*! @name Ungrouped
50249@{ */
50250/// @}
50251
50252
50253/*! @name Object
50254@{ */
50255/// @}
50256
50257
50258/*! @name Editing
50259@{ */
50260/// @}
50261
50262
50263/*! @name Persistence
50264@{ */
50265/// @}
50266
50267};
50268
50269/*!
50270@brief A grouping of render bin managers which forms a render pass.
50271
50272The render pass is used to order a set of RenderBinManager objects which are used when rendering a scene.  This class does little work itself other than managing its list of render bins.
50273
50274In 'core/scripts/client/renderManager.cs' you will find the DiffuseRenderPassManager which is used by the C++ engine to render the scene.
50275
50276@see RenderBinManager
50277@ingroup RenderBin
50278
50279*/
50280class RenderPassManager : public SimObject {
50281public:
50282/*!
50283@brief Returns the total number of bin managers.
50284
50285*/
50286int getManagerCount();
50287/*!
50288@brief Returns the render bin manager at the index or null if the index is out of range.
50289
50290*/
50291RenderBinManager getManager( int index );
50292/*!
50293@brief Add as a render bin manager to the pass.
50294
50295*/
50296void addManager( RenderBinManager  renderBin );
50297/*!
50298@brief Removes a render bin manager.
50299
50300*/
50301void removeManager( RenderBinManager  renderBin );
50302
50303/*! @name Callbacks
50304@{ */
50305/// @}
50306
50307
50308/*! @name Ungrouped
50309@{ */
50310/// @}
50311
50312
50313/*! @name Object
50314@{ */
50315/// @}
50316
50317
50318/*! @name Editing
50319@{ */
50320/// @}
50321
50322
50323/*! @name Persistence
50324@{ */
50325/// @}
50326
50327};
50328
50329/*!
50330@brief A render bin which uses object callbacks for rendering.
50331
50332This render bin gathers object render instances and calls its delegate method to perform rendering.  It is used infrequently for specialized scene objects which perform custom rendering.
50333
50334@ingroup RenderBin
50335
50336*/
50337class RenderProbeMgr : public RenderBinManager {
50338public:
50339/*!
50340@brief Bakes the cubemaps for a reflection probe
50341
50342.*/
50343void bakeProbe( ReflectionProbe probe=nullAsType< ReflectionProbe*>() );
50344/*!
50345@brief Iterates over all reflection probes in the scene and bakes their cubemaps
50346
50347.*/
50348void bakeProbes();
50349
50350/*! @name Callbacks
50351@{ */
50352/// @}
50353
50354
50355/*! @name Ungrouped
50356@{ */
50357/// @}
50358
50359
50360/*! @name Object
50361@{ */
50362/// @}
50363
50364
50365/*! @name Editing
50366@{ */
50367/// @}
50368
50369
50370/*! @name Persistence
50371@{ */
50372/// @}
50373
50374};
50375
50376/*!
50377@brief A spline along which various objects can move along. The spline object acts like a container for Marker objects, which make
50378up the joints, or knots, along the path. Paths can be assigned a speed, can be looping or non-looping. Each of a path's markers can be
50379one of three primary movement types: "normal", "Position Only", or "Kink". 
50380@tsexample
50381new path()
50382   {
50383     isLooping = "1";
50384
50385     new Marker()
50386      {
50387         seqNum = "0";
50388         type = "Normal";
50389         msToNext = "1000";
50390         smoothingType = "Spline";
50391         position = "-0.054708 -35.0612 234.802";
50392         rotation = "1 0 0 0";
50393      };
50394
50395   };
50396@endtsexample
50397@see Marker
50398@see NetConnection::transmitPaths()
50399@see NetConnection::clearPaths()
50400@see Path
50401@ingroup enviroMisc
50402
50403*/
50404class Path : public GameBase {
50405public:
50406/*!
50407@brief Returns the PathID (not the object ID) of this path.
50408
50409@return PathID (not the object ID) of this path.
50410@tsexample
50411// Acquire the PathID of this path object.
50412%pathID = %thisPath.getPathId();
50413
50414@endtsexample*/
50415int getPathId();
50416
50417/*! @name Callbacks
50418@{ */
50419/*!
50420@brief Called when this ScriptGroup is added to the system.
50421
50422@param ID Unique object ID assigned when created (%this in script).
50423*/
50424void onAdd( SimObjectId ID );
50425/// @}
50426
50427/*!
50428@brief Disables rendering of all instances of this type.
50429
50430
50431@ingroup UNDOCUMENTED
50432*/
50433static bool isRenderable;
50434/*!
50435@brief Disables selection of all instances of this type.
50436
50437
50438@ingroup UNDOCUMENTED
50439*/
50440static bool isSelectable;
50441/*!
50442@brief If this is true, the loop is closed, otherwise it is open.
50443
50444
50445*/
50446bool isLooping;
50447/*!
50448@brief Speed.
50449
50450
50451*/
50452float speed;
50453/*!
50454@brief @brief Spawned PathShape.
50455
50456
50457
50458*/
50459PathShapeData mPathShape;
50460/*!
50461@brief Spawn Count.
50462
50463
50464*/
50465int spawnCount;
50466/*!
50467@brief Spawn Delay (min).
50468
50469
50470*/
50471int minDelay;
50472/*!
50473@brief Spawn Delay (max).
50474
50475
50476*/
50477int maxDelay;
50478
50479/*! @name Game
50480@{ */
50481/// @}
50482
50483
50484/*! @name GameObject
50485@{ */
50486/// @}
50487
50488
50489/*! @name Transform
50490@{ */
50491/// @}
50492
50493
50494/*! @name Editing
50495@{ */
50496/// @}
50497
50498
50499/*! @name Mounting
50500@{ */
50501/// @}
50502
50503
50504/*! @name Ungrouped
50505@{ */
50506/// @}
50507
50508
50509/*! @name Object
50510@{ */
50511/// @}
50512
50513
50514/*! @name Editing
50515@{ */
50516/// @}
50517
50518
50519/*! @name Persistence
50520@{ */
50521/// @}
50522
50523};
50524
50525/*!
50526@brief Represent a terrain object in a Torque 3D level
50527
50528@tsexample
50529new TerrainBlock(theTerrain)
50530{
50531   terrainFile = "art/terrains/Deathball Desert_0.ter";
50532   squareSize = "2";
50533   tile = "0";
50534   baseTexSize = "1024";
50535   screenError = "16";
50536   position = "-1024 -1024 179.978";
50537   rotation = "1 0 0 0";
50538   scale = "1 1 1";
50539   isRenderEnabled = "true";
50540   canSaveDynamicFields = "1";
50541};
50542@endtsexample
50543
50544@see TerrainMaterial
50545
50546@ingroup Terrain
50547
50548*/
50549class TerrainBlock : public SceneObject {
50550public:
50551/*!
50552@brief Saves the terrain block's terrain file to the specified file name.
50553
50554@param fileName Name and path of file to save terrain data to.
50555
50556@return True if file save was successful, false otherwise*/
50557bool save( string fileName );
50558/*!
50559@brief Saves the terrain block's terrain file to the specified file name.
50560
50561@param fileName Name and path of file to save terrain data to.
50562
50563@return True if file save was successful, false otherwise*/
50564bool saveAsset();
50565void setMaterialsDirty();
50566/*!
50567@brief export the terrain block's heightmap to a bitmap file (default: png)
50568
50569*/
50570bool exportHeightMap( string fileNameStr, string format="png" );
50571/*!
50572@brief export the terrain block's layer maps to bitmap files (default: png)
50573
50574*/
50575bool exportLayerMaps( string filePrefixStr, string format="png" );
50576static int createNew( String terrainName, uint resolution, String materialName, bool genNoise );
50577static int import( int terrainObjectId, String heightMapFile, float metersPerPixel, float heightScale, String opacityLayerFiles, String materialsStr, bool flipYAxis=true );
50578
50579/*! @name Callbacks
50580@{ */
50581/// @}
50582
50583/*!
50584@brief Triggers debug rendering of terrain cells
50585
50586
50587@ingroup Terrain*/
50588static bool debugRender;
50589/*!
50590@brief Disables rendering of all instances of this type.
50591
50592
50593@ingroup UNDOCUMENTED
50594*/
50595static bool isRenderable;
50596/*!
50597@brief Disables selection of all instances of this type.
50598
50599
50600@ingroup UNDOCUMENTED
50601*/
50602static bool isSelectable;
50603
50604/*! @name Media
50605@{ */
50606/*!
50607@brief The source terrain data asset.
50608*/
50609assetIdString TerrainAsset;
50610/*!
50611@brief The source terrain data file.
50612*/
50613filename terrainFile;
50614/// @}
50615
50616
50617/*! @name Misc
50618@{ */
50619/*!
50620@brief Allows the terrain to cast shadows onto itself and other objects.
50621*/
50622bool castShadows;
50623/*!
50624@brief Indicates the spacing between points on the XY plane on the terrain.
50625*/
50626float squareSize;
50627/*!
50628@brief Size of base texture size per meter.
50629*/
50630int baseTexSize;
50631/*!
50632*/
50633baseTexFormat baseTexFormat;
50634/*!
50635@brief Light map dimensions in pixels.
50636*/
50637int lightMapSize;
50638/*!
50639@brief Not yet implemented.
50640*/
50641int screenError;
50642/*!
50643@brief Whether or not to update the Base Texture
50644*/
50645bool updateBasetex;
50646/// @}
50647
50648
50649/*! @name AFX
50650@{ */
50651/*!
50652*/
50653bool ignoreZodiacs;
50654/// @}
50655
50656
50657/*! @name GameObject
50658@{ */
50659/// @}
50660
50661
50662/*! @name Transform
50663@{ */
50664/// @}
50665
50666
50667/*! @name Editing
50668@{ */
50669/// @}
50670
50671
50672/*! @name Mounting
50673@{ */
50674/// @}
50675
50676
50677/*! @name Ungrouped
50678@{ */
50679/// @}
50680
50681
50682/*! @name Object
50683@{ */
50684/// @}
50685
50686
50687/*! @name Editing
50688@{ */
50689/// @}
50690
50691
50692/*! @name Persistence
50693@{ */
50694/// @}
50695
50696};
50697
50698/*!
50699@brief Volumetric Fog Object class. Main class defining the Volumetric
50700Fog objects in the scene. Used in conjunction with the VolumetricFogRTManager
50701class which is responsible for the required rendertargets.
50702
50703Methods (exposed to script):
50704 setFogColorF(color) Changes the overall fog color (color.rgba range 0.0 - 1.0).
50705; setFogColor(color) Changes the overall fog color color.rgba range 0 - 255).
50706; setFogDensity(density) Changes the overall fog density.
50707 setFogModulation(strength, speed1, speed2) changes the strength
50708 and the speeds of the 2 animation layers.
50709
50710Callbacks:
50711onEnterFog triggered whenever the controlobject (Player or Camera) enters the Fog.
50712 (current Fog object and the controlobject are exposed to script.
50713onLeaveFog triggered whenever the controlobject (Player or Camera) left the Fog.
50714 (current Fog object and the controlobject are exposed to script.
50715
50716@tsexample
50717 new VolumetricFog()
50718 {
50719 shapeName = "art/environment/FogRCube.dts";
50720 fogColor = "200 200 200 128";
50721 fogDensity = "0.2";
50722 ignoreWater = "0";
50723 MinSize = "250";
50724 FadeSize = "750";
50725 texture = "art/environment/FogMod_heavy.dds";
50726 tiles = "1.5";
50727 modStrength = "0.2";
50728 PrimSpeed = "-0.01 0.04";
50729 SecSpeed = "0.02 -0.02";
50730 position = "748.644 656.371 65.3506"; 
50731 rotation = "0 0 1 20.354";
50732 scale = "40 30 6";
50733 };
50734@endtsexample
50735
50736@ingroup UNDOCUMENTED
50737
50738*/
50739class VolumetricFog : public SceneObject {
50740public:
50741/*!
50742@brief Changes the color of the fog
50743
50744.@params new_color the new fog color (rgb 0.0 - 1.0, a is ignored.*/
50745void SetFogColorF( LinearColorF new_color );
50746/*!
50747@brief Changes the color of the fog
50748
50749.@params new_color the new fog color (rgb 0-255, a is ignored.*/
50750void SetFogColor( ColorI new_color );
50751/*!
50752@brief Changes the density of the fog
50753
50754.@params new_density the new fog density.*/
50755void SetFogDensity( float new_density );
50756/*!
50757@brief Changes the modulation of the fog
50758
50759.@params new_strenght the new strength of the modulation.
50760@params new_speed1 the new speed (x y) of the modulation layer 1.
50761@params new_speed2 the new speed (x y) of the modulation layer 2.*/
50762void SetFogModulation( float new_strenght, Point2F new_speed1, Point2F new_speed2 );
50763/*!
50764@brief Changes the glow postfx when inside the fog
50765
50766.@params on_off set to true to enable glow.
50767@params strength glow strength.*/
50768void SetFogGlow( bool on_off, float strength );
50769/*!
50770@brief Changes the lightrays postfx when inside the fog
50771
50772.@params on_off set to true to modification of the lightray postfx.
50773@params strength lightray strength.*/
50774void SetFogLightray( bool on_off, float strength );
50775/*!
50776@brief returns true if control object is inside the fog
50777
50778.*/
50779bool isInsideFog();
50780
50781/*! @name Callbacks
50782@{ */
50783/*!
50784@brief Called when an object enters the volume of the Fog instance.
50785
50786@param obj the controlobject entering the fog.*/
50787void onEnterFog( SimObjectId obj );
50788/*!
50789@brief Called when an object left the volume of the Fog instance.
50790
50791@param obj the controlobject leaving the fog.*/
50792void onLeaveFog( SimObjectId obj );
50793/// @}
50794
50795/*!
50796@brief Disables rendering of all instances of this type.
50797
50798
50799@ingroup UNDOCUMENTED
50800*/
50801static bool isRenderable;
50802/*!
50803@brief Disables selection of all instances of this type.
50804
50805
50806@ingroup UNDOCUMENTED
50807*/
50808static bool isSelectable;
50809
50810/*! @name VolumetricFogData
50811@{ */
50812/*!
50813@brief The source shape asset.
50814*/
50815assetIdString ShapeAsset;
50816/*!
50817@brief Path and filename of the model file (.DTS, .DAE) to use for this Volume.
50818*/
50819filename shapeName;
50820/*!
50821@brief Fog color RGBA (Alpha is ignored)
50822*/
50823ColorI fogColor;
50824/*!
50825@brief Overal fog density value (0 disables the fog).
50826*/
50827float fogDensity;
50828/*!
50829@brief Set to true if volumetric fog should continue while submerged.
50830*/
50831bool ignoreWater;
50832/*!
50833@brief Min size (in pixels) for fog to be rendered.
50834*/
50835float MinSize;
50836/*!
50837@brief Object size in pixels at which the FX-fading kicks in (0 disables fading).
50838*/
50839float fadeSize;
50840/// @}
50841
50842
50843/*! @name VolumetricFogModulation
50844@{ */
50845/*!
50846@brief A texture which contains Fogdensity modulator in the red channel and color with 1-green channel. No texture disables modulation.
50847*/
50848filename texture;
50849/*!
50850@brief How many times the texture is mapped to the object.
50851*/
50852float tiles;
50853/*!
50854@brief Overall strength of the density modulation (0 disables modulation).
50855*/
50856float modStrength;
50857/*!
50858@brief Overall primary speed of the density modulation (x-speed(u) y-speed(v))
50859*/
50860Point2F PrimSpeed;
50861/*!
50862@brief Overall secundary speed of the density modulation (x-speed(u) y-speed(v))
50863*/
50864Point2F SecSpeed;
50865/// @}
50866
50867
50868/*! @name Reflections
50869@{ */
50870/*!
50871@brief Set to true if volumetric fog should be reflected.
50872*/
50873bool Reflectable;
50874/*!
50875@brief Strength of the reflections (0 disables the fog).
50876*/
50877float ReflectStrength;
50878/// @}
50879
50880
50881/*! @name PostFX
50882@{ */
50883/*!
50884@brief Set to true if volumetric fog should use glow PostFX.
50885*/
50886bool useGlow;
50887/*!
50888@brief Overall strength of the glow PostFX.
50889*/
50890float glowStrength;
50891/*!
50892@brief Set to true if volumetric fog should modify the brightness of the Lightrays.
50893*/
50894bool modLightRay;
50895/*!
50896@brief Modifier for LightRay PostFX when inside Fog.
50897*/
50898float lightRayMod;
50899/// @}
50900
50901
50902/*! @name GameObject
50903@{ */
50904/// @}
50905
50906
50907/*! @name Transform
50908@{ */
50909/// @}
50910
50911
50912/*! @name Editing
50913@{ */
50914/// @}
50915
50916
50917/*! @name Mounting
50918@{ */
50919/// @}
50920
50921
50922/*! @name Ungrouped
50923@{ */
50924/// @}
50925
50926
50927/*! @name Object
50928@{ */
50929/// @}
50930
50931
50932/*! @name Editing
50933@{ */
50934/// @}
50935
50936
50937/*! @name Persistence
50938@{ */
50939/// @}
50940
50941};
50942
50943/*!
50944@brief A strip shaped decal defined by spine nodes which clips against Terrain objects.
50945
50946DecalRoad is for representing a road or path ( or other inventive things ) across a TerrainBlock. It renders as a decal and is therefore only for features that do not need geometric depth.
50947
50948The Material assigned to DecalRoad should tile vertically.
50949
50950@ingroup Terrain
50951*/
50952class DecalRoad : public SceneObject {
50953public:
50954/*!
50955@brief Intended as a helper to developers and editor scripts.
50956
50957Force DecalRoad to update it's spline and reclip geometry.*/
50958void regenerate();
50959/*!
50960@brief Intended as a helper to developers and editor scripts.
50961
50962Force trigger an inspectPostApply. This will transmit the material and other fields ( not including nodes ) to client objects.*/
50963void postApply();
50964
50965/*! @name Callbacks
50966@{ */
50967/// @}
50968
50969/*!
50970@brief For use by the Decal Editor.
50971
50972
50973@ingroup Editors
50974*/
50975static bool EditorOpen;
50976/*!
50977@brief For use by the Decal Editor.
50978
50979
50980@ingroup Editors
50981*/
50982static bool wireframe;
50983/*!
50984@brief For use by the Decal Editor.
50985
50986
50987@ingroup Editors
50988*/
50989static bool showBatches;
50990/*!
50991@brief For use by the Decal Editor.
50992
50993
50994@ingroup Editors
50995*/
50996static bool discardAll;
50997/*!
50998@brief For use by the Decal Editor.
50999
51000
51001@ingroup Editors
51002*/
51003static bool showSpline;
51004/*!
51005@brief For use by the Decal Editor.
51006
51007
51008@ingroup Editors
51009*/
51010static bool showRoad;
51011/*!
51012@brief For use by the Decal Editor.
51013
51014
51015@ingroup Editors
51016*/
51017static int updateDelay;
51018/*!
51019@brief Disables rendering of all instances of this type.
51020
51021
51022@ingroup UNDOCUMENTED
51023*/
51024static bool isRenderable;
51025/*!
51026@brief Disables selection of all instances of this type.
51027
51028
51029@ingroup UNDOCUMENTED
51030*/
51031static bool isSelectable;
51032
51033/*! @name DecalRoad
51034@{ */
51035/*!
51036@brief Material Asset used for rendering.
51037*/
51038assetIdString MaterialAsset;
51039/*!
51040@brief Material used for rendering.
51041*/
51042string Material;
51043/*!
51044@brief The length in meters of textures mapped to the DecalRoad
51045*/
51046float textureLength;
51047/*!
51048@brief Angle in degrees - DecalRoad will subdivided the spline if its curve is greater than this threshold.
51049*/
51050float breakAngle;
51051/*!
51052@brief DecalRoad(s) are rendered in descending renderPriority order.
51053*/
51054int renderPriority;
51055/// @}
51056
51057
51058/*! @name Internal
51059@{ */
51060/*!
51061@brief Do not modify, for internal use.
51062*/
51063string Node;
51064/// @}
51065
51066
51067/*! @name GameObject
51068@{ */
51069/// @}
51070
51071
51072/*! @name Transform
51073@{ */
51074/// @}
51075
51076
51077/*! @name Editing
51078@{ */
51079/// @}
51080
51081
51082/*! @name Mounting
51083@{ */
51084/// @}
51085
51086
51087/*! @name Ungrouped
51088@{ */
51089/// @}
51090
51091
51092/*! @name Object
51093@{ */
51094/// @}
51095
51096
51097/*! @name Editing
51098@{ */
51099/// @}
51100
51101
51102/*! @name Persistence
51103@{ */
51104/// @}
51105
51106};
51107
51108/*!
51109@brief A strip of rectangular mesh segments defined by a 3D spline for prototyping road-shaped objects in your scene.
51110
51111User may control width and depth per node, overall spline shape in three dimensions, and seperate Materials for rendering the top, bottom, and side surfaces.
51112
51113MeshRoad is not capable of handling intersections, branches, curbs, or other desirable features in a final 'road' asset and is therefore intended for prototyping and experimentation.
51114
51115Materials assigned to MeshRoad should tile vertically.
51116
51117@ingroup Terrain
51118*/
51119class MeshRoad : public SceneObject {
51120public:
51121/*!
51122@brief Intended as a helper to developers and editor scripts.
51123
51124Sets the depth in meters of a particular node.*/
51125void setNodeDepth( int idx, float meters );
51126/*!
51127@brief Intended as a helper to developers and editor scripts.
51128
51129Force MeshRoad to recreate its geometry.*/
51130void regenerate();
51131/*!
51132@brief Intended as a helper to developers and editor scripts.
51133
51134Force trigger an inspectPostApply. This will transmit material and other fields ( not including nodes ) to client objects.*/
51135void postApply();
51136
51137/*! @name Callbacks
51138@{ */
51139/// @}
51140
51141/*!
51142@brief True if the MeshRoad editor is open, otherwise false.
51143
51144@ingroup Editors
51145*/
51146static bool EditorOpen;
51147/*!
51148@brief If true, will render the wireframe of the road.
51149
51150@ingroup Editors
51151*/
51152static bool wireframe;
51153/*!
51154@brief Determines if the debug rendering of the batches cubes is displayed or not.
51155
51156@ingroup Editors
51157*/
51158static bool showBatches;
51159/*!
51160@brief If true, the spline on which the curvature of this road is based will be rendered.
51161
51162@ingroup Editors
51163*/
51164static bool showSpline;
51165/*!
51166@brief If true, the road will be rendered. When in the editor, roads are always rendered regardless of this flag.
51167
51168@ingroup Editors
51169*/
51170static bool showRoad;
51171/*!
51172@brief If true, the road profile will be shown in the editor.
51173
51174@ingroup Editors
51175*/
51176static bool showRoadProfile;
51177/*!
51178@brief Disables rendering of all instances of this type.
51179
51180
51181@ingroup UNDOCUMENTED
51182*/
51183static bool isRenderable;
51184/*!
51185@brief Disables selection of all instances of this type.
51186
51187
51188@ingroup UNDOCUMENTED
51189*/
51190static bool isSelectable;
51191
51192/*! @name MeshRoad
51193@{ */
51194/*!
51195@brief Material for the upper surface of the road.
51196*/
51197string topMaterial;
51198/*!
51199@brief Material for the upper surface of the road.
51200*/
51201assetIdString TopMaterialAsset;
51202/*!
51203@brief Material for the bottom surface of the road.
51204*/
51205string bottomMaterial;
51206/*!
51207@brief Material for the bottom surface of the road.
51208*/
51209assetIdString BottomMaterialAsset;
51210/*!
51211@brief Material for the left, right, front, and back surfaces of the road.
51212*/
51213string sideMaterial;
51214/*!
51215@brief Material for the left, right, front, and back surfaces of the road.
51216*/
51217assetIdString SideMaterialAsset;
51218/*!
51219@brief The length in meters of textures mapped to the MeshRoad.
51220*/
51221float textureLength;
51222/*!
51223@brief Angle in degrees - MeshRoad will subdivide the spline if its curve is greater than this threshold.
51224*/
51225float breakAngle;
51226/*!
51227@brief Subdivide segments widthwise this many times when generating vertices.
51228*/
51229int widthSubdivisions;
51230/// @}
51231
51232
51233/*! @name Internal
51234@{ */
51235/*!
51236@brief Do not modify, for internal use.
51237*/
51238string Node;
51239/*!
51240@brief Do not modify, for internal use.
51241*/
51242string ProfileNode;
51243/// @}
51244
51245
51246/*! @name GameObject
51247@{ */
51248/// @}
51249
51250
51251/*! @name Transform
51252@{ */
51253/// @}
51254
51255
51256/*! @name Editing
51257@{ */
51258/// @}
51259
51260
51261/*! @name Mounting
51262@{ */
51263/// @}
51264
51265
51266/*! @name Ungrouped
51267@{ */
51268/// @}
51269
51270
51271/*! @name Object
51272@{ */
51273/// @}
51274
51275
51276/*! @name Editing
51277@{ */
51278/// @}
51279
51280
51281/*! @name Persistence
51282@{ */
51283/// @}
51284
51285};
51286
51287/*!
51288@brief A water volume defined by a 3D spline.
51289
51290User may control width and depth per node and overall spline shape in three dimensions.
51291
51292%River supports dynamic planar reflections (fullReflect) like all WaterObject classes, but keep in mind it is not necessarily a planar surface. For best visual quality a %River should be less reflective the more it twists and bends. This caution only applies to %Rivers with fullReflect on.
51293
51294@see WaterObject for inherited functionality.
51295
51296@ingroup Water
51297*/
51298class River : public WaterObject {
51299public:
51300/*!
51301@brief Intended as a helper to developers and editor scripts.
51302
51303Force River to recreate its geometry.*/
51304void regenerate();
51305/*!
51306@brief Intended as a helper to developers and editor scripts.
51307
51308@see SegmentLength field.*/
51309void setMetersPerSegment( float meters );
51310/*!
51311@brief Intended as a helper to developers and editor scripts.
51312
51313BatchSize is not currently used.*/
51314void setBatchSize( float meters );
51315/*!
51316@brief Intended as a helper to developers and editor scripts.
51317
51318Sets the depth in meters of a particular node.*/
51319void setNodeDepth( int idx, float meters );
51320/*!
51321@brief Intended as a helper to developers and editor scripts.
51322
51323@see SubdivideLength field.*/
51324void setMaxDivisionSize( float meters );
51325
51326/*! @name Callbacks
51327@{ */
51328/// @}
51329
51330/*!
51331@brief For editor use.
51332
51333@ingroup Editors
51334*/
51335static bool EditorOpen;
51336/*!
51337@brief For editor use.
51338
51339@ingroup Editors
51340*/
51341static bool showWalls;
51342/*!
51343@brief For editor use.
51344
51345@ingroup Editors
51346*/
51347static bool showNodes;
51348/*!
51349@brief For editor use.
51350
51351@ingroup Editors
51352*/
51353static bool showSpline;
51354/*!
51355@brief For editor use.
51356
51357@ingroup Editors
51358*/
51359static bool showRiver;
51360/*!
51361@brief For editor use.
51362
51363@ingroup Editors
51364*/
51365static bool showWireframe;
51366/*!
51367@brief Disables rendering of all instances of this type.
51368
51369
51370@ingroup UNDOCUMENTED
51371*/
51372static bool isRenderable;
51373/*!
51374@brief Disables selection of all instances of this type.
51375
51376
51377@ingroup UNDOCUMENTED
51378*/
51379static bool isSelectable;
51380
51381/*! @name River
51382@{ */
51383/*!
51384@brief Divide the River lengthwise into segments of this length in meters. These geometric volumes are used for spacial queries like determining containment.
51385*/
51386float SegmentLength;
51387/*!
51388@brief For purposes of generating the renderable geometry River segments are further subdivided such that no quad is of greater width or length than this distance in meters.
51389*/
51390float SubdivideLength;
51391/*!
51392@brief Magnitude of the force vector applied to dynamic objects within the River.
51393*/
51394float FlowMagnitude;
51395/*!
51396@brief Segments of the river at this distance in meters or greater will render as a single unsubdivided without undulation effects.
51397*/
51398float LowLODDistance;
51399/// @}
51400
51401
51402/*! @name Internal
51403@{ */
51404/*!
51405@brief For internal use, do not modify.
51406*/
51407string Node;
51408/// @}
51409
51410
51411/*! @name WaterObject
51412@{ */
51413/// @}
51414
51415
51416/*! @name Reflect
51417@{ */
51418/// @}
51419
51420
51421/*! @name Underwater Fogging
51422@{ */
51423/// @}
51424
51425
51426/*! @name Misc
51427@{ */
51428/// @}
51429
51430
51431/*! @name Distortion
51432@{ */
51433/// @}
51434
51435
51436/*! @name Basic Lighting
51437@{ */
51438/// @}
51439
51440
51441/*! @name Sound
51442@{ */
51443/// @}
51444
51445
51446/*! @name GameObject
51447@{ */
51448/// @}
51449
51450
51451/*! @name Transform
51452@{ */
51453/// @}
51454
51455
51456/*! @name Editing
51457@{ */
51458/// @}
51459
51460
51461/*! @name Mounting
51462@{ */
51463/// @}
51464
51465
51466/*! @name Ungrouped
51467@{ */
51468/// @}
51469
51470
51471/*! @name Object
51472@{ */
51473/// @}
51474
51475
51476/*! @name Editing
51477@{ */
51478/// @}
51479
51480
51481/*! @name Persistence
51482@{ */
51483/// @}
51484
51485};
51486
51487/*!
51488@brief Represents both the sun and sky for scenes with a dynamic time of day.
51489
51490%ScatterSky renders as a dome shaped mesh which is camera relative and always overhead. It is intended to be part of the background of your scene and renders before all other objects types.
51491
51492%ScatterSky is designed for outdoor scenes which need to transition fluidly between radically different times of day. It will respond to time changes originating from a TimeOfDay object or the elevation field can be directly adjusted.
51493
51494During day, %ScatterSky uses atmosphereic sunlight scattering aproximations to generate a sky gradient and sun corona. It also calculates the fog color, ambient color, and sun color, which are used for scene lighting. This is user controlled by fields within the ScatterSky group.
51495
51496During night, %ScatterSky supports can transition to a night sky cubemap and moon sprite. The user can control this and night time colors used for scene lighting with fields within the Night group.
51497
51498A scene with a ScatterSky should not have any other sky or sun objects as it already fulfills both roles.
51499
51500%ScatterSky is intended to be used with CloudLayer and TimeOfDay as part of a scene with dynamic lighting. Having a %ScatterSky without a changing time of day would unnecessarily give up artistic control compared and fillrate compared to a SkyBox + Sun setup.
51501
51502@ingroup Atmosphere
51503*/
51504class ScatterSky : public SceneObject {
51505public:
51506/*!
51507@brief Apply a full network update of all fields to all clients.
51508
51509*/
51510void applyChanges();
51511
51512/*! @name Callbacks
51513@{ */
51514/// @}
51515
51516/*!
51517@brief Disables rendering of all instances of this type.
51518
51519
51520@ingroup UNDOCUMENTED
51521*/
51522static bool isRenderable;
51523/*!
51524@brief Disables selection of all instances of this type.
51525
51526
51527@ingroup UNDOCUMENTED
51528*/
51529static bool isSelectable;
51530
51531/*! @name ScatterSky
51532Only azimuth and elevation are networked fields. To trigger a full update of all other fields use the applyChanges ConsoleMethod.
51533@{ */
51534/*!
51535@brief Global brightness and intensity applied to the sky and objects in the level.
51536*/
51537float skyBrightness;
51538/*!
51539@brief Affects the size of the sun's disk.
51540*/
51541float sunSize;
51542/*!
51543@brief Controls how much the alpha component of colorize brigthens the sky. Setting to 0 returns default behavior.
51544*/
51545float colorizeAmount;
51546/*!
51547@brief Tints the sky the color specified, the alpha controls the brigthness. The brightness is multipled by the value of colorizeAmt.
51548*/
51549LinearColorF colorize;
51550/*!
51551@brief Controls how blue the atmosphere is during the day.
51552*/
51553float rayleighScattering;
51554/*!
51555@brief Modulates the directional color of sunlight.
51556*/
51557LinearColorF sunScale;
51558/*!
51559@brief Modulates the ambient color of sunlight.
51560*/
51561LinearColorF ambientScale;
51562/*!
51563@brief Modulates the fog color. Note that this overrides the LevelInfo.fogColor property, so you should not use LevelInfo.fogColor if the level contains a ScatterSky object.
51564*/
51565LinearColorF fogScale;
51566/*!
51567@brief Controls the contrast of the sky and sun during daytime.
51568*/
51569float exposure;
51570/*!
51571@brief Offsets the scatterSky to avoid canvas rendering. Use 5000 or greater for the initial adjustment
51572*/
51573float zOffset;
51574/// @}
51575
51576
51577/*! @name Orbit
51578@{ */
51579/*!
51580@brief The horizontal angle of the sun measured clockwise from the positive Y world axis. This field is networked.
51581*/
51582float azimuth;
51583/*!
51584@brief The elevation angle of the sun above or below the horizon. This field is networked.
51585*/
51586float elevation;
51587/*!
51588@brief The horizontal angle of the moon measured clockwise from the positive Y world axis. This is not animated by time or networked.
51589*/
51590float moonAzimuth;
51591/*!
51592@brief The elevation angle of the moon above or below the horizon. This is not animated by time or networked.
51593*/
51594float moonElevation;
51595/// @}
51596
51597
51598/*! @name Lighting
51599@{ */
51600/*!
51601@brief Enables/disables shadows cast by objects due to ScatterSky light.
51602*/
51603bool castShadows;
51604/*!
51605@brief static shadow refresh rate (milliseconds)
51606*/
51607int staticRefreshFreq;
51608/*!
51609@brief dynamic shadow refresh rate (milliseconds)
51610*/
51611int dynamicRefreshFreq;
51612/*!
51613@brief The brightness of the ScatterSky's light object.
51614*/
51615float brightness;
51616/// @}
51617
51618
51619/*! @name Misc
51620@{ */
51621/*!
51622@brief Datablock for the flare produced by the ScatterSky.
51623*/
51624LightFlareData flareType;
51625/*!
51626@brief Changes the size and intensity of the flare.
51627*/
51628float flareScale;
51629/// @}
51630
51631
51632/*! @name Night
51633@{ */
51634/*!
51635@brief The ambient color during night. Also used for the sky color if useNightCubemap is false.
51636*/
51637LinearColorF nightColor;
51638/*!
51639@brief The fog color during night.
51640*/
51641LinearColorF nightFogColor;
51642/*!
51643@brief Enable or disable rendering of the moon sprite during night.
51644*/
51645bool moonEnabled;
51646/*!
51647@brief Material for the moon sprite.
51648*/
51649string moonMat;
51650/*!
51651@brief Controls size the moon sprite renders, specified as a fractional amount of the screen height.
51652*/
51653float moonScale;
51654/*!
51655@brief Color of light cast by the directional light during night.
51656*/
51657LinearColorF moonLightColor;
51658/*!
51659@brief Transition to the nightCubemap during night. If false we use nightColor.
51660*/
51661bool useNightCubemap;
51662/*!
51663@brief Cubemap visible during night.
51664*/
51665string nightCubemap;
51666/// @}
51667
51668
51669/*! @name Advanced Lighting
51670@{ */
51671/*!
51672@brief The proportions of constant, linear, and quadratic attenuation to use for the falloff for point and spot lights.
51673*/
51674Point3F attenuationRatio;
51675/*!
51676@brief The type of shadow to use on this light.
51677*/
51678ShadowType shadowType;
51679/*!
51680@brief A custom pattern texture which is projected from the light.
51681*/
51682filename cookie;
51683/*!
51684@brief The texture size of the shadow map.
51685*/
51686int texSize;
51687/*!
51688@brief The ESM shadow darkening factor
51689*/
51690Point4F overDarkFactor;
51691/*!
51692@brief The distance from the camera to extend the PSSM shadow.
51693*/
51694float shadowDistance;
51695/*!
51696*/
51697float shadowSoftness;
51698/*!
51699@brief The logrithmic PSSM split distance factor.
51700*/
51701int numSplits;
51702/*!
51703@brief The logrithmic PSSM split distance factor.
51704*/
51705float logWeight;
51706/*!
51707@brief Start fading shadows out at this distance.  0 = auto calculate this distance.
51708*/
51709float fadeStartDistance;
51710/*!
51711@brief This toggles only terrain being rendered to the last split of a PSSM shadow map.
51712*/
51713bool lastSplitTerrainOnly;
51714/// @}
51715
51716
51717/*! @name Advanced Lighting Lightmap
51718@{ */
51719/*!
51720@brief This light is represented in lightmaps (static light, default: false)
51721*/
51722bool representedInLightmap;
51723/*!
51724@brief The color that should be used to multiply-blend dynamic shadows onto lightmapped geometry (ignored if 'representedInLightmap' is false)
51725*/
51726LinearColorF shadowDarkenColor;
51727/*!
51728@brief This light should render lightmapped geometry during its shadow-map update (ignored if 'representedInLightmap' is false)
51729*/
51730bool includeLightmappedGeometryInShadow;
51731/// @}
51732
51733
51734/*! @name GameObject
51735@{ */
51736/// @}
51737
51738
51739/*! @name Transform
51740@{ */
51741/// @}
51742
51743
51744/*! @name Editing
51745@{ */
51746/// @}
51747
51748
51749/*! @name Mounting
51750@{ */
51751/// @}
51752
51753
51754/*! @name Ungrouped
51755@{ */
51756/// @}
51757
51758
51759/*! @name Object
51760@{ */
51761/// @}
51762
51763
51764/*! @name Editing
51765@{ */
51766/// @}
51767
51768
51769/*! @name Persistence
51770@{ */
51771/// @}
51772
51773};
51774
51775/*!
51776@brief Represents the sky with an artist-created cubemap.
51777
51778SkyBox is not a directional light and should be used in conjunction with a Sun object.
51779
51780@ingroup Atmosphere
51781*/
51782class SkyBox : public SceneObject {
51783public:
51784void postApply();
51785
51786/*! @name Callbacks
51787@{ */
51788/// @}
51789
51790/*!
51791@brief Disables rendering of all instances of this type.
51792
51793
51794@ingroup UNDOCUMENTED
51795*/
51796static bool isRenderable;
51797/*!
51798@brief Disables selection of all instances of this type.
51799
51800
51801@ingroup UNDOCUMENTED
51802*/
51803static bool isSelectable;
51804
51805/*! @name Sky Box
51806@{ */
51807/*!
51808@brief The name of a cubemap material for the sky box.
51809*/
51810string Material;
51811/*!
51812@brief If false the bottom of the skybox is not rendered.
51813*/
51814bool drawBottom;
51815/*!
51816@brief The height (0-1) of the fog band from the horizon to the top of the SkyBox.
51817*/
51818float fogBandHeight;
51819/// @}
51820
51821
51822/*! @name GameObject
51823@{ */
51824/// @}
51825
51826
51827/*! @name Transform
51828@{ */
51829/// @}
51830
51831
51832/*! @name Editing
51833@{ */
51834/// @}
51835
51836
51837/*! @name Mounting
51838@{ */
51839/// @}
51840
51841
51842/*! @name Ungrouped
51843@{ */
51844/// @}
51845
51846
51847/*! @name Object
51848@{ */
51849/// @}
51850
51851
51852/*! @name Editing
51853@{ */
51854/// @}
51855
51856
51857/*! @name Persistence
51858@{ */
51859/// @}
51860
51861};
51862
51863/*!
51864@brief A global light affecting your entire scene and optionally renders a corona effect.
51865
51866Sun is both the directional and ambient light for your entire scene.
51867
51868@ingroup Atmosphere
51869*/
51870class Sun : public SceneObject {
51871public:
51872void apply();
51873/*!
51874@brief animate( F32 duration, F32 startAzimuth, F32 endAzimuth, F32 startElevation, F32 endElevation )
51875
51876*/
51877void animate( float duration, float startAzimuth, float endAzimuth, float startElevation, float endElevation );
51878
51879/*! @name Callbacks
51880@{ */
51881/// @}
51882
51883/*!
51884@brief Disables rendering of all instances of this type.
51885
51886
51887@ingroup UNDOCUMENTED
51888*/
51889static bool isRenderable;
51890/*!
51891@brief Disables selection of all instances of this type.
51892
51893
51894@ingroup UNDOCUMENTED
51895*/
51896static bool isSelectable;
51897
51898/*! @name Orbit
51899@{ */
51900/*!
51901@brief The horizontal angle of the sun measured clockwise from the positive Y world axis.
51902*/
51903float azimuth;
51904/*!
51905@brief The elevation angle of the sun above or below the horizon.
51906*/
51907float elevation;
51908/// @}
51909
51910
51911/*! @name Lighting
51912@{ */
51913/*!
51914@brief Color shading applied to surfaces in direct contact with light source.
51915*/
51916LinearColorF color;
51917/*!
51918@brief Color shading applied to surfaces not in direct contact with light source, such as in the shadows or interiors.
51919*/
51920LinearColorF ambient;
51921/*!
51922@brief Adjust the Sun's global contrast/intensity
51923*/
51924float brightness;
51925/*!
51926@brief Enables/disables shadows cast by objects due to Sun light
51927*/
51928bool castShadows;
51929/// @}
51930
51931
51932/*! @name Corona
51933@{ */
51934/*!
51935@brief Enable or disable rendering of the corona sprite.
51936*/
51937bool coronaEnabled;
51938/*!
51939@brief Texture for the corona sprite.
51940*/
51941string coronaMaterial;
51942/*!
51943@brief Controls size the corona sprite renders, specified as a fractional amount of the screen height.
51944*/
51945float coronaScale;
51946/*!
51947@brief Modulates the corona sprite color ( if coronaUseLightColor is false ).
51948*/
51949LinearColorF coronaTint;
51950/*!
51951@brief Modulate the corona sprite color by the color of the light ( overrides coronaTint ).
51952*/
51953bool coronaUseLightColor;
51954/// @}
51955
51956
51957/*! @name Misc
51958@{ */
51959/*!
51960@brief Datablock for the flare produced by the Sun
51961*/
51962LightFlareData flareType;
51963/*!
51964@brief Changes the size and intensity of the flare.
51965*/
51966float flareScale;
51967/// @}
51968
51969
51970/*! @name Advanced Lighting
51971@{ */
51972/*!
51973@brief The proportions of constant, linear, and quadratic attenuation to use for the falloff for point and spot lights.
51974*/
51975Point3F attenuationRatio;
51976/*!
51977@brief The type of shadow to use on this light.
51978*/
51979ShadowType shadowType;
51980/*!
51981@brief A custom pattern texture which is projected from the light.
51982*/
51983filename cookie;
51984/*!
51985@brief The texture size of the shadow map.
51986*/
51987int texSize;
51988/*!
51989@brief The ESM shadow darkening factor
51990*/
51991Point4F overDarkFactor;
51992/*!
51993@brief The distance from the camera to extend the PSSM shadow.
51994*/
51995float shadowDistance;
51996/*!
51997*/
51998float shadowSoftness;
51999/*!
52000@brief The logrithmic PSSM split distance factor.
52001*/
52002int numSplits;
52003/*!
52004@brief The logrithmic PSSM split distance factor.
52005*/
52006float logWeight;
52007/*!
52008@brief Start fading shadows out at this distance.  0 = auto calculate this distance.
52009*/
52010float fadeStartDistance;
52011/*!
52012@brief This toggles only terrain being rendered to the last split of a PSSM shadow map.
52013*/
52014bool lastSplitTerrainOnly;
52015/// @}
52016
52017
52018/*! @name Advanced Lighting Lightmap
52019@{ */
52020/*!
52021@brief This light is represented in lightmaps (static light, default: false)
52022*/
52023bool representedInLightmap;
52024/*!
52025@brief The color that should be used to multiply-blend dynamic shadows onto lightmapped geometry (ignored if 'representedInLightmap' is false)
52026*/
52027LinearColorF shadowDarkenColor;
52028/*!
52029@brief This light should render lightmapped geometry during its shadow-map update (ignored if 'representedInLightmap' is false)
52030*/
52031bool includeLightmappedGeometryInShadow;
52032/// @}
52033
52034
52035/*! @name GameObject
52036@{ */
52037/// @}
52038
52039
52040/*! @name Transform
52041@{ */
52042/// @}
52043
52044
52045/*! @name Editing
52046@{ */
52047/// @}
52048
52049
52050/*! @name Mounting
52051@{ */
52052/// @}
52053
52054
52055/*! @name Ungrouped
52056@{ */
52057/// @}
52058
52059
52060/*! @name Object
52061@{ */
52062/// @}
52063
52064
52065/*! @name Editing
52066@{ */
52067/// @}
52068
52069
52070/*! @name Persistence
52071@{ */
52072/// @}
52073
52074};
52075
52076/*!
52077@brief Environmental object that triggers a day/night cycle in level.
52078
52079@note TimeOfDay only works in Advanced Lighting with a Sub object or ScatterSky
52080
52081@tsexample
52082new TimeOfDay(tod)
52083{
52084   axisTilt = "23.44";
52085   dayLength = "120";
52086   startTime = "0.15";
52087   time = "0.15";
52088   play = "0";
52089   azimuthOverride = "572.958";
52090   dayScale = "1";
52091   nightScale = "1.5";
52092   position = "598.399 550.652 196.297";
52093   rotation = "1 0 0 0";
52094   scale = "1 1 1";
52095   canSave = "1";
52096   canSaveDynamicFields = "1";
52097};
52098@endtsexample
52099
52100@ingroup enviroMisc
52101*/
52102class TimeOfDay : public SceneObject {
52103public:
52104void addTimeOfDayEvent( float elevation, string identifier );
52105void setTimeOfDay( float time );
52106void setPlay( bool enabled );
52107void setDayLength( float seconds );
52108void animate( float elevation, float degreesPerSecond );
52109
52110/*! @name Callbacks
52111@{ */
52112/// @}
52113
52114/*!
52115@brief Disables rendering of all instances of this type.
52116
52117
52118@ingroup UNDOCUMENTED
52119*/
52120static bool isRenderable;
52121/*!
52122@brief Disables selection of all instances of this type.
52123
52124
52125@ingroup UNDOCUMENTED
52126*/
52127static bool isSelectable;
52128
52129/*! @name TimeOfDay
52130@{ */
52131/*!
52132@brief The angle in degrees between global equator and tropic.
52133*/
52134float axisTilt;
52135/*!
52136@brief The length of a virtual day in real world seconds.
52137*/
52138float dayLength;
52139/*!
52140*/
52141float startTime;
52142/*!
52143@brief Current time of day.
52144*/
52145float Time;
52146/*!
52147@brief True when the TimeOfDay object is operating.
52148*/
52149bool play;
52150/*!
52151*/
52152float azimuthOverride;
52153/*!
52154@brief Scalar applied to time that elapses while the sun is up.
52155*/
52156float dayScale;
52157/*!
52158@brief Scalar applied to time that elapses while the sun is down.
52159*/
52160float nightScale;
52161/// @}
52162
52163
52164/*! @name GameObject
52165@{ */
52166/// @}
52167
52168
52169/*! @name Transform
52170@{ */
52171/// @}
52172
52173
52174/*! @name Editing
52175@{ */
52176/// @}
52177
52178
52179/*! @name Mounting
52180@{ */
52181/// @}
52182
52183
52184/*! @name Ungrouped
52185@{ */
52186/// @}
52187
52188
52189/*! @name Object
52190@{ */
52191/// @}
52192
52193
52194/*! @name Editing
52195@{ */
52196/// @}
52197
52198
52199/*! @name Persistence
52200@{ */
52201/// @}
52202
52203};
52204
52205/*!
52206@brief %Forest is a global-bounds scene object provides collision and rendering for a (.forest) data file.
52207
52208%Forest is designed to efficiently render a large number of static meshes: trees, rocks plants, etc. These cannot be moved at game-time or play animations but do support wind effects using vertex shader transformations guided by vertex color in the asset and user placed wind emitters ( or weapon explosions ).
52209
52210Script level manipulation of forest data is not possible through %Forest, it is only the rendering/collision. All editing is done through the world editor.
52211
52212@see TSForestItemData Defines a tree type.
52213@see GuiForestEditorCtrl Used by the world editor to provide manipulation of forest data.
52214@ingroup Forest
52215*/
52216class Forest : public SceneObject {
52217public:
52218/*!
52219@brief saveDataFile( [path] )
52220
52221*/
52222void saveDataFile( string path="" );
52223bool isDirty();
52224void regenCells();
52225void clear();
52226
52227/*! @name Callbacks
52228@{ */
52229/// @}
52230
52231/*!
52232@brief A debugging aid which will force all forest items to be rendered as imposters.
52233
52234@ingroup Forest
52235*/
52236static bool forceImposters;
52237/*!
52238@brief A debugging aid which will disable rendering of all imposters in the forest.
52239
52240@ingroup Forest
52241*/
52242static bool disableImposters;
52243/*!
52244@brief A debugging aid which renders the forest cell bounds.
52245
52246@ingroup Forest
52247*/
52248static bool drawCells;
52249/*!
52250@brief A debugging aid which renders the forest bounds.
52251
52252@ingroup Forest
52253*/
52254static bool drawBounds;
52255/*!
52256@brief Disables rendering of all instances of this type.
52257
52258
52259@ingroup UNDOCUMENTED
52260*/
52261static bool isRenderable;
52262/*!
52263@brief Disables selection of all instances of this type.
52264
52265
52266@ingroup UNDOCUMENTED
52267*/
52268static bool isSelectable;
52269
52270/*! @name GameObject
52271@{ */
52272/// @}
52273
52274
52275/*! @name Transform
52276@{ */
52277/// @}
52278
52279
52280/*! @name Editing
52281@{ */
52282/// @}
52283
52284
52285/*! @name Mounting
52286@{ */
52287/// @}
52288
52289
52290/*! @name Ungrouped
52291@{ */
52292/// @}
52293
52294
52295/*! @name Object
52296@{ */
52297/// @}
52298
52299
52300/*! @name Editing
52301@{ */
52302/// @}
52303
52304
52305/*! @name Persistence
52306@{ */
52307/// @}
52308
52309/*!
52310@brief The source forest data file.
52311*/
52312filename dataFile;
52313
52314/*! @name Lod
52315@{ */
52316/*!
52317@brief Scalar applied to the farclip distance when Forest renders into a reflection.
52318*/
52319float lodReflectScalar;
52320/// @}
52321
52322};
52323
52324/*!
52325@brief Object responsible for simulating wind in a level.
52326
52327When placed in the level, a ForestWindEmitter will cause tree branches to bend and sway, leaves to flutter, and create vertical bending on the tree's trunk.
52328
52329@tsexample
52330// The following is a full declaration of a wind emitter
52331new ForestWindEmitter()
52332{
52333   position = "497.739 765.821 102.395";
52334   windEnabled = "1";
52335   radialEmitter = "1";
52336   strength = "1";
52337   radius = "3";
52338   gustStrength = "0.5";
52339   gustFrequency = "1";
52340   gustYawAngle = "10";
52341   gustYawFrequency = "4";
52342   gustWobbleStrength = "2";
52343   turbulenceStrength = "1";
52344   turbulenceFrequency = "2";
52345   hasMount = "0";
52346   scale = "3 3 3";
52347   canSave = "1";
52348   canSaveDynamicFields = "1";
52349   rotation = "1 0 0 0";
52350};
52351@endtsexample
52352
52353@ingroup FX
52354@ingroup Forest
52355@ingroup Atmosphere
52356
52357*/
52358class ForestWindEmitter : public SceneObject {
52359public:
52360/*!
52361@brief Mounts the wind emitter to another scene object
52362
52363@param objectID Unique ID of the object wind emitter should attach to@tsexample
52364// Wind emitter previously created and named %windEmitter
52365// Going to attach it to the player, making him a walking wind storm
52366%windEmitter.attachToObject(%player);
52367@endtsexample*/
52368void attachToObject( uint objectID );
52369
52370/*! @name Callbacks
52371@{ */
52372/// @}
52373
52374/*!
52375@brief Disables rendering of all instances of this type.
52376
52377
52378@ingroup UNDOCUMENTED
52379*/
52380static bool isRenderable;
52381/*!
52382@brief Disables selection of all instances of this type.
52383
52384
52385@ingroup UNDOCUMENTED
52386*/
52387static bool isSelectable;
52388
52389/*! @name GameObject
52390@{ */
52391/// @}
52392
52393
52394/*! @name Transform
52395@{ */
52396/// @}
52397
52398
52399/*! @name Editing
52400@{ */
52401/// @}
52402
52403
52404/*! @name Mounting
52405@{ */
52406/// @}
52407
52408
52409/*! @name Ungrouped
52410@{ */
52411/// @}
52412
52413
52414/*! @name Object
52415@{ */
52416/// @}
52417
52418
52419/*! @name Editing
52420@{ */
52421/// @}
52422
52423
52424/*! @name Persistence
52425@{ */
52426/// @}
52427
52428
52429/*! @name ForestWind
52430@{ */
52431/*!
52432@brief Determines if the emitter will be counted in wind calculations.
52433*/
52434bool windEnabled;
52435/*!
52436@brief Determines if the emitter is a global direction or local radial emitter.
52437*/
52438bool radialEmitter;
52439/*!
52440@brief The strength of the wind force.
52441*/
52442float strength;
52443/*!
52444@brief The radius of the emitter for local radial emitters.
52445*/
52446float radius;
52447/*!
52448@brief The maximum strength of a gust.
52449*/
52450float gustStrength;
52451/*!
52452@brief The frequency of gusting in seconds.
52453*/
52454float gustFrequency;
52455/*!
52456@brief The amount of degrees the wind direction can drift (both positive and negative).
52457*/
52458float gustYawAngle;
52459/*!
52460@brief The frequency of wind yaw drift, in seconds.
52461*/
52462float gustYawFrequency;
52463/*!
52464@brief The amount of random wobble added to gust and turbulence vectors.
52465*/
52466float gustWobbleStrength;
52467/*!
52468@brief The strength of gust turbulence.
52469*/
52470float turbulenceStrength;
52471/*!
52472@brief The frequency of gust turbulence, in seconds.
52473*/
52474float turbulenceFrequency;
52475/*!
52476@brief Determines if the emitter is mounted to another object.
52477*/
52478bool hasMount;
52479/// @}
52480
52481};
52482
52483/*!
52484@brief An object used to modify a DTS or COLLADA shape model after it has been loaded by Torque
52485
52486@ingroup gameObjects
52487
52488*/
52489class TSShapeConstructor : public SimObject {
52490public:
52491/*!
52492@brief Add a new mesh primitive to the shape.
52493
52494@param meshName full name (object name + detail size) of the new mesh. If no detail size is present at the end of the name, a value of 2 is used.<br>An underscore before the number at the end of the name will be interpreted as a negative sign. eg. "MyMesh_4" will be interpreted as "MyMesh-4".
52495@param type one of: "box", "sphere", "capsule"
52496@param params mesh primitive parameters:
52497<ul><li>for box: "size_x size_y size_z"</li><li>for sphere: "radius"</li><li>for capsule: "height radius"</li></ul></ul>
52498@param txfm local transform offset from the node for this mesh
52499@param nodeName name of the node to attach the new mesh to (will change the object's node if adding a new mesh to an existing object)
52500@return true if successful, false otherwise
52501
52502@tsexample
52503%this.addMesh( "Box4", "box", "2 4 2", "0 2 0 0 0 1 0", "eye" );
52504%this.addMesh( "Sphere256", "sphere", "2", "0 0 0 0 0 1 0", "root" );
52505%this.addMesh( "MyCapsule-1", "capsule", "2 5", "0 0 2 0 0 1 0", "base01" );
52506@endtsexample
52507*/
52508bool addPrimitive( string meshName, string type, string params, TransformF txfm, string nodeName );
52509/*!
52510@brief Autofit a mesh primitive or set of convex hulls to the shape geometry. Hulls may optionally be converted to boxes, spheres and/or capsules based on their volume.
52511
52512@param size size for this detail level
52513@param type one of: box, sphere, capsule, 10-dop x, 10-dop y, 10-dop z, 18-dop, 26-dop, convex hulls. See the Shape Editor documentation for more details about these types.
52514@param target geometry to fit collision mesh(es) to; either "bounds" (for the whole shape), or the name of an object in the shape
52515@param depth maximum split recursion depth (hulls only)
52516@param merge volume % threshold used to merge hulls together (hulls only)
52517@param concavity volume % threshold used to detect concavity (hulls only)
52518@param maxVerts maximum number of vertices per hull (hulls only)
52519@param boxMaxError max % volume difference for a hull to be converted to a box (hulls only)
52520@param sphereMaxError max % volume difference for a hull to be converted to a sphere (hulls only)
52521@param capsuleMaxError max % volume difference for a hull to be converted to a capsule (hulls only)
52522@return true if successful, false otherwise
52523
52524@tsexample
52525%this.addCollisionDetail( -1, "box", "bounds" );
52526%this.addCollisionDetail( -1, "convex hulls", "bounds", 4, 30, 30, 32, 0, 0, 0 );
52527%this.addCollisionDetail( -1, "convex hulls", "bounds", 4, 30, 30, 32, 50, 50, 50 );
52528@endtsexample
52529*/
52530bool addCollisionDetail( int size, string type, string target, int depth=4, float merge=30, float concavity=30, int maxVerts=32, float boxMaxError=0, float sphereMaxError=0, float capsuleMaxError=0 );
52531/*!
52532@brief Dump the shape hierarchy to the console or to a file. Useful for reviewing the result of a series of construction commands.
52533
52534@param filename Destination filename. If not specified, dump to console.
52535
52536@tsexample
52537%this.dumpShape();               // dump to console
52538%this.dumpShape( "./dump.txt" ); // dump to file
52539@endtsexample
52540*/
52541void dumpShape( string filename="" );
52542/*!
52543@brief Save the shape (with all current changes) to a new DTS file.
52544
52545@param filename Destination filename.
52546
52547@tsexample
52548%this.saveShape( "./myShape.dts" );
52549@endtsexample
52550*/
52551void saveShape( string filename );
52552/*!
52553@brief Write the current change set to a TSShapeConstructor script file. The name of the script file is the same as the model, but with .cs extension. eg. myShape.cs for myShape.dts or myShape.dae.
52554
52555*/
52556void writeChangeSet();
52557/*!
52558@brief Notify game objects that this shape file has changed, allowing them to update internal data if needed.
52559
52560*/
52561void notifyShapeChanged();
52562/*!
52563@brief Get the total number of nodes in the shape.
52564
52565@return the number of nodes in the shape.
52566
52567@tsexample
52568%count = %this.getNodeCount();
52569@endtsexample
52570*/
52571int getNodeCount();
52572/*!
52573@brief Get the index of the node.
52574
52575@param name name of the node to lookup.
52576@return the index of the named node, or -1 if no such node exists.
52577
52578@tsexample
52579// get the index of Bip01 Pelvis node in the shape
52580%index = %this.getNodeIndex( "Bip01 Pelvis" );
52581@endtsexample
52582*/
52583int getNodeIndex( string name );
52584/*!
52585@brief Get the name of the indexed node.
52586
52587@param index index of the node to lookup (valid range is 0 - getNodeCount()-1).
52588@return the name of the indexed node, or "" if no such node exists.
52589
52590@tsexample
52591// print the names of all the nodes in the shape
52592%count = %this.getNodeCount();
52593for (%i = 0; %i < %count; %i++)
52594   echo(%i SPC %this.getNodeName(%i));
52595@endtsexample
52596*/
52597string getNodeName( int index );
52598/*!
52599@brief Get the name of the node's parent. If the node has no parent (ie. it is at the root level), return an empty string.
52600
52601@param name name of the node to query.
52602@return the name of the node's parent, or "" if the node is at the root level
52603
52604@tsexample
52605echo( "Bip01 Pelvis parent = " @ %this.getNodeParentName( "Bip01 Pelvis ") );
52606@endtsexample
52607*/
52608string getNodeParentName( string name );
52609/*!
52610@brief Set the parent of a node.
52611
52612@param name name of the node to modify
52613@param parentName name of the parent node to set (use "" to move the node to the root level)
52614@return true if successful, false if failed
52615
52616@tsexample
52617%this.setNodeParent( "Bip01 Pelvis", "start01" );
52618@endtsexample
52619*/
52620bool setNodeParent( string name, string parentName );
52621/*!
52622@brief Get the number of children of this node.
52623
52624@param name name of the node to query.
52625@return the number of child nodes.
52626
52627@tsexample
52628%count = %this.getNodeChildCount( "Bip01 Pelvis" );
52629@endtsexample
52630*/
52631int getNodeChildCount( string name );
52632/*!
52633@brief Get the name of the indexed child node.
52634
52635@param name name of the parent node to query.
52636@param index index of the child node (valid range is 0 - getNodeChildName()-1).
52637@return the name of the indexed child node.
52638
52639@tsexample
52640function dumpNode( %shape, %name, %indent )
52641{
52642   echo( %indent @ %name );
52643   %count = %shape.getNodeChildCount( %name );
52644   for ( %i = 0; %i < %count; %i++ )
52645      dumpNode( %shape, %shape.getNodeChildName( %name, %i ), %indent @ "   " );
52646}
52647
52648function dumpShape( %shape )
52649{
52650   // recursively dump node hierarchy
52651   %count = %shape.getNodeCount();
52652   for ( %i = 0; %i < %count; %i++ )
52653   {
52654      // dump top level nodes
52655      %name = %shape.getNodeName( %i );
52656      if ( %shape.getNodeParentName( %name ) $=  )
52657         dumpNode( %shape, %name, "" );
52658   }
52659}
52660@endtsexample
52661*/
52662string getNodeChildName( string name, int index );
52663/*!
52664@brief Get the number of geometry objects attached to this node.
52665
52666@param name name of the node to query.
52667@return the number of attached objects.
52668
52669@tsexample
52670%count = %this.getNodeObjectCount( "Bip01 Head" );
52671@endtsexample
52672*/
52673int getNodeObjectCount( string name );
52674/*!
52675@brief Get the name of the indexed object.
52676
52677@param name name of the node to query.
52678@param index index of the object (valid range is 0 - getNodeObjectCount()-1).
52679@return the name of the indexed object.
52680
52681@tsexample
52682// print the names of all objects attached to the node
52683%count = %this.getNodeObjectCount( "Bip01 Head" );
52684for ( %i = 0; %i < %count; %i++ )
52685   echo( %this.getNodeObjectName( "Bip01 Head", %i ) );
52686@endtsexample
52687*/
52688string getNodeObjectName( string name, int index );
52689/*!
52690@brief Get the base (ie. not animated) transform of a node.
52691
52692@param name name of the node to query.
52693@param isWorld true to get the global transform, false (or omitted) to get the local-to-parent transform.
52694@return the node transform in the form "pos.x pos.y pos.z rot.x rot.y rot.z rot.angle".
52695
52696@tsexample
52697%ret = %this.getNodeTransform( "mount0" );
52698%this.setNodeTransform( "mount4", %ret );
52699@endtsexample
52700*/
52701TransformF getNodeTransform( string name, bool isWorld=false );
52702/*!
52703@brief Set the base transform of a node. That is, the transform of the node when in the root (not-animated) pose.
52704
52705@param name name of the node to modify
52706@param txfm transform string of the form: "pos.x pos.y pos.z rot.x rot.y rot.z rot.angle"
52707@param isworld (optional) flag to set the local-to-parent or the global transform. If false, or not specified, the position and orientation are treated as relative to the node's parent.
52708@return true if successful, false otherwise
52709
52710@tsexample
52711%this.setNodeTransform( "mount0", "0 0 1 0 0 1 0" );
52712%this.setNodeTransform( "mount0", "0 0 0 0 0 1 1.57" );
52713%this.setNodeTransform( "mount0", "1 0 0 0 0 1 0", true );
52714@endtsexample
52715*/
52716bool setNodeTransform( string name, TransformF txfm, bool isWorld=false );
52717/*!
52718@brief Rename a node.
52719
52720@note Note that node names must be unique, so this command will fail if there is already a node with the desired name
52721@param oldName current name of the node
52722@param newName new name of the node
52723@return true if successful, false otherwise
52724
52725@tsexample
52726%this.renameNode( "Bip01 L Hand", "mount5" );
52727@endtsexample
52728*/
52729bool renameNode( string oldName, string newName );
52730/*!
52731@brief Add a new node.
52732
52733@param name name for the new node (must not already exist)
52734@param parentName name of an existing node to be the parent of the new node. If empty (""), the new node will be at the root level of the node hierarchy.
52735@param txfm (optional) transform string of the form: "pos.x pos.y pos.z rot.x rot.y rot.z rot.angle"
52736@param isworld (optional) flag to set the local-to-parent or the global transform. If false, or not specified, the position and orientation are treated as relative to the node's parent.
52737@return true if successful, false otherwise
52738
52739@tsexample
52740%this.addNode( "Nose", "Bip01 Head", "0 2 2 0 0 1 0" );
52741%this.addNode( "myRoot", "", "0 0 4 0 0 1 1.57" );
52742%this.addNode( "Nodes", "Bip01 Head", "0 2 0 0 0 1 0", true );
52743@endtsexample
52744*/
52745bool addNode( string name, string parentName, TransformF txfm=TransformF::Identity, bool isWorld=false );
52746/*!
52747@brief Remove a node from the shape.
52748
52749The named node is removed from the shape, including from any sequences that use the node. Child nodes and objects attached to the node are re-assigned to the node's parent.
52750@param name name of the node to remove.
52751@return true if successful, false otherwise.
52752
52753@tsexample
52754%this.removeNode( "Nose" );
52755@endtsexample
52756*/
52757bool removeNode( string name );
52758/*!
52759@brief Get the number of materials in the shape.
52760
52761@return the number of materials in the shape.
52762
52763@tsexample
52764%count = %this.getTargetCount();
52765@endtsexample
52766*/
52767int getTargetCount();
52768/*!
52769@brief Get the name of the indexed shape material.
52770
52771@param index index of the material to get (valid range is 0 - getTargetCount()-1).
52772@return the name of the indexed material.
52773
52774@tsexample
52775%count = %this.getTargetCount();
52776for ( %i = 0; %i < %count; %i++ )
52777   echo( "Target " @ %i @ ": " @ %this.getTargetName( %i ) );
52778@endtsexample
52779*/
52780string getTargetName( int index );
52781/*!
52782@brief Get the total number of objects in the shape.
52783
52784@return the number of objects in the shape.
52785
52786@tsexample
52787%count = %this.getObjectCount();
52788@endtsexample
52789*/
52790int getObjectCount();
52791/*!
52792@brief Get the name of the indexed object.
52793
52794@param index index of the object to get (valid range is 0 - getObjectCount()-1).
52795@return the name of the indexed object.
52796
52797@tsexample
52798// print the names of all objects in the shape
52799%count = %this.getObjectCount();
52800for ( %i = 0; %i < %count; %i++ )
52801   echo( %i SPC %this.getObjectName( %i ) );
52802@endtsexample
52803*/
52804string getObjectName( int index );
52805/*!
52806@brief Get the index of the first object with the given name.
52807
52808@param name name of the object to get.
52809@return the index of the named object.
52810
52811@tsexample
52812%index = %this.getObjectIndex( "Head" );
52813@endtsexample
52814*/
52815int getObjectIndex( string name );
52816/*!
52817@brief Get the name of the node this object is attached to.
52818
52819@param name name of the object to get.
52820@return the name of the attached node, or an empty string if this object is not attached to a node (usually the case for skinned meshes).
52821
52822@tsexample
52823echo( "Hand is attached to " @ %this.getObjectNode( "Hand" ) );
52824@endtsexample
52825*/
52826string getObjectNode( string name );
52827/*!
52828@brief Set the node an object is attached to.
52829
52830When the shape is rendered, the object geometry is rendered at the node's current transform.
52831@param objName name of the object to modify
52832@param nodeName name of the node to attach the object to
52833@return true if successful, false otherwise
52834
52835@tsexample
52836%this.setObjectNode( "Hand", "Bip01 LeftHand" );
52837@endtsexample
52838*/
52839bool setObjectNode( string objName, string nodeName );
52840/*!
52841@brief Rename an object.
52842
52843@note Note that object names must be unique, so this command will fail if there is already an object with the desired name
52844@param oldName current name of the object
52845@param newName new name of the object
52846@return true if successful, false otherwise
52847
52848@tsexample
52849%this.renameObject( "MyBox", "Box" );
52850@endtsexample
52851*/
52852bool renameObject( string oldName, string newName );
52853/*!
52854@brief Remove an object (including all meshes for that object) from the shape.
52855
52856@param name name of the object to remove.
52857@return true if successful, false otherwise.
52858
52859@tsexample
52860// clear all objects in the shape
52861%count = %this.getObjectCount();
52862for ( %i = %count-1; %i >= 0; %i-- )
52863   %this.removeObject( %this.getObjectName(%i) );
52864@endtsexample
52865*/
52866bool removeObject( string name );
52867/*!
52868@brief Get the number of meshes (detail levels) for the specified object.
52869
52870@param name name of the object to query
52871@return the number of meshes for this object.
52872
52873@tsexample
52874%count = %this.getMeshCount( "SimpleShape" );
52875@endtsexample
52876*/
52877int getMeshCount( string name );
52878/*!
52879@brief Get the name of the indexed mesh (detail level) for the specified object.
52880
52881@param name name of the object to query
52882@param index index of the mesh (valid range is 0 - getMeshCount()-1)
52883@return the mesh name.
52884
52885@tsexample
52886// print the names of all meshes in the shape
52887%objCount = %this.getObjectCount();
52888for ( %i = 0; %i < %objCount; %i++ )
52889{
52890   %objName = %this.getObjectName( %i );
52891   %meshCount = %this.getMeshCount( %objName );
52892   for ( %j = 0; %j < %meshCount; %j++ )
52893      echo( %this.getMeshName( %objName, %j ) );
52894}
52895@endtsexample
52896*/
52897string getMeshName( string name, int index );
52898/*!
52899@brief Get the detail level size of the indexed mesh for the specified object.
52900
52901@param name name of the object to query
52902@param index index of the mesh (valid range is 0 - getMeshCount()-1)
52903@return the mesh detail level size.
52904
52905@tsexample
52906// print sizes for all detail levels of this object
52907%objName = "trunk";
52908%count = %this.getMeshCount( %objName );
52909for ( %i = 0; %i < %count; %i++ )
52910   echo( %this.getMeshSize( %objName, %i ) );
52911@endtsexample
52912*/
52913int getMeshSize( string name, int index );
52914/*!
52915@brief Change the detail level size of the named mesh.
52916
52917@param name full name (object name + current size ) of the mesh to modify
52918@param size new detail level size
52919@return true if successful, false otherwise.
52920
52921@tsexample
52922%this.setMeshSize( "SimpleShape128", 64 );
52923@endtsexample
52924*/
52925bool setMeshSize( string name, int size );
52926/*!
52927@brief Get the display type of the mesh.
52928
52929@param name name of the mesh to query
52930@return the string returned is one of:<dl><dt>normal</dt><dd>a normal 3D mesh</dd><dt>billboard</dt><dd>a mesh that always faces the camera</dd><dt>billboardzaxis</dt><dd>a mesh that always faces the camera in the Z-axis</dd></dl>
52931
52932@tsexample
52933echo( "Mesh type is " @ %this.getMeshType( "SimpleShape128" ) );
52934@endtsexample
52935*/
52936string getMeshType( string name );
52937/*!
52938@brief Set the display type for the mesh.
52939
52940@param name full name (object name + detail size) of the mesh to modify
52941@param type the new type for the mesh: "normal", "billboard" or "billboardzaxis"
52942@return true if successful, false otherwise
52943
52944@tsexample
52945// set the mesh to be a billboard
52946%this.setMeshType( "SimpleShape64", "billboard" );
52947@endtsexample
52948*/
52949bool setMeshType( string name, string type );
52950/*!
52951@brief Get the name of the material attached to a mesh. Note that only the first material used by the mesh is returned.
52952
52953@param name full name (object name + detail size) of the mesh to query
52954@return name of the material attached to the mesh (suitable for use with the Material mapTo field)
52955
52956@tsexample
52957echo( "Mesh material is " @ %this.sgetMeshMaterial( "SimpleShape128" ) );
52958@endtsexample
52959*/
52960string getMeshMaterial( string name );
52961/*!
52962@brief Set the name of the material attached to the mesh.
52963
52964@param meshName full name (object name + detail size) of the mesh to modify
52965@param matName name of the material to attach. This could be the base name of the diffuse texture (eg. "test_mat" for "test_mat.jpg"), or the name of a Material object already defined in script.
52966@return true if successful, false otherwise
52967
52968@tsexample
52969// set the mesh material
52970%this.setMeshMaterial( "SimpleShape128", "test_mat" );
52971@endtsexample
52972*/
52973bool setMeshMaterial( string meshName, string matName );
52974/*!
52975@brief Add geometry from another DTS or DAE shape file into this shape.
52976
52977Any materials required by the source mesh are also copied into this shape.<br>
52978@param meshName full name (object name + detail size) of the new mesh. If no detail size is present at the end of the name, a value of 2 is used.<br>An underscore before the number at the end of the name will be interpreted as a negative sign. eg. "MyMesh_4" will be interpreted as "MyMesh-4".
52979@param srcShape name of a shape file (DTS or DAE) that contains the mesh
52980@param srcMesh the full name (object name + detail size) of the mesh to copy from the DTS/DAE file into this shape</li>@return true if successful, false otherwise
52981
52982@tsexample
52983%this.addMesh( "ColMesh-1", "./collision.dts", "ColMesh", "Col-1" );
52984%this.addMesh( "SimpleShape10", "./testShape.dae", "MyMesh2",  );
52985@endtsexample
52986*/
52987bool addMesh( string meshName, string srcShape, string srcMesh );
52988/*!
52989@brief Remove a mesh from the shape.
52990
52991If all geometry is removed from an object, the object is also removed.
52992@param name full name (object name + detail size) of the mesh to remove
52993@return true if successful, false otherwise
52994
52995@tsexample
52996%this.removeMesh( "SimpleShape128" );
52997@endtsexample
52998*/
52999bool removeMesh( string name );
53000/*!
53001@brief Get the bounding box for the shape.
53002
53003@return Bounding box "minX minY minZ maxX maxY maxZ"*/
53004Box3F getBounds();
53005/*!
53006@brief Set the shape bounds to the given bounding box.
53007
53008@param Bounding box "minX minY minZ maxX maxY maxZ"
53009@return true if successful, false otherwise
53010*/
53011bool setBounds( Box3F bbox );
53012/*!
53013@brief Get the total number of detail levels in the shape.
53014
53015@return the number of detail levels in the shape
53016*/
53017int getDetailLevelCount();
53018/*!
53019@brief Get the name of the indexed detail level.
53020
53021@param index detail level index (valid range is 0 - getDetailLevelCount()-1)
53022@return the detail level name
53023
53024@tsexample
53025// print the names of all detail levels in the shape
53026%count = %this.getDetailLevelCount();
53027for ( %i = 0; %i < %count; %i++ )
53028   echo( %i SPC %this.getDetailLevelName( %i ) );
53029@endtsexample
53030*/
53031string getDetailLevelName( int index );
53032/*!
53033@brief Get the size of the indexed detail level.
53034
53035@param index detail level index (valid range is 0 - getDetailLevelCount()-1)
53036@return the detail level size
53037
53038@tsexample
53039// print the sizes of all detail levels in the shape
53040%count = %this.getDetailLevelCount();
53041for ( %i = 0; %i < %count; %i++ )
53042   echo( "Detail" @ %i @ " has size " @ %this.getDetailLevelSize( %i ) );
53043@endtsexample
53044*/
53045int getDetailLevelSize( int index );
53046/*!
53047@brief Get the index of the detail level with a given size.
53048
53049@param size size of the detail level to lookup
53050@return index of the detail level with the desired size, or -1 if no such detail exists
53051
53052@tsexample
53053if ( %this.getDetailLevelSize( 32 ) == -1 )
53054   echo( "Error: This shape does not have a detail level at size 32" );
53055@endtsexample
53056*/
53057int getDetailLevelIndex( int size );
53058/*!
53059@brief Rename a detail level.
53060
53061@note Note that detail level names must be unique, so this command will fail if there is already a detail level with the desired name
53062@param oldName current name of the detail level
53063@param newName new name of the detail level
53064@return true if successful, false otherwise
53065
53066@tsexample
53067%this.renameDetailLevel( "detail-1", "collision-1" );
53068@endtsexample
53069*/
53070bool renameDetailLevel( string oldName, string newName );
53071/*!
53072@brief Remove the detail level (including all meshes in the detail level)
53073
53074@param size size of the detail level to remove
53075@return true if successful, false otherwise
53076@tsexample
53077%this.removeDetailLevel( 2 );
53078@endtsexample
53079*/
53080bool removeDetailLevel( int index );
53081/*!
53082@brief Change the size of a detail level.@note Note that detail levels are always sorted in decreasing size order, so this command may cause detail level indices to change.
53083
53084@param index index of the detail level to modify
53085@param newSize new size for the detail level
53086@return new index for this detail level
53087
53088@tsexample
53089%this.setDetailLevelSize( 2, 256 );
53090@endtsexample
53091*/
53092int setDetailLevelSize( int index, int newSize );
53093/*!
53094@brief Get the index of the imposter (auto-billboard) detail level (if any).
53095
53096@return imposter detail level index, or -1 if the shape does not use imposters.
53097
53098*/
53099int getImposterDetailLevel();
53100/*!
53101@brief Get the settings used to generate imposters for the indexed detail level.
53102
53103@param index index of the detail level to query (does not need to be an imposter detail level
53104@return string of the form: "valid eqSteps pSteps dl dim poles angle", where:<dl><dt>valid</dt><dd>1 if this detail level generates imposters, 0 otherwise</dd><dt>eqSteps</dt><dd>number of steps around the equator</dd><dt>pSteps</dt><dd>number of steps between the poles</dd><dt>dl</dt><dd>index of the detail level used to generate imposters</dd><dt>dim</dt><dd>size (in pixels) of each imposter image</dd><dt>poles</dt><dd>1 to include pole images, 0 otherwise</dd><dt>angle</dt><dd>angle at which to display pole images</dd></dl>
53105
53106@tsexample
53107// print the imposter detail level settings
53108%index = %this.getImposterDetailLevel();
53109if ( %index != -1 )
53110   echo( "Imposter settings: " @ %this.getImposterSettings( %index ) );
53111@endtsexample
53112*/
53113string getImposterSettings( int index );
53114/*!
53115@brief Add (or edit) an imposter detail level to the shape.
53116
53117If the shape already contains an imposter detail level, this command will simply change the imposter settings
53118@param size size of the imposter detail level
53119@param equatorSteps defines the number of snapshots to take around the equator. Imagine the object being rotated around the vertical axis, then a snapshot taken at regularly spaced intervals.
53120@param polarSteps defines the number of snapshots taken between the poles (top and bottom), at each equator step. eg. At each equator snapshot, snapshots are taken at regular intervals between the poles.
53121@param dl the detail level to use when generating the snapshots. Note that this is an array index rather than a detail size. So if an object has detail sizes of: 200, 150, and 40, then setting @a dl to 1 will generate the snapshots using detail size 150.
53122@param dim defines the size of the imposter images in pixels. The larger the number, the more detailed the billboard will be.
53123@param includePoles flag indicating whether to include the "pole" snapshots. ie. the views from the top and bottom of the object.
53124@param polar_angle if pole snapshots are active (@a includePoles is true), this parameter defines the camera angle (in degrees) within which to render the pole snapshot. eg. if polar_angle is set to 25 degrees, then the snapshot taken at the pole (looking directly down or up at the object) will be rendered when the camera is within 25 degrees of the pole.
53125@return true if successful, false otherwise
53126
53127@tsexample
53128%this.addImposter( 2, 4, 0, 0, 64, false, 0 );
53129%this.addImposter( 2, 4, 2, 0, 64, true, 10 );   // this command would edit the existing imposter detail level
53130@endtsexample
53131*/
53132int addImposter( int size, int equatorSteps, int polarSteps, int dl, int dim, bool includePoles, float polarAngle );
53133/*!
53134@brief Remove the imposter detail level (if any) from the shape.
53135
53136@return true if successful, false otherwise
53137
53138*/
53139bool removeImposter();
53140/*!
53141@brief Get the total number of sequences in the shape.
53142
53143@return the number of sequences in the shape
53144
53145*/
53146int getSequenceCount();
53147/*!
53148@brief Find the index of the sequence with the given name.
53149
53150@param name name of the sequence to lookup
53151@return index of the sequence with matching name, or -1 if not found
53152
53153@tsexample
53154// Check if a given sequence exists in the shape
53155if ( %this.getSequenceIndex( "walk" ) == -1 )
53156   echo( "Could not find 'walk' sequence" );
53157@endtsexample
53158*/
53159int getSequenceIndex( string name );
53160/*!
53161@brief Get the name of the indexed sequence.
53162
53163@param index index of the sequence to query (valid range is 0 - getSequenceCount()-1)
53164@return the name of the sequence
53165
53166@tsexample
53167// print the name of all sequences in the shape
53168%count = %this.getSequenceCount();
53169for ( %i = 0; %i < %count; %i++ )
53170   echo( %i SPC %this.getSequenceName( %i ) );
53171@endtsexample
53172*/
53173string getSequenceName( int index );
53174/*!
53175@brief Get information about where the sequence data came from.
53176
53177For example, whether it was loaded from an external DSQ file.
53178@param name name of the sequence to query
53179@return TAB delimited string of the form: "from reserved start end total", where:<dl><dt>from</dt><dd>the source of the animation data, such as the path to a DSQ file, or the name of an existing sequence in the shape. This field will be empty for sequences already embedded in the DTS or DAE file.</dd><dt>reserved</dt><dd>reserved value</dd><dt>start</dt><dd>the first frame in the source sequence used to create this sequence</dd><dt>end</dt><dd>the last frame in the source sequence used to create this sequence</dd><dt>total</dt><dd>the total number of frames in the source sequence</dd></dl>
53180
53181@tsexample
53182// print the source for the walk animation
53183echo( "walk source:" SPC getField( %this.getSequenceSource( "walk" ), 0 ) );
53184@endtsexample
53185*/
53186string getSequenceSource( string name );
53187/*!
53188@brief Get the number of keyframes in the sequence.
53189
53190@param name name of the sequence to query
53191@return number of keyframes in the sequence
53192
53193@tsexample
53194echo( "Run has " @ %this.getSequenceFrameCount( "run" ) @ " keyframes" );
53195@endtsexample
53196*/
53197int getSequenceFrameCount( string name );
53198/*!
53199@brief Get the priority setting of the sequence.
53200
53201@param name name of the sequence to query
53202@return priority value of the sequence
53203
53204*/
53205float getSequencePriority( string name );
53206/*!
53207@brief Set the sequence priority.
53208
53209@param name name of the sequence to modify
53210@param priority new priority value
53211@return true if successful, false otherwise
53212
53213*/
53214bool setSequencePriority( string name, float priority );
53215/*!
53216@brief Get the ground speed of the sequence.
53217
53218@note Note that only the first 2 ground frames of the sequence are examined; the speed is assumed to be constant throughout the sequence.
53219@param name name of the sequence to query
53220@return string of the form: "trans.x trans.y trans.z rot.x rot.y rot.z"
53221
53222@tsexample
53223%speed = VectorLen( getWords( %this.getSequenceGroundSpeed( "run" ), 0, 2 ) );
53224   echo( "Run moves at " @ %speed @ " units per frame" );
53225@endtsexample
53226*/
53227string getSequenceGroundSpeed( string name );
53228/*!
53229@brief Set the translation and rotation ground speed of the sequence.
53230
53231The ground speed of the sequence is set by generating ground transform keyframes. The ground translational and rotational speed is assumed to be constant for the duration of the sequence. Existing ground frames for the sequence (if any) will be replaced.
53232@param name name of the sequence to modify
53233@param transSpeed translational speed (trans.x trans.y trans.z) in Torque units per frame
53234@param rotSpeed (optional) rotational speed (rot.x rot.y rot.z) in radians per frame. Default is "0 0 0"
53235@return true if successful, false otherwise
53236
53237@tsexample
53238%this.setSequenceGroundSpeed( "run", "5 0 0" );
53239%this.setSequenceGroundSpeed( "spin", "0 0 0", "4 0 0" );
53240@endtsexample
53241*/
53242bool setSequenceGroundSpeed( string name, Point3F transSpeed, Point3F rotSpeed=Point3F::Zero );
53243/*!
53244@brief Check if this sequence is cyclic (looping).
53245
53246@param name name of the sequence to query
53247@return true if this sequence is cyclic, false if not
53248
53249@tsexample
53250if ( !%this.getSequenceCyclic( "ambient" ) )
53251   error( "ambient sequence is not cyclic!" );
53252@endtsexample
53253*/
53254bool getSequenceCyclic( string name );
53255/*!
53256@brief Mark a sequence as cyclic or non-cyclic.
53257
53258@param name name of the sequence to modify
53259@param cyclic true to make the sequence cyclic, false for non-cyclic
53260@return true if successful, false otherwise
53261
53262@tsexample
53263%this.setSequenceCyclic( "ambient", true );
53264%this.setSequenceCyclic( "shoot", false );
53265@endtsexample
53266*/
53267bool setSequenceCyclic( string name, bool cyclic );
53268/*!
53269@brief Get information about blended sequences.
53270
53271@param name name of the sequence to query
53272@return TAB delimited string of the form: "isBlend blendSeq blendFrame", where:<dl><dt>blend_flag</dt><dd>a boolean flag indicating whether this sequence is a blend</dd><dt>blend_seq_name</dt><dd>the name of the sequence that contains the reference frame (empty for blend sequences embedded in DTS files)</dd><dt>blend_seq_frame</dt><dd>the blend reference frame (empty for blend sequences embedded in DTS files)</dd></dl>
53273@note Note that only sequences set to be blends using the setSequenceBlend command will contain the blendSeq and blendFrame information.
53274
53275@tsexample
53276%blendData = %this.getSequenceBlend( "look" );
53277if ( getField( %blendData, 0 ) )
53278   echo( "look is a blend, reference: " @ getField( %blendData, 1 ) );
53279@endtsexample
53280*/
53281string getSequenceBlend( string name );
53282/*!
53283@brief Mark a sequence as a blend or non-blend.
53284
53285A blend sequence is one that will be added on top of any other playing sequences. This is done by storing the animated node transforms relative to a reference frame, rather than as absolute transforms.
53286@param name name of the sequence to modify
53287@param blend true to make the sequence a blend, false for a non-blend
53288@param blendSeq the name of the sequence that contains the blend reference frame
53289@param blendFrame the reference frame in the blendSeq sequence
53290@return true if successful, false otherwise
53291
53292@tsexample
53293%this.setSequenceBlend( "look", true, "root", 0 );
53294@endtsexample
53295*/
53296bool setSequenceBlend( string name, bool blend, string blendSeq, int blendFrame );
53297/*!
53298@brief Rename a sequence.
53299
53300@note Note that sequence names must be unique, so this command will fail if there is already a sequence with the desired name
53301@param oldName current name of the sequence
53302@param newName new name of the sequence
53303@return true if successful, false otherwise
53304
53305@tsexample
53306%this.renameSequence( "walking", "walk" );
53307@endtsexample
53308*/
53309bool renameSequence( string oldName, string newName );
53310/*!
53311@brief Add a new sequence to the shape.
53312
53313@param source the name of an existing sequence, or the name of a DTS or DAE shape or DSQ sequence file. When the shape file contains more than one sequence, the desired sequence can be specified by appending the name to the end of the shape file. eg. "myShape.dts run" would select the "run" sequence from the "myShape.dts" file.
53314
53315@param name name of the new sequence
53316@param start (optional) first frame to copy. Defaults to 0, the first frame in the sequence.
53317@param end (optional) last frame to copy. Defaults to -1, the last frame in the sequence.
53318@param padRot (optional) copy root-pose rotation keys for non-animated nodes. This is useful if the source sequence data has a different root-pose to the target shape, such as if one character was in the T pose, and the other had arms at the side. Normally only nodes that are actually rotated by the source sequence have keyframes added, but setting this flag will also add keyframes for nodes that are not animated, but have a different root-pose rotation to the target shape root pose.
53319@param padTrans (optional) copy root-pose translation keys for non-animated nodes.  This is useful if the source sequence data has a different root-pose to the target shape, such as if one character was in the T pose, and the other had arms at the side. Normally only nodes that are actually moved by the source sequence have keyframes added, but setting this flag will also add keyframes for nodes that are not animated, but have a different root-pose position to the target shape root pose.
53320@return true if successful, false otherwise
53321
53322@tsexample
53323%this.addSequence( "./testShape.dts ambient", "ambient" );
53324%this.addSequence( "./myPlayer.dae run", "run" );
53325%this.addSequence( "./player_look.dsq", "look", 0, -1 );     // start to end
53326%this.addSequence( "walk", "walk_shortA", 0, 4 );            // start to frame 4
53327%this.addSequence( "walk", "walk_shortB", 4, -1 );           // frame 4 to end
53328@endtsexample
53329*/
53330bool addSequence( string source, string name, int start=0, int end=-1, bool padRot=true, bool padTrans=false );
53331/*!
53332@brief Remove the sequence from the shape.
53333
53334@param name name of the sequence to remove
53335@return true if successful, false otherwise
53336
53337*/
53338bool removeSequence( string name );
53339/*!
53340@brief Get the number of triggers in the specified sequence.
53341
53342@param name name of the sequence to query
53343@return number of triggers in the sequence
53344
53345*/
53346int getTriggerCount( string name );
53347/*!
53348@brief Get information about the indexed trigger
53349
53350@param name name of the sequence to query
53351@param index index of the trigger (valid range is 0 - getTriggerCount()-1)
53352@return string of the form "frame state"
53353
53354@tsexample
53355// print all triggers in the sequence
53356%count = %this.getTriggerCount( "back" );
53357for ( %i = 0; %i < %count; %i++ )
53358   echo( %i SPC %this.getTrigger( "back", %i ) );
53359@endtsexample
53360*/
53361string getTrigger( string name, int index );
53362/*!
53363@brief Add a new trigger to the sequence.
53364
53365@param name name of the sequence to modify
53366@param keyframe keyframe of the new trigger
53367@param state of the new trigger
53368@return true if successful, false otherwise
53369
53370@tsexample
53371%this.addTrigger( "walk", 3, 1 );
53372%this.addTrigger( "walk", 5, -1 );
53373@endtsexample
53374*/
53375bool addTrigger( string name, int keyframe, int state );
53376/*!
53377@brief Remove a trigger from the sequence.
53378
53379@param name name of the sequence to modify
53380@param keyframe keyframe of the trigger to remove
53381@param state of the trigger to remove
53382@return true if successful, false otherwise
53383
53384@tsexample
53385%this.removeTrigger( "walk", 3, 1 );
53386@endtsexample
53387*/
53388bool removeTrigger( string name, int keyframe, int state );
53389
53390/*! @name Callbacks
53391@{ */
53392/*!
53393@brief Called immediately after the DTS or DAE file has been loaded; before the shape data is available to any other object (StaticShape, Player etc). This is where you should put any post-load commands to modify the shape in-memory such as addNode, renameSequence etc.
53394
53395*/
53396void onLoad();
53397/*!
53398@brief Called when the DTS or DAE resource is flushed from memory. Not normally required, but may be useful to perform cleanup.
53399
53400*/
53401void onUnload();
53402/// @}
53403
53404
53405/*! @name Media
53406@{ */
53407/*!
53408@brief Specifies the path to the DTS or DAE file to be operated on by this object.
53409
53410Since the TSShapeConstructor script must be in the same folder as the DTS or DAE file, it is recommended to use a relative path so that the shape and script files can be copied to another location without having to modify the path.
53411*/
53412filename baseShape;
53413/// @}
53414
53415
53416/*! @name Collada
53417@{ */
53418/*!
53419@brief Override the <up_axis> element in the COLLADA (.dae) file. No effect for DTS files.
53420
53421Set to one of the following values:
53422<dl><dt>X_AXIS</dt><dd>Positive X points up. Model will be rotated into Torque's coordinate system (Z up).</dd><dt>Y_AXIS</dt><dd>Positive Y points up. Model will be rotated into Torque's coordinate system (Z up).</dd><dt>Z_AXIS</dt><dd>Positive Z points up. No rotation will be applied to the model.</dd><dt>DEFAULT</dt><dd>The default value. Use the value in the .dae file (defaults to Z_AXIS if the <up_axis> element is not present).</dd></dl>
53423*/
53424TSShapeConstructorUpAxis upAxis;
53425/*!
53426@brief Override the <unit> element in the COLLADA (.dae) file. No effect for DTS files.
53427
53428COLLADA (.dae) files usually contain a <unit> element that indicates the 'real world' units that the model is described in. It means you can work in sensible and meaningful units in your modeling app.<br>
53429For example, if you were modeling a small object like a cup, it might make sense to work in inches (1 MAX unit = 1 inch), but if you were modeling a building, it might make more sense to work in feet (1 MAX unit = 1 foot). If you export both models to COLLADA, T3D will automatically scale them appropriately. 1 T3D unit = 1 meter, so the cup would be scaled down by 0.0254, and the building scaled down by 0.3048, given them both the correct scale relative to each other.<br>
53430Omit the field or set to -1 to use the value in the .dae file (1.0 if the <unit> element is not present)
53431*/
53432float unit;
53433/*!
53434@brief Control how the COLLADA (.dae) importer interprets LOD in the model. No effect for DTS files.
53435
53436Set to one of the following values:
53437<dl><dt>DetectDTS</dt><dd>The default value. Instructs the importer to search for a 'baseXXX->startXXX' node hierarchy at the root level. If found, the importer acts as if ''TrailingNumber'' was set. Otherwise, all geometry is imported at a single detail size.</dd><dt>SingleSize</dt><dd>All geometry is imported at a fixed detail size. Numbers at the end of geometry node's are ignored.</dd><dt>TrailingNumber</dt><dd>Numbers at the end of geometry node's name are interpreted as the detail size (similar to DTS exporting). Geometry instances with the same base name but different trailing number are grouped into the same object.</dd><dt>DEFAULT</dt><dd>The default value. Use the value in the .dae file (defaults to Z_AXIS if the <up_axis> element is not present).</dd></dl>
53438*/
53439TSShapeConstructorLodType LODType;
53440/*!
53441@brief Sets the detail size when lodType is set to SingleSize. No effect otherwise, and no effect for DTS files.
53442
53443@see lodType
53444*/
53445int singleDetailSize;
53446/*!
53447@brief Prefix to apply to all material map names in the COLLADA (.dae) file. No effect for DTS files.
53448
53449This field is useful to avoid material name clashes for exporters that generate generic material names like "texture0" or "material1".
53450*/
53451string matNamePrefix;
53452/*!
53453@brief TAB separated patterns of nodes to import even if in neverImport list. No effect for DTS files.
53454
53455Torque allows unwanted nodes in COLLADA (.dae) files to to be ignored during import. This field contains a TAB separated list of patterns to match node names. Any node that matches one of the patterns in the list will <b>always</b> be imported, even if it also matches the neverImport list
53456@see neverImport
53457
53458@tsexample
53459singleton TSShapeConstructor(MyShapeDae)
53460{
53461   baseShape = "./myShape.dae";
53462   alwaysImport = "mount*" TAB "eye";
53463   neverImport = "*-PIVOT";
53464}
53465@endtsexample
53466*/
53467string alwaysImport;
53468/*!
53469@brief TAB separated patterns of nodes to ignore on loading. No effect for DTS files.
53470
53471Torque allows unwanted nodes in COLLADA (.dae) files to to be ignored during import. This field contains a TAB separated list of patterns to match node names. Any node that matches one of the patterns in the list will not be imported (unless it matches the alwaysImport list.
53472@see alwaysImport
53473*/
53474string neverImport;
53475/*!
53476@brief TAB separated patterns of meshes to import even if in neverImportMesh list. No effect for DTS files.
53477
53478Torque allows unwanted meshes in COLLADA (.dae) files to to be ignored during import. This field contains a TAB separated list of patterns to match mesh names. Any mesh that matches one of the patterns in the list will <b>always</b> be imported, even if it also matches the neverImportMesh list
53479@see neverImportMesh
53480
53481@tsexample
53482singleton TSShapeConstructor(MyShapeDae)
53483{
53484   baseShape = "./myShape.dae";
53485   alwaysImportMesh = "body*" TAB "armor" TAB "bounds";
53486   neverImportMesh = "*-dummy";
53487}
53488@endtsexample
53489*/
53490string alwaysImportMesh;
53491/*!
53492@brief TAB separated patterns of meshes to ignore on loading. No effect for DTS files.
53493
53494Torque allows unwanted meshes in COLLADA (.dae) files to to be ignored during import. This field contains a TAB separated list of patterns to match mesh names. Any mesh that matches one of the patterns in the list will not be imported (unless it matches the alwaysImportMesh list.
53495@see alwaysImportMesh
53496*/
53497string neverImportMesh;
53498/*!
53499@brief TAB separated patterns of materials to ignore on loading. No effect for DTS files.
53500
53501Torque allows unwanted materials in COLLADA (.dae) files to to be ignored during import. This field contains a TAB separated list of patterns to match material names. Any material that matches one of the patterns in the list will not be imported
53502*/
53503string neverImportMat;
53504/*!
53505@brief Ignore <scale> elements inside COLLADA <node>s. No effect for DTS files.
53506
53507This field is a workaround for certain exporters that generate bad node scaling, and is not usually required.
53508*/
53509bool IgnoreNodeScale;
53510/*!
53511@brief Translate COLLADA model on import so the origin is at the center. No effect for DTS files.
53512*/
53513bool AdjustCenter;
53514/*!
53515@brief Translate COLLADA model on import so origin is at the (Z axis) bottom of the model. No effect for DTS files.
53516
53517This can be used along with adjustCenter to have the origin at the center of the bottom of the model.
53518@see adjustCenter
53519*/
53520bool AdjustFloor;
53521/*!
53522@brief Forces update of the materials.cs file in the same folder as the COLLADA (.dae) file, even if Materials already exist. No effect for DTS files.
53523
53524Normally only Materials that are not already defined are written to materials.cs.
53525*/
53526bool forceUpdateMaterials;
53527/*!
53528@brief Convert to left handed coordinate system.
53529*/
53530bool convertLeftHanded;
53531/*!
53532@brief Calculate tangents and bitangents, if possible.
53533*/
53534bool calcTangentSpace;
53535/*!
53536@brief Convert spherical, cylindrical, box and planar mapping to proper UVs.
53537*/
53538bool genUVCoords;
53539/*!
53540@brief Preprocess UV transformations (scaling, translation ...).
53541*/
53542bool transformUVCoords;
53543/*!
53544@brief This step flips all UV coordinates along the y-axis and adjusts material settings and bitangents accordingly.
53545
53546Assimp uses TL(0,0):BR(1,1). T3D uses TL(0,1):BR(1,0). This will be needed for most textured models.
53547*/
53548bool flipUVCoords;
53549/*!
53550@brief Search for instanced meshes and remove them by references to one master.
53551*/
53552bool findInstances;
53553/*!
53554@brief Limit bone weights to 4 per vertex.
53555*/
53556bool limitBoneWeights;
53557/*!
53558@brief Identifies and joins identical vertex data sets within all imported meshes.
53559*/
53560bool JoinIdenticalVerts;
53561/*!
53562@brief This step adjusts the output face winding order to be clockwise. The default assimp face winding order is counter clockwise.
53563*/
53564bool reverseWindingOrder;
53565/*!
53566@brief Reverse the normal vector direction for all normals.
53567*/
53568bool invertNormals;
53569/*!
53570@brief Removes redundant materials.
53571*/
53572bool removeRedundantMats;
53573/*!
53574@brief How to import timing data as frames, seconds or milliseconds.
53575*/
53576TSShapeConstructorAnimType animTiming;
53577/*!
53578@brief FPS value to use if timing is set in frames and the animations does not have an fps set.
53579*/
53580int animFPS;
53581/// @}
53582
53583
53584/*! @name Sequences
53585@{ */
53586/*!
53587@brief Legacy method of adding sequences to a DTS or DAE shape after loading.
53588
53589
53590@tsexample
53591singleton TSShapeConstructor(MyShapeDae)
53592{
53593   baseShape = "./myShape.dae";
53594   sequence = "../anims/root.dae root";
53595   sequence = "../anims/walk.dae walk";
53596   sequence = "../anims/jump.dsq jump";
53597}
53598@endtsexample
53599*/
53600filename sequence;
53601/// @}
53602
53603
53604/*! @name Ungrouped
53605@{ */
53606/// @}
53607
53608
53609/*! @name Object
53610@{ */
53611/// @}
53612
53613
53614/*! @name Editing
53615@{ */
53616/// @}
53617
53618
53619/*! @name Persistence
53620@{ */
53621/// @}
53622
53623};
53624
53625/*!
53626@brief A fullscreen shader effect.
53627
53628@section PFXTextureIdentifiers
53629
53630@ingroup Rendering
53631
53632*/
53633class PostEffect : public SimGroup {
53634public:
53635/*!
53636@brief Reloads the effect shader and textures.
53637
53638*/
53639void reload();
53640/*!
53641@brief Enables the effect.
53642
53643*/
53644void enable();
53645/*!
53646@brief Disables the effect.
53647
53648*/
53649void disable();
53650/*!
53651@brief Toggles the effect between enabled / disabled.
53652
53653@return True if effect is enabled.*/
53654bool toggle();
53655/*!
53656@brief @return True if the effect is enabled.
53657
53658*/
53659bool isEnabled();
53660/*!
53661@brief This is used to set the texture file and load the texture on a running effect. If the texture file is not different from the current file nothing is changed.  If the texture cannot be found a null texture is assigned.
53662
53663@param index The texture stage index.
53664@param filePath The file name of the texture to set.
53665*/
53666void setTexture( int index, string filePath );
53667/*!
53668@brief Sets the value of a uniform defined in the shader. This will usually be called within the setShaderConsts callback. Array type constants are not supported.
53669
53670@param name Name of the constanst, prefixed with '$'.
53671@param value Value to set, space seperate values with more than one element.
53672@tsexample
53673function MyPfx::setShaderConsts( %this )
53674{
53675   // example float4 uniform
53676   %this.setShaderConst( "$colorMod", "1.0 0.9 1.0 1.0" );
53677   // example float1 uniform
53678   %this.setShaderConst( "$strength", "3.0" );
53679   // example integer uniform
53680   %this.setShaderConst( "$loops", "5" );}
53681@endtsexample*/
53682void setShaderConst( string name, string value );
53683/*!
53684@brief @return Width over height of the backbuffer.
53685
53686*/
53687float getAspectRatio();
53688/*!
53689@brief Dumps this PostEffect shader's disassembly to a temporary text file.
53690
53691@return Full path to the dumped file or an empty string if failed.*/
53692String dumpShaderDisassembly();
53693/*!
53694@brief Adds a macro to the effect's shader or sets an existing one's value. This will usually be called within the onAdd or preProcess callback.
53695
53696@param key lval of the macro.@param value rval of the macro, or may be empty.@tsexample
53697function MyPfx::onAdd( %this )
53698{
53699   %this.setShaderMacro( "NUM_SAMPLES", "10" );
53700   %this.setShaderMacro( "HIGH_QUALITY_MODE" );
53701   
53702   // In the shader looks like... 
53703   // #define NUM_SAMPLES 10
53704   // #define HIGH_QUALITY_MODE
53705}
53706@endtsexample*/
53707void setShaderMacro( string key, string value="" );
53708/*!
53709@brief Remove a shader macro. This will usually be called within the preProcess callback.
53710
53711@param key Macro to remove.*/
53712void removeShaderMacro( string key );
53713/*!
53714@brief Remove all shader macros.
53715
53716*/
53717void clearShaderMacros();
53718
53719/*! @name Callbacks
53720@{ */
53721/*!
53722@brief Called when this object is first created and registered.
53723
53724*/
53725void onAdd();
53726/*!
53727@brief Called when an effect is processed but before textures are bound. This allows the user to change texture related paramaters or macros at runtime.
53728
53729@tsexample
53730function SSAOPostFx::preProcess( %this )
53731{
53732   if ( $SSAOPostFx::quality !$= %this.quality )
53733   {
53734      %this.quality = mClamp( mRound( $SSAOPostFx::quality ), 0, 2 );
53735      
53736      %this.setShaderMacro( "QUALITY", %this.quality );
53737   }
53738   %this.targetScale = $SSAOPostFx::targetScale;
53739}
53740@endtsexample
53741@see setShaderConst
53742@see setShaderMacro*/
53743void preProcess();
53744/*!
53745@brief Called immediate before processing this effect. This is the user's chance to set the value of shader uniforms (constants).
53746
53747@see setShaderConst*/
53748void setShaderConsts();
53749/*!
53750@brief Called when this effect becomes enabled. If the user returns false from this callback the effect will not be enabled.
53751
53752@return True to allow this effect to be enabled.*/
53753bool onEnabled();
53754/*!
53755@brief Called when this effect becomes disabled.
53756
53757*/
53758void onDisabled();
53759/// @}
53760
53761/*!
53762@brief Name of a GFXShaderData for this effect.
53763*/
53764string shader;
53765/*!
53766@brief Name of a GFXStateBlockData for this effect.
53767*/
53768GFXStateBlockData stateBlock;
53769/*!
53770@brief String identifier of this effect's target texture.
53771
53772@see PFXTextureIdentifiers
53773*/
53774string Target;
53775/*!
53776@brief Optional string identifier for this effect's target depth/stencil texture.
53777
53778@see PFXTextureIdentifiers
53779*/
53780string targetDepthStencil;
53781/*!
53782@brief If targetSize is zero this is used to set a relative size from the current target.
53783*/
53784Point2F targetScale;
53785/*!
53786@brief If non-zero this is used as the absolute target size.
53787*/
53788Point2I targetSize;
53789/*!
53790@brief Format of the target texture, not applicable if writing to the backbuffer.
53791*/
53792GFXFormat targetFormat;
53793/*!
53794@brief Color to which the target texture is cleared before rendering.
53795*/
53796LinearColorF targetClearColor;
53797/*!
53798@brief Describes when the target texture should be cleared.
53799*/
53800PFXTargetClear targetClear;
53801/*!
53802@brief Specifies how the viewport should be set up for a target texture.
53803*/
53804PFXTargetViewport targetViewport;
53805/*!
53806@brief Input textures to this effect ( samplers ).
53807
53808@see PFXTextureIdentifiers
53809*/
53810filename texture[ 8 ];
53811/*!
53812@brief Set input texture to be sRGB
53813*/
53814bool textureSRGB[ 8 ];
53815/*!
53816@brief When to process this effect during the frame.
53817*/
53818PFXRenderTime renderTime;
53819/*!
53820@brief Name of a renderBin, used if renderTime is PFXBeforeBin or PFXAfterBin.
53821*/
53822string renderBin;
53823/*!
53824@brief PostEffects are processed in DESCENDING order of renderPriority if more than one has the same renderBin/Time.
53825*/
53826float renderPriority;
53827/*!
53828@brief Is this effect processed during reflection render passes.
53829*/
53830bool allowReflectPass;
53831/*!
53832@brief Is the effect on.
53833*/
53834bool Enabled;
53835/*!
53836@brief Allows you to turn on a PostEffect for only a single frame.
53837*/
53838bool onThisFrame;
53839/*!
53840@brief Allows you to turn on a PostEffect for only a single frame.
53841*/
53842bool oneFrameOnly;
53843/*!
53844@brief Skip processing of this PostEffect and its children even if its parent is enabled. Parent and sibling PostEffects in the chain are still processed.
53845*/
53846bool skip;
53847
53848/*! @name Ungrouped
53849@{ */
53850/// @}
53851
53852
53853/*! @name Object
53854@{ */
53855/// @}
53856
53857
53858/*! @name Editing
53859@{ */
53860/// @}
53861
53862
53863/*! @name Persistence
53864@{ */
53865/// @}
53866
53867};
53868
53869class PfxVis {
53870public:
53871/*!
53872@brief Callback when a visualization window is closed.
53873
53874@param ctrl Name of the GUI control being closed
53875@tsexample
53876PfxVis::onWindowClosed( VisWindow )
53877@endtsexample
53878
53879*/
53880
53881void onWindowClosed(GuiWindowCtrl *ctrl);
53882/*!
53883@brief Show all visualization windows.
53884
53885@tsexample
53886PfxVis::show();@endtsexample
53887
53888*/
53889
53890void show();
53891/*!
53892@brief Hide all visualization windows (they are not destroyed).
53893
53894@tsexample
53895PfxVis::hide();@endtsexample
53896
53897*/
53898
53899void hide();
53900/*!
53901@brief Open visualization windows for all input and target textures.
53902
53903@param effect Name of the PostEffect to open
53904@param clear True to close all visualization windows before opening the effect
53905
53906@tsexample
53907// Multiple PostEffects can be visualized at the same time
53908PfxVis::open( PostEffect )
53909@endtsexample
53910
53911*/
53912
53913void open(PostEffect effect, bool clear);
53914/*!
53915@brief Close all visualization windows.
53916
53917@tsexample
53918PfxVis::clear();@endtsexample
53919
53920*/
53921
53922void clear();
53923
53924/*! @name Callbacks
53925@{ */
53926/// @}
53927
53928};
53929
53930/*! UNDOCUMENTED!
53931@ingroup UNDOCUMENTED
53932 */
53933class Scene : public NetObject {
53934public:
53935/*!
53936@brief Get the root Scene object that is loaded.
53937
53938@return The id of the Root Scene. Will be 0 if no root scene is loaded*/
53939int getRootScene();
53940/*!
53941@brief Get the root Scene object that is loaded.
53942
53943@return The id of the Root Scene. Will be 0 if no root scene is loaded*/
53944void addDynamicObject( SceneObject sceneObj=nullAsType<SceneObject*>() );
53945/*!
53946@brief Get the root Scene object that is loaded.
53947
53948@return The id of the Root Scene. Will be 0 if no root scene is loaded*/
53949void removeDynamicObject( SceneObject sceneObj=nullAsType<SceneObject*>() );
53950/*!
53951@brief Get the root Scene object that is loaded.
53952
53953@return The id of the Root Scene. Will be 0 if no root scene is loaded*/
53954String getObjectsByClass( String className="" );
53955/*!
53956@brief Get the root Scene object that is loaded.
53957
53958@return The id of the Root Scene. Will be 0 if no root scene is loaded*/
53959void dumpUtilizedAssets();
53960/*!
53961@brief Get the root Scene object that is loaded.
53962
53963@return The id of the Root Scene. Will be 0 if no root scene is loaded*/
53964string getOriginatingFile();
53965/*!
53966@brief Get the root Scene object that is loaded.
53967
53968@return The id of the Root Scene. Will be 0 if no root scene is loaded*/
53969string getLevelAsset();
53970/*!
53971@brief Save out the object to the given file.
53972
53973@param fileName The name of the file to save to.@param selectedOnly If true, only objects marked as selected will be saved out.
53974@param preAppendString Text which will be preprended directly to the object serialization.
53975@param True on success, false on failure.*/
53976bool save( string fileName="" );
53977
53978/*! @name Callbacks
53979@{ */
53980/// @}
53981
53982/*!
53983@brief Debug tool which locks the frustum culling to the current camera location.
53984
53985@ingroup Rendering
53986*/
53987static bool lockCull;
53988/*!
53989@brief Used to disable the somewhat expensive terrain occlusion testing.
53990
53991@ingroup Rendering
53992*/
53993static bool disableTerrainOcclusion;
53994/*!
53995@brief If true, zone culling will be disabled and the scene contents will only be culled against the root frustum.
53996
53997
53998@ingroup Rendering
53999*/
54000static bool disableZoneCulling;
54001/*!
54002@brief If true, the bounding boxes of objects will be displayed.
54003
54004
54005@ingroup Rendering*/
54006static bool renderBoundingBoxes;
54007/*!
54008@brief Maximum number of occluders that will be concurrently allowed into the scene culling state of any given zone.
54009
54010
54011@ingroup Rendering*/
54012static int maxOccludersPerZone;
54013/*!
54014@brief TODO
54015
54016
54017@ingroup Rendering*/
54018static float occluderMinWidthPercentage;
54019/*!
54020@brief TODO
54021
54022
54023@ingroup Rendering*/
54024static float occluderMinHeightPercentage;
54025
54026/*! @name Ungrouped
54027@{ */
54028/// @}
54029
54030
54031/*! @name Object
54032@{ */
54033/// @}
54034
54035
54036/*! @name Editing
54037@{ */
54038/// @}
54039
54040
54041/*! @name Persistence
54042@{ */
54043/// @}
54044
54045
54046/*! @name Internal
54047@{ */
54048/*!
54049*/
54050bool isSubScene;
54051/*!
54052*/
54053bool isEditing;
54054/*!
54055*/
54056bool isDirty;
54057/// @}
54058
54059
54060/*! @name Gameplay
54061@{ */
54062/*!
54063@brief The name of the gamemode that this scene utilizes
54064*/
54065string gameModeName;
54066/// @}
54067
54068
54069/*! @name PostFX
54070@{ */
54071/*!
54072@brief Edit Scene's default Post Effects
54073*/
54074bool EditPostEffects;
54075/// @}
54076
54077};
54078
54079/*!
54080@brief Provides the basis for implementing a multiplayer game protocol.
54081
54082NetConnection combines a low-level notify protocol implemented in ConnectionProtocol with a SimGroup, and implements several distinct subsystems:
54083
54084- <b>Event Manager</b>  This is responsible for transmitting NetEvents over the wire.  It deals with ensuring that the various types of NetEvents are delivered appropriately, and with notifying the event of its delivery status.
54085
54086- <b>Move Manager</b>  This is responsible for transferring a Move to the server 32 times a second (on the client) and applying it to the control object (on the server).
54087
54088- <b>Ghost Manager</b>  This is responsible for doing scoping calculations (on the server side) and transmitting most-recent ghost information to the client.
54089
54090- <b>File Transfer</b>  It is often the case that clients will lack important files when connecting to a server which is running a mod or new map. This subsystem allows the server to transfer such files to the client.
54091
54092- <b>Networked String Table</b>  String data can easily soak up network bandwidth, so for efficiency, we implement a networked string table. We can then notify the connection of strings we will reference often, such as player names, and transmit only a tag, instead of the whole string.
54093
54094- <b>Demo Recording</b>  A demo in Torque is a log of the network traffic between client and server; when a NetConnection records a demo, it simply logs this data to a file. When it plays a demo back, it replays the logged data.
54095
54096- <b>Connection Database</b>  This is used to keep track of all the NetConnections; it can be iterated over (for instance, to send an event to all active connections), or queried by address.
54097
54098The NetConnection is a SimGroup. On the client side, it contains all the objects which have been ghosted to that client. On the server side, it is empty; it can be used (typically in script) to hold objects related to the connection. For instance, you might place an observation camera in the NetConnnection. In both cases, when the connection is destroyed, so are the contained objects.
54099
54100The NetConnection also has the concept of local connections.  These are used when the client and server reside in the same process.  A local connection is typically required to use the standard Torque world building tools.  A local connection is also required when building a single player game.
54101
54102@see @ref Networking, @ref ghosting_scoping, @ref netconnection_simgroup, @ref local_connections, GameConnection, AIConnection, and AIClient.
54103
54104@ingroup Networking
54105
54106*/
54107class NetConnection : public SimGroup {
54108public:
54109/*!
54110@brief Sent by the server during phase 2 of the mission download to update motion spline paths.
54111
54112The server transmits all spline motion paths that are within the mission (Path) separate from other objects.  This is due to the potentially large number of nodes within each path, which may saturate a packet sent to the client.  By managing this step separately, Torque has finer control over how packets are organised vs. doing it during the ghosting stage.
54113
54114Internally a PathManager is used to track all paths defined within a mission on the server, and each one is transmitted using a PathManagerEvent.  The client side collects these events and builds the given paths within its own PathManager.  This is typically done during the standard mission start phase 2 when following Torque's example mission startup sequence.
54115
54116When a mission is ended, all paths need to be cleared from their respective path managers.@tsexample
54117function serverCmdMissionStartPhase2Ack(%client, %seq, %playerDB)
54118{
54119   // Make sure to ignore calls from a previous mission load
54120   if (%seq != $missionSequence || !$MissionRunning)
54121      return;
54122   if (%client.currentPhase != 1.5)
54123      return;
54124   %client.currentPhase = 2;
54125
54126   // Set the player datablock choice
54127   %client.playerDB = %playerDB;
54128
54129   // Update mission paths (SimPath), this needs to get there before the objects.
54130   %client.transmitPaths();
54131
54132   // Start ghosting objects to the client
54133   %client.activateGhosting();
54134}
54135@endtsexample
54136@see clearPaths()
54137@see Path*/
54138void transmitPaths();
54139/*!
54140@brief On the server, resets the connection to indicate that motion spline paths have not been transmitted.
54141
54142Typically when a mission has ended on the server, all connected clients are informed of this change and their connections are reset back to a starting state.  This method resets a connection on the server to indicate that motion spline paths have not been transmitted.
54143
54144@tsexample
54145   // Inform the clients
54146   for (%clientIndex = 0; %clientIndex < ClientGroup.getCount(); %clientIndex++)
54147   {
54148      // clear ghosts and paths from all clients
54149      %cl = ClientGroup.getObject(%clientIndex);
54150      %cl.endMission();
54151      %cl.resetGhosting();
54152      %cl.clearPaths();
54153   }
54154@endtsexample
54155@see transmitPaths()
54156@see Path*/
54157void clearPaths();
54158/*!
54159@brief Returns the far end network address for the connection.
54160
54161The address will be in one of the following forms:
54162- <b>IP:Broadcast:&lt;port&gt;</b> for broadcast type addresses
54163- <b>IP:&lt;address&gt;:&lt;port&gt;</b> for IP addresses
54164- <b>local</b> when connected locally (server and client running in same process*/
54165string getAddress();
54166/*!
54167@brief Simulate network issues on the connection for testing.
54168
54169@param packetLoss The fraction of packets that will be lost.  Ranges from 0.0 (no loss) to 1.0 (complete loss)
54170@param delay Delays packets being transmitted by simulating a particular ping.  This is an absolute integer, measured in ms.*/
54171void setSimulatedNetParams( float packetLoss, int delay );
54172/*!
54173@brief Returns the average round trip time (in ms) for the connection.
54174
54175The round trip time is recalculated every time a notify packet is received.  Notify packets are used to information the connection that the far end successfully received the sent packet.*/
54176int getPing();
54177/*!
54178@brief Returns the percentage of packets lost per tick.
54179
54180@note This method is not yet hooked up.*/
54181int getPacketLoss();
54182/*!
54183@brief Ensures that all configured packet rates and sizes meet minimum requirements.
54184
54185This method is normally only called when a NetConnection class is first constructed.  It need only be manually called if the global variables that set the packet rate or size have changed.
54186
54187@note If @$pref::Net::PacketRateToServer, @$pref::Net::PacketRateToClient or @$pref::Net::PacketSize have been changed since a NetConnection has been created, this method must be called on all connections for them to follow the new rates or size.*/
54188void checkMaxRate();
54189/*!
54190@brief On the client, convert a ghost ID from this connection to a real SimObject ID.
54191
54192Torque's network ghosting system only exchanges ghost ID's between the server and client.  Use this method on the client to discover an object's local SimObject ID when you only have a ghost ID.
54193@param ghostID The ghost ID of the object as sent by the server.
54194@returns The SimObject ID of the object, or 0 if it could not be resolved.
54195
54196@tsexample
54197%object = ServerConnection.resolveGhostID( %ghostId );
54198@endtsexample
54199
54200@see @ref ghosting_scoping for a description of the ghosting system.*/
54201int resolveGhostID( int ghostID );
54202/*!
54203@brief On the server, convert a ghost ID from this connection to a real SimObject ID.
54204
54205Torque's network ghosting system only exchanges ghost ID's between the server and client.  Use this method on the server to discover an object's local SimObject ID when you only have a ghost ID.
54206@param ghostID The ghost ID of the object as sent by the server.
54207@returns The SimObject ID of the object, or 0 if it could not be resolved.
54208
54209@tsexample
54210%object = %client.resolveObjectFromGhostIndex( %ghostId );
54211@endtsexample
54212
54213@see @ref ghosting_scoping for a description of the ghosting system.*/
54214int resolveObjectFromGhostIndex( int ghostID );
54215/*!
54216@brief On server or client, convert a real id to the ghost id for this connection.
54217
54218Torque's network ghosting system only exchanges ghost ID's between the server and client.  Use this method on the server or client to discover an object's ghost ID based on its real SimObject ID.
54219@param realID The real SimObject ID of the object.
54220@returns The ghost ID of the object for this connection, or -1 if it could not be resolved.
54221
54222@see @ref ghosting_scoping for a description of the ghosting system.*/
54223int getGhostID( int realID );
54224/*!
54225@brief Connects to the remote address.
54226
54227Attempts to connect with another NetConnection on the given address.  Typically once connected, a game's information is passed along from the server to the client, followed by the player entering the game world.  The actual procedure is dependent on the NetConnection subclass that is used.  i.e. GameConnection.
54228@param remoteAddress The address to connect to in the form of IP:&lt;address&gt;:&lt;port&rt; although the <i>IP:</i> portion is optional.  The <i>address</i> portion may be in the form of w.x.y.z or as a host name, in which case a DNS lookup will be performed.  You may also substitue the word <i>broadcast</i> for the address to broadcast the connect request over the local subnet.
54229
54230@see NetConnection::connectLocal() to connect to a server running within the same process as the client.*/
54231void connect( string remoteAddress );
54232/*!
54233@brief Connects with the server that is running within the same process as the client.
54234
54235@returns An error text message upon failure, or an empty string when successful.
54236
54237@see See @ref local_connections for a description of local connections and their use.  See NetConnection::connect() to connect to a server running in another process (on the same machine or not).*/
54238string connectLocal();
54239/*!
54240@brief Provides the number of active ghosts on the connection.
54241
54242@returns The number of active ghosts.
54243@see @ref ghosting_scoping for a description of the ghosting system.*/
54244int getGhostsActive();
54245/*!
54246@brief Returns the ghost-index for an object.
54247
54248
54249@ingroup AFX*/
54250int GetGhostIndex( NetObject obj );
54251/*!
54252@brief Resolves a ghost-index into an object ID.
54253
54254
54255@ingroup AFX*/
54256int ResolveGhost( int ghostIndex );
54257
54258/*! @name Callbacks
54259@{ */
54260/// @}
54261
54262
54263/*! @name Ungrouped
54264@{ */
54265/// @}
54266
54267
54268/*! @name Object
54269@{ */
54270/// @}
54271
54272
54273/*! @name Editing
54274@{ */
54275/// @}
54276
54277
54278/*! @name Persistence
54279@{ */
54280/// @}
54281
54282};
54283
54284/*!
54285@brief The game-specific subclass of NetConnection.
54286
54287The GameConnection introduces the concept of the control object.  The control object is simply the object that the client is associated with that network connection controls.  By default the control object is an instance of the Player class, but can also be an instance of Camera (when editing the mission, for example), or any other ShapeBase derived class as appropriate for the game.
54288
54289Torque uses a model in which the server is the authoritative master of the simulation.  To prevent clients from cheating, the server simulates all player moves and then tells the client where his player is in the world.  This model, while secure, can have problems.  If the network latency is high, this round-trip time can give the player a very noticeable sense of movement lag.  To correct this problem, the game uses a form of prediction - it simulates the movement of the control object on the client and on the server both.  This way the client doesn't need to wait for round-trip verification of his moves.  Only in the case of a force acting on the control object on the server that doesn't exist on the client does the client's position need to be forcefully changed.
54290
54291To support this, all control objects (derivative of ShapeBase) must supply a writePacketData() and readPacketData() function that send enough data to accurately simulate the object on the client.  These functions are only called for the current control object, and only when the server can determine that the client's simulation is somehow out of sync with the server.  This occurs usually if the client is affected by a force not present on the server (like an interpolating object) or if the server object is affected by a server only force (such as the impulse from an explosion).
54292
54293The Move structure is a 32 millisecond snapshot of player input, containing x, y, and z positional and rotational changes as well as trigger state changes. When time passes in the simulation moves are collected (depending on how much time passes), and applied to the current control object on the client. The same moves are then packed over to the server in GameConnection::writePacket(), for processing on the server's version of the control object.
54294
54295@see @ref Networking, NetConnection, ShapeBase
54296
54297@ingroup Networking
54298
54299*/
54300class GameConnection : public NetConnection {
54301public:
54302/*!
54303@brief On the client, set the password that will be passed to the server.
54304
54305On the server, this password is compared with what is stored in $pref::Server::Password.  If $pref::Server::Password is empty then the client's sent password is ignored.  Otherwise, if the passed in client password and the server password do not match, the CHR_PASSWORD error string is sent back to the client and the connection is immediately terminated.
54306
54307This password checking is performed quite early on in the connection request process so as to minimize the impact of multiple failed attempts -- also known as hacking.*/
54308void setJoinPassword( string password );
54309/*!
54310@brief On the client, pass along a variable set of parameters to the server.
54311
54312Once the connection is established with the server, the server calls its onConnect() method with the client's passed in parameters as aruments.
54313
54314@see GameConnection::onConnect()*/
54315void setConnectArgs(const char* args);
54316/*!
54317@brief Sent by the server during phase 1 of the mission download to send the datablocks to the client.
54318
54319SimDataBlocks, also known as just datablocks, need to be transmitted to the client prior to the client entering the game world.  These represent the static data that most objects in the world reference.  This is typically done during the standard mission start phase 1 when following Torque's example mission startup sequence.
54320
54321When the datablocks have all been transmitted, onDataBlocksDone() is called to move the mission start process to the next phase.@param sequence The sequence is common between the server and client and ensures that the client is acting on the most recent mission start process.  If an errant network packet (one that was lost but has now been found) is received by the client with an incorrect sequence, it is just ignored.  This sequence number is updated on the server every time a mission is loaded.
54322
54323@tsexample
54324function serverCmdMissionStartPhase1Ack(%client, %seq)
54325{
54326   // Make sure to ignore calls from a previous mission load
54327   if (%seq != $missionSequence || !$MissionRunning)
54328      return;
54329   if (%client.currentPhase != 0)
54330      return;
54331   %client.currentPhase = 1;
54332
54333   // Start with the CRC
54334   %client.setMissionCRC( $missionCRC );
54335
54336   // Send over the datablocks...
54337   // OnDataBlocksDone will get called when have confirmation
54338   // that they've all been received.
54339   %client.transmitDataBlocks($missionSequence);
54340}
54341@endtsexample
54342
54343@see GameConnection::onDataBlocksDone()*/
54344void transmitDataBlocks( int sequence );
54345/*!
54346@brief Called by the server during phase 2 of the mission download to start sending ghosts to the client.
54347
54348Ghosts represent objects on the server that are in scope for the client.  These need to be synchronized with the client in order for the client to see and interact with them.  This is typically done during the standard mission start phase 2 when following Torque's example mission startup sequence.
54349
54350@tsexample
54351function serverCmdMissionStartPhase2Ack(%client, %seq, %playerDB)
54352{
54353   // Make sure to ignore calls from a previous mission load
54354   if (%seq != $missionSequence || !$MissionRunning)
54355      return;
54356   if (%client.currentPhase != 1.5)
54357      return;
54358   %client.currentPhase = 2;
54359
54360   // Set the player datablock choice
54361   %client.playerDB = %playerDB;
54362
54363   // Update mod paths, this needs to get there before the objects.
54364   %client.transmitPaths();
54365
54366   // Start ghosting objects to the client
54367   %client.activateGhosting();
54368}
54369@endtsexample
54370
54371@see @ref ghosting_scoping for a description of the ghosting system.*/
54372void activateGhosting();
54373/*!
54374@brief On the server, resets the connection to indicate that ghosting has been disabled.
54375
54376Typically when a mission has ended on the server, all connected clients are informed of this change and their connections are reset back to a starting state.  This method resets a connection on the server to indicate that ghosts are no longer being transmitted.  On the client end, all ghost information will be deleted.
54377
54378@tsexample
54379   // Inform the clients
54380   for (%clientIndex = 0; %clientIndex < ClientGroup.getCount(); %clientIndex++)
54381   {
54382      // clear ghosts and paths from all clients
54383      %cl = ClientGroup.getObject(%clientIndex);
54384      %cl.endMission();
54385      %cl.resetGhosting();
54386      %cl.clearPaths();
54387   }
54388@endtsexample
54389
54390@see @ref ghosting_scoping for a description of the ghosting system.*/
54391void resetGhosting();
54392/*!
54393@brief On the server, sets the object that the client will control.
54394
54395By default the control object is an instance of the Player class, but can also be an instance of Camera (when editing the mission, for example), or any other ShapeBase derived class as appropriate for the game.
54396
54397@param ctrlObj The GameBase object on the server to control.*/
54398bool setControlObject( GameBase ctrlObj );
54399/*!
54400@brief Clear any display device.
54401
54402A display device may define a number of properties that are used during rendering.*/
54403void clearDisplayDevice();
54404/*!
54405@brief On the server, returns the object that the client is controlling.By default the control object is an instance of the Player class, but can also be an instance of Camera (when editing the mission, for example), or any other ShapeBase derived class as appropriate for the game.
54406
54407@see GameConnection::setControlObject()*/
54408GameBase getControlObject();
54409/*!
54410@brief Returns true if this connection is AI controlled.
54411
54412@see AIConnection*/
54413bool isAIControlled();
54414/*!
54415@brief Returns true if the object being controlled by the client is making use of a rotation damped camera.
54416
54417@see Camera*/
54418bool isControlObjectRotDampedCamera();
54419/*!
54420@brief Used on the server to play a 2D sound that is not attached to any object.
54421
54422@param profile The SFXProfile that defines the sound to play.
54423
54424@tsexample
54425function ServerPlay2D(%profile)
54426{
54427   // Play the given sound profile on every client.
54428   // The sounds will be transmitted as an event, not attached to any object.
54429   for(%idx = 0; %idx < ClientGroup.getCount(); %idx++)
54430      ClientGroup.getObject(%idx).play2D(%profile);
54431}
54432@endtsexample*/
54433bool play2D( SFXProfile profile );
54434/*!
54435@brief Used on the server to play a 3D sound that is not attached to any object.
54436
54437@param profile The SFXProfile that defines the sound to play.
54438@param location The position and orientation of the 3D sound given in the form of "x y z ax ay az aa".
54439
54440@tsexample
54441function ServerPlay3D(%profile,%transform)
54442{
54443   // Play the given sound profile at the given position on every client
54444   // The sound will be transmitted as an event, not attached to any object.
54445   for(%idx = 0; %idx < ClientGroup.getCount(); %idx++)
54446      ClientGroup.getObject(%idx).play3D(%profile,%transform);
54447}
54448@endtsexample*/
54449bool play3D( SFXProfile profile, TransformF location );
54450/*!
54451@brief Sets the size of the chase camera's matrix queue.
54452
54453@note This sets the queue size across all GameConnections.
54454
54455@note This is not currently hooked up.*/
54456bool chaseCam( int size );
54457/*!
54458@brief Returns the default field of view as used by the control object's camera.*/
54459float getControlCameraDefaultFov();
54460/*!
54461@brief On the server, sets the control object's camera's field of view.
54462
54463@param newFOV New field of view (in degrees) to force the control object's camera to use.  This value is clamped to be within the range of 1 to 179 degrees.
54464
54465@note When transmitted over the network to the client, the resolution is limited to one degree.  Any fraction is dropped.*/
54466void setControlCameraFov( float newFOV );
54467/*!
54468@brief Returns the field of view as used by the control object's camera.*/
54469float getControlCameraFov();
54470/*!
54471@brief On the client, get the control object's damage flash level.
54472
54473@return flash level*/
54474float getDamageFlash();
54475/*!
54476@brief On the client, get the control object's white-out level.
54477
54478@return white-out level*/
54479float getWhiteOut();
54480/*!
54481@brief On the server, sets the client's 3D display to fade to black.
54482
54483@param doFade Set to true to fade to black, and false to fade from black.
54484@param timeMS Time it takes to perform the fade as measured in ms.
54485
54486@note Not currently hooked up, and is not synchronized over the network.*/
54487void setBlackOut( bool doFade, int timeMS );
54488/*!
54489@brief On the server, transmits the mission file's CRC value to the client.
54490
54491Typically, during the standard mission start phase 1, the mission file's CRC value on the server is send to the client.  This allows the client to determine if the mission has changed since the last time it downloaded this mission and act appropriately, such as rebuilt cached lightmaps.
54492
54493@param CRC The mission file's CRC value on the server.
54494
54495@tsexample
54496function serverCmdMissionStartPhase1Ack(%client, %seq)
54497{
54498   // Make sure to ignore calls from a previous mission load
54499   if (%seq != $missionSequence || !$MissionRunning)
54500      return;
54501   if (%client.currentPhase != 0)
54502      return;
54503   %client.currentPhase = 1;
54504
54505   // Start with the CRC
54506   %client.setMissionCRC( $missionCRC );
54507
54508   // Send over the datablocks...
54509   // OnDataBlocksDone will get called when have confirmation
54510   // that they've all been received.
54511   %client.transmitDataBlocks($missionSequence);
54512}
54513@endtsexample*/
54514void setMissionCRC( int CRC );
54515/*!
54516@brief On the server, disconnect a client and pass along an optional reason why.
54517
54518This method performs two operations: it disconnects a client connection from the server, and it deletes the connection object.  The optional reason is sent in the disconnect packet and is often displayed to the user so they know why they've been disconnected.
54519
54520@param reason [optional] The reason why the user has been disconnected from the server.
54521
54522@tsexample
54523function kick(%client)
54524{
54525   messageAll( 'MsgAdminForce', '\c2The Admin has kicked %1.', %client.playerName);
54526
54527   if (!%client.isAIControlled())
54528      BanList::add(%client.guid, %client.getAddress(), $Pref::Server::KickBanTime);
54529   %client.delete("You have been kicked from this server");
54530}
54531@endtsexample*/
54532void delete( string reason="" );
54533/*!
54534@brief On the client, starts recording the network connection's traffic to a demo file.
54535
54536It is often useful to play back a game session.  This could be for producing a demo of the game that will be shown at a later time, or for debugging a game.  By recording the entire network stream it is possible to later play game the game exactly as it unfolded during the actual play session.  This is because all user control and server results pass through the connection.
54537
54538@param fileName The file name to use for the demo recording.
54539
54540@see GameConnection::stopRecording(), GameConnection::playDemo()*/
54541void startRecording( string fileName );
54542/*!
54543@brief On the client, stops the recording of a connection's network traffic to a file.
54544
54545@see GameConnection::startRecording(), GameConnection::playDemo()*/
54546void stopRecording();
54547/*!
54548@brief On the client, play back a previously recorded game session.
54549
54550It is often useful to play back a game session.  This could be for producing a demo of the game that will be shown at a later time, or for debugging a game.  By recording the entire network stream it is possible to later play game the game exactly as it unfolded during the actual play session.  This is because all user control and server results pass through the connection.
54551
54552@returns True if the playback was successful.  False if there was an issue, such as not being able to open the demo file for playback.
54553
54554@see GameConnection::startRecording(), GameConnection::stopRecording()*/
54555bool playDemo( string demoFileName );
54556/*!
54557@brief Returns true if a previously recorded demo file is now playing.
54558
54559@see GameConnection::playDemo()*/
54560bool isDemoPlaying();
54561/*!
54562@brief Returns true if a demo file is now being recorded.
54563
54564@see GameConnection::startRecording(), GameConnection::stopRecording()*/
54565bool isDemoRecording();
54566/*!
54567@brief List all of the classes that this connection knows about, and what their IDs are. Useful for debugging network problems.
54568
54569@note The list is sent to the console.*/
54570void listClassIDs();
54571/*!
54572@brief On the client, this static mehtod will return the connection to the server, if any.
54573
54574@returns The SimObject ID of the server connection, or -1 if none is found.*/
54575static int getServerConnection();
54576/*!
54577@brief On the server, set the connection's camera object used when not viewing through the control object.
54578
54579@see GameConnection::getCameraObject() and GameConnection::clearCameraObject()*/
54580bool setCameraObject( GameBase camera );
54581/*!
54582@brief Returns the connection's camera object used when not viewing through the control object.
54583
54584@see GameConnection::setCameraObject() and GameConnection::clearCameraObject()*/
54585SimObject getCameraObject();
54586/*!
54587@brief Clear the connection's camera object reference.
54588
54589@see GameConnection::setCameraObject() and GameConnection::getCameraObject()*/
54590void clearCameraObject();
54591/*!
54592@brief Returns true if this connection is in first person mode.
54593
54594@note Transition to first person occurs over time via mCameraPos, so this won't immediately return true after a set.*/
54595bool isFirstPerson();
54596/*!
54597@brief On the server, sets this connection into or out of first person mode.
54598
54599@param firstPerson Set to true to put the connection into first person mode.*/
54600void setFirstPerson( bool firstPerson );
54601/*!
54602@brief Set the control scheme that may be used by a connection's control object.
54603
54604@param absoluteRotation Use absolute rotation values from client, likely through ExtendedMove.
54605@param addYawToAbsRot Add relative yaw control to the absolute rotation calculation.  Only useful when absoluteRotation is true.*/
54606void setControlSchemeParameters( bool absoluteRotation, bool addYawToAbsRot, bool addPitchToAbsRot );
54607/*!
54608@brief Get the connection's control scheme absolute rotation property.
54609
54610@return True if the connection's control object should use an absolute rotation control scheme.
54611
54612@see GameConnection::setControlSchemeParameters()*/
54613bool getControlSchemeAbsoluteRotation();
54614/*!
54615@brief Sets the distance that objects around it will be ghosted. If set to 0, it may be defined by the LevelInfo.
54616
54617@dist - is the max distance*/
54618void setVisibleGhostDistance( float dist );
54619/*!
54620@brief Gets the distance that objects around the connection will be ghosted.
54621
54622@return S32 of distance.*/
54623float getVisibleGhostDistance();
54624bool setSelectedObj( SceneObject obj, bool propagate_to_client=false );
54625SimObject getSelectedObj();
54626void clearSelectedObj( bool propagate_to_client=false );
54627void setPreSelectedObjFromRollover();
54628void clearPreSelectedObj();
54629void setSelectedObjFromPreSelected();
54630void saveDatablockCache();
54631void loadDatablockCache();
54632bool loadDatablockCache_Begin();
54633bool loadDatablockCache_Continue();
54634
54635/*! @name Callbacks
54636@{ */
54637/*!
54638@brief Called on the client when the connection to the server times out.*/
54639void onConnectionTimedOut();
54640/*!
54641@brief Called on the client when the connection to the server has been established.*/
54642void onConnectionAccepted();
54643/*!
54644@brief Called when connection attempts have timed out.*/
54645void onConnectRequestTimedOut();
54646/*!
54647@brief Called on the client when the connection to the server has been dropped.
54648
54649@param reason The reason why the connection was dropped.*/
54650void onConnectionDropped( string reason );
54651/*!
54652@brief Called on the client when the connection to the server has been rejected.
54653
54654@param reason The reason why the connection request was rejected.*/
54655void onConnectRequestRejected( string reason );
54656/*!
54657@brief Called on the client when there is an error with the connection to the server.
54658
54659@param errorString The connection error text.*/
54660void onConnectionError( string errorString );
54661/*!
54662@brief Called on the server when the client's connection has been dropped.
54663
54664@param disconnectReason The reason why the connection was dropped.*/
54665void onDrop( string disconnectReason );
54666/*!
54667@brief Called on the client when the first control object has been set by the server and we are now ready to go.
54668
54669A common action to perform when this callback is called is to switch the GUI canvas from the loading screen and over to the 3D game GUI.*/
54670void initialControlSet();
54671/*!
54672@brief Called on the client when the control object has been changed by the server.*/
54673void onControlObjectChange();
54674/*!
54675@brief Called on the client to display the lag icon.
54676
54677When the connection with the server is lagging, this callback is called to allow the game GUI to display some indicator to the player.
54678
54679@param state Set to true if the lag icon should be displayed.*/
54680void setLagIcon( bool state );
54681/*!
54682@brief Called on the server when all datablocks has been sent to the client.
54683
54684During phase 1 of the mission download, all datablocks are sent from the server to the client.  Once all datablocks have been sent, this callback is called and the mission download procedure may move on to the next phase.
54685
54686@param sequence The sequence is common between the server and client and ensures that the client is acting on the most recent mission start process.  If an errant network packet (one that was lost but has now been found) is received by the client with an incorrect sequence, it is just ignored.  This sequence number is updated on the server every time a mission is loaded.
54687
54688@see GameConnection::transmitDataBlocks()*/
54689void onDataBlocksDone( uint sequence );
54690/*!
54691@brief Called on the client when the damage flash or white out states change.
54692
54693When the server changes the damage flash or white out values, this callback is called either is on or both are off.  Typically this is used to enable the flash postFx.
54694
54695@param state Set to true if either the damage flash or white out conditions are active.*/
54696void onFlash( bool state );
54697/// @}
54698
54699
54700/*! @name Ungrouped
54701@{ */
54702/// @}
54703
54704
54705/*! @name Object
54706@{ */
54707/// @}
54708
54709
54710/*! @name Editing
54711@{ */
54712/// @}
54713
54714
54715/*! @name Persistence
54716@{ */
54717/// @}
54718
54719};
54720
54721/*!
54722@brief Special client connection driven by an AI, rather than a human.
54723
54724Unlike other net connections, AIConnection is intended to run unmanned. Rather than gathering input from a human using a device, move events, triggers, and look events are driven through functions like AIConnection::setMove.
54725
54726In addition to having its own set of functions for managing client move events, a member variable inherited by GameConnection is toggle: mAIControlled. This is useful for a server to determine if a connection is AI driven via the function GameConnection::isAIControlled
54727
54728AIConnection is an alternative to manually creating an AI driven game object. When you want the server to manage AI, you will create a specific one from script using a class like AIPlayer. If you do not want the server managing the AI and wish to simulate a complete client connection, you will use AIConnection
54729
54730.To get more specific, if you want a strong alternative to AIPlayer (and wish to make use of the AIConnection structure), consider AIClient. AIClient inherits from AIConnection, contains quite a bit of functionality you will find in AIPlayer, and has its own Player object.
54731
54732@tsexample
54733// Create a new AI client connection
54734%botConnection = aiConnect("MasterBlaster" @ %i, -1, 0.5, false, "SDF", 1.0);
54735
54736// In another area of the code, you can locate this and any other AIConnections
54737// using the isAIControlled function
54738for(%i = 0; %i < ClientGroup.getCount(); %i++)
54739{
54740   %client = ClientGroup.getObject(%i);
54741   if(%client.isAIControlled())
54742   {
54743      // React to this AI controlled client
54744   }
54745}
54746@endtsexample
54747
54748@note This is a legacy class, which you are discouraged from using as it will most likely be deprecated in a future version. For now it has been left in for backwards compatibility with TGE and the old RTS Kit. Use GameConnection and AIPlayer instead.
54749
54750@see GameConnection, NetConnection, AIClient
54751
54752@ingroup AI
54753@ingroup Networking
54754
54755*/
54756class AIConnection : public GameConnection {
54757public:
54758/*!
54759@brief Set a field on the current move.
54760
54761
54762@param   field One of {'x','y','z','yaw','pitch','roll'}
54763@param   value Value to set field to.*/
54764void setMove( string field, float value );
54765/*!
54766@brief Get the given field of a move.
54767
54768
54769@param field One of {'x','y','z','yaw','pitch','roll'}
54770@returns The requested field on the current move.*/
54771float getMove( string field );
54772/*!
54773@brief Enable/disable freelook on the current move.
54774
54775*/
54776void setFreeLook( bool isFreeLook );
54777/*!
54778@brief getFreeLook()Is freelook on for the current move?
54779
54780*/
54781bool getFreeLook();
54782/*!
54783@brief Set a trigger.
54784
54785*/
54786void setTrigger( int idx, bool set );
54787/*!
54788@brief Is the given trigger set?
54789
54790*/
54791bool getTrigger( int idx );
54792string getAddress();
54793
54794/*! @name Callbacks
54795@{ */
54796/// @}
54797
54798
54799/*! @name Ungrouped
54800@{ */
54801/// @}
54802
54803
54804/*! @name Object
54805@{ */
54806/// @}
54807
54808
54809/*! @name Editing
54810@{ */
54811/// @}
54812
54813
54814/*! @name Persistence
54815@{ */
54816/// @}
54817
54818};
54819
54820/*!
54821@brief Simulated client driven by AI commands.
54822
54823This object is derived from the AIConnection class. It introduces its own Player object to solidify the purpose of this class: Simulated client connecting as a player
54824
54825To get more specific, if you want a strong alternative to AIPlayer (and wish to make use of the AIConnection structure), consider AIClient. AIClient inherits from AIConnection, contains quite a bit of functionality you will find in AIPlayer, and has its own Player object.
54826
54827@note This is a legacy class, which you are discouraged from using as it will most likely be deprecated in a future version. For now it has been left in for backwards compatibility with TGE and the old RTS Kit. Use AIPlayer instead.
54828
54829@see AIPlayer, AIConnection
54830
54831@ingroup AI
54832@ingroup Networking
54833
54834*/
54835class AIClient : public AIConnection {
54836public:
54837/*!
54838@brief ai.setMoveSpeed( float );
54839
54840*/
54841void setMoveSpeed( float speed );
54842/*!
54843@brief ai.stop();
54844
54845*/
54846void stop();
54847/*!
54848@brief ai.setAimLocation( x y z );
54849
54850*/
54851void setAimLocation( Point3F v );
54852/*!
54853@brief ai.setMoveDestination( x y z );
54854
54855*/
54856void setMoveDestination( Point3F v );
54857/*!
54858@brief ai.getAimLocation();
54859
54860*/
54861Point3F getAimLocation();
54862/*!
54863@brief ai.getMoveDestination();
54864
54865*/
54866Point3F getMoveDestination();
54867/*!
54868@brief ai.setTargetObject( obj );
54869
54870*/
54871void setTargetObject( string objName );
54872/*!
54873@brief ai.getTargetObject();
54874
54875*/
54876int getTargetObject();
54877/*!
54878@brief ai.missionCycleCleanup();
54879
54880*/
54881void missionCycleCleanup();
54882/*!
54883@brief ai.move();
54884
54885*/
54886void move();
54887/*!
54888@brief ai.getLocation();
54889
54890*/
54891Point3F getLocation();
54892/*!
54893@brief ai.moveForward();
54894
54895*/
54896void moveForward();
54897
54898/*! @name Callbacks
54899@{ */
54900void onConnect( string idString );
54901/// @}
54902
54903
54904/*! @name Ungrouped
54905@{ */
54906/// @}
54907
54908
54909/*! @name Object
54910@{ */
54911/// @}
54912
54913
54914/*! @name Editing
54915@{ */
54916/// @}
54917
54918
54919/*! @name Persistence
54920@{ */
54921/// @}
54922
54923};
54924
54925/*!
54926@ingroup gameObjects
54927
54928*/
54929class Player : public ShapeBase {
54930public:
54931/*!
54932@brief Get the name of the player's current pose.
54933
54934The pose is one of the following:
54935
54936<ul><li>Stand - Standard movement pose.</li><li>Sprint - Sprinting pose.</li><li>Crouch - Crouch pose.</li><li>Prone - Prone pose.</li><li>Swim - Swimming pose.</li></ul>
54937@return The current pose; one of: "Stand", "Sprint", "Crouch", "Prone", "Swim"*/
54938string getPose();
54939/*!
54940@brief Allow all poses a chance to occur.
54941
54942This method resets any poses that have manually been blocked from occuring.  This includes the regular pose states such as sprinting, crouch, being prone and swimming.  It also includes being able to jump and jet jump.  While this is allowing these poses to occur it doesn't mean that they all can due to other conditions.  We're just not manually blocking them from being allowed.
54943@see allowJumping()
54944@see allowJetJumping()
54945@see allowSprinting()
54946@see allowCrouching()
54947@see allowProne()
54948@see allowSwimming()*/
54949void allowAllPoses();
54950/*!
54951@brief Set if the Player is allowed to jump.
54952
54953The default is to allow jumping unless there are other environmental concerns that prevent it.  This method is mainly used to explicitly disallow jumping at any time.
54954@param state Set to true to allow jumping, false to disable it.
54955@see allowAllPoses()*/
54956void allowJumping( bool state );
54957/*!
54958@brief Set if the Player is allowed to jet jump.
54959
54960The default is to allow jet jumping unless there are other environmental concerns that prevent it.  This method is mainly used to explicitly disallow jet jumping at any time.
54961@param state Set to true to allow jet jumping, false to disable it.
54962@see allowAllPoses()*/
54963void allowJetJumping( bool state );
54964/*!
54965@brief Set if the Player is allowed to sprint.
54966
54967The default is to allow sprinting unless there are other environmental concerns that prevent it.  This method is mainly used to explicitly disallow sprinting at any time.
54968@param state Set to true to allow sprinting, false to disable it.
54969@see allowAllPoses()*/
54970void allowSprinting( bool state );
54971/*!
54972@brief Set if the Player is allowed to crouch.
54973
54974The default is to allow crouching unless there are other environmental concerns that prevent it.  This method is mainly used to explicitly disallow crouching at any time.
54975@param state Set to true to allow crouching, false to disable it.
54976@see allowAllPoses()*/
54977void allowCrouching( bool state );
54978/*!
54979@brief Set if the Player is allowed to go prone.
54980
54981The default is to allow being prone unless there are other environmental concerns that prevent it.  This method is mainly used to explicitly disallow going prone at any time.
54982@param state Set to true to allow being prone, false to disable it.
54983@see allowAllPoses()*/
54984void allowProne( bool state );
54985/*!
54986@brief Set if the Player is allowed to swim.
54987
54988The default is to allow swimming unless there are other environmental concerns that prevent it.  This method is mainly used to explicitly disallow swimming at any time.
54989@param state Set to true to allow swimming, false to disable it.
54990@see allowAllPoses()*/
54991void allowSwimming( bool state );
54992/*!
54993@brief Get the name of the player's current state.
54994
54995The state is one of the following:
54996
54997<ul><li>Dead - The Player is dead.</li><li>Mounted - The Player is mounted to an object such as a vehicle.</li><li>Move - The Player is free to move.  The usual state.</li><li>Recover - The Player is recovering from a fall.  See PlayerData::recoverDelay.</li></ul>
54998@return The current state; one of: "Dead", "Mounted", "Move", "Recover"*/
54999string getState();
55000/*!
55001@brief Get the named damage location and modifier for a given world position.
55002
55003the Player object can simulate different hit locations based on a pre-defined set of PlayerData defined percentages.  These hit percentages divide up the Player's bounding box into different regions.  The diagram below demonstrates how the various PlayerData properties split up the bounding volume:
55004
55005<img src="images/player_damageloc.png">
55006
55007While you may pass in any world position and getDamageLocation() will provide a best-fit location, you should be aware that this can produce some interesting results.  For example, any position that is above PlayerData::boxHeadPercentage will be considered a 'head' hit, even if the world position is high in the sky.  Therefore it may be wise to keep the passed in point to somewhere on the surface of, or within, the Player's bounding volume.
55008
55009@note This method will not return an accurate location when the player is prone or swimming.
55010
55011@param pos A world position for which to retrieve a body region on this player.
55012@return a string containing two words (space separated strings), where the first is a location and the second is a modifier.
55013
55014Posible locations:<ul><li>head</li><li>torso</li><li>legs</li></ul>
55015Head modifiers:<ul><li>left_back</li><li>middle_back</li><li>right_back</li><li>left_middle</li><li>middle_middle</li><li>right_middle</li><li>left_front</li><li>middle_front</li><li>right_front</li></ul>
55016Legs/Torso modifiers:<ul><li>front_left</li><li>front_right</li><li>back_left</li><li>back_right</li></ul>
55017@see PlayerData::boxHeadPercentage
55018@see PlayerData::boxHeadFrontPercentage
55019@see PlayerData::boxHeadBackPercentage
55020@see PlayerData::boxHeadLeftPercentage
55021@see PlayerData::boxHeadRightPercentage
55022@see PlayerData::boxTorsoPercentage*/
55023string getDamageLocation( Point3F pos );
55024/*!
55025@brief Set the sequence that controls the player's arms (dynamically adjusted to match look direction).
55026
55027@param name Name of the sequence to play on the player's arms.
55028@return true if successful, false if failed.
55029@note By default the 'look' sequence is used, if available.*/
55030bool setArmThread( string name );
55031/*!
55032@brief Set the main action sequence to play for this player.
55033
55034@param name Name of the action sequence to set
55035@param hold Set to false to get a callback on the datablock when the sequence ends (PlayerData::animationDone()).  When set to true no callback is made.
55036@param fsp True if first person and none of the spine nodes in the shape should animate.  False will allow the shape's spine nodes to animate.
55037@return True if succesful, false if failed
55038@note The spine nodes for the Player's shape are named as follows:
55039
55040<ul><li>Bip01 Pelvis</li><li>Bip01 Spine</li><li>Bip01 Spine1</li><li>Bip01 Spine2</li><li>Bip01 Neck</li><li>Bip01 Head</li></ul>
55041
55042You cannot use setActionThread() to have the Player play one of the motion determined action animation sequences.  These sequences are chosen based on how the Player moves and the Player's current pose.  The names of these sequences are:
55043
55044<ul><li>root</li><li>run</li><li>side</li><li>side_right</li><li>crouch_root</li><li>crouch_forward</li><li>crouch_backward</li><li>crouch_side</li><li>crouch_right</li><li>prone_root</li><li>prone_forward</li><li>prone_backward</li><li>swim_root</li><li>swim_forward</li><li>swim_backward</li><li>swim_left</li><li>swim_right</li><li>fall</li><li>jump</li><li>standjump</li><li>land</li><li>jet</li></ul>
55045
55046If the player moves in any direction then the animation sequence set using this method will be cancelled and the chosen mation-based sequence will take over.  This makes great for times when the Player cannot move, such as when mounted, or when it doesn't matter if the action sequence changes, such as waving and saluting.
55047@tsexample
55048// Place the player in a sitting position after being mounted
55049%player.setActionThread( "sitting", true, true );
55050@endtsexample*/
55051bool setActionThread( string name, bool hold=false, bool fsp=true );
55052/*!
55053@brief Set the object to be controlled by this player
55054
55055It is possible to have the moves sent to the Player object from the GameConnection to be passed along to another object.  This happens, for example when a player is mounted to a vehicle.  The move commands pass through the Player and on to the vehicle (while the player remains stationary within the vehicle).  With setControlObject() you can have the Player pass along its moves to any object.  One possible use is for a player to move a remote controlled vehicle.  In this case the player does not mount the vehicle directly, but still wants to be able to control it.
55056@param obj Object to control with this player
55057@return True if the object is valid, false if not
55058@see getControlObject()
55059@see clearControlObject()
55060@see GameConnection::setControlObject()*/
55061bool setControlObject( ShapeBase obj );
55062/*!
55063@brief Get the current object we are controlling.
55064
55065@return ID of the ShapeBase object we control, or 0 if not controlling an object.
55066@see setControlObject()
55067@see clearControlObject()*/
55068int getControlObject();
55069/*!
55070@brief Clears the player's current control object.
55071
55072Returns control to the player. This internally calls Player::setControlObject(0).
55073@tsexample
55074%player.clearControlObject();
55075echo(%player.getControlObject()); //<-- Returns 0, player assumes control
55076%player.setControlObject(%vehicle);
55077echo(%player.getControlObject()); //<-- Returns %vehicle, player controls the vehicle now.
55078@endtsexample
55079@note If the player does not have a control object, the player will receive all moves from its GameConnection.  If you're looking to remove control from the player itself (i.e. stop sending moves to the player) use GameConnection::setControlObject() to transfer control to another object, such as a camera.
55080@see setControlObject()
55081@see getControlObject()
55082@see GameConnection::setControlObject()*/
55083void clearControlObject();
55084/*!
55085@brief Check if it is safe to dismount at this position.
55086
55087Internally this method casts a ray from oldPos to pos to determine if it hits the terrain, an interior object, a water object, another player, a static shape, a vehicle (exluding the one currently mounted), or physical zone.  If this ray is in the clear, then the player's bounding box is also checked for a collision at the pos position.  If this displaced bounding box is also in the clear, then checkDismountPoint() returns true.
55088@param oldPos The player's current position
55089@param pos The dismount position to check
55090@return True if the dismount position is clear, false if not
55091@note The player must be already mounted for this method to not assert.*/
55092bool checkDismountPoint( Point3F oldPos, Point3F pos );
55093/*!
55094@brief Get the number of death animations available to this player.
55095
55096Death animations are assumed to be named death1-N using consecutive indices.*/
55097int getNumDeathAnimations();
55098bool isAnimationLocked();
55099void setLookAnimationOverride( bool flag );
55100void copyHeadRotation( Player other_player );
55101/*!
55102@brief setMovementSpeedBias(F32 bias)
55103
55104*/
55105void setMovementSpeedBias( float bias );
55106
55107/*! @name Callbacks
55108@{ */
55109/// @}
55110
55111/*!
55112@brief Determines if the player is rendered or not.
55113
55114Used on the client side to disable the rendering of all Player objects.  This is mainly for the tools or debugging.
55115@ingroup GameObjects
55116*/
55117static bool renderMyPlayer;
55118/*!
55119@brief Determines if mounted shapes are rendered or not.
55120
55121Used on the client side to disable the rendering of all Player mounted objects.  This is mainly used for the tools or debugging.
55122@ingroup GameObjects
55123*/
55124static bool renderMyItems;
55125/*!
55126@brief Determines if the player's collision mesh should be rendered.
55127
55128This is mainly used for the tools and debugging.
55129@ingroup GameObjects
55130*/
55131static bool renderCollision;
55132/*!
55133@brief Fraction of tick at which instant warp occures on the client.
55134
55135@ingroup GameObjects
55136*/
55137static float minWarpTicks;
55138/*!
55139@brief When a warp needs to occur due to the client being too far off from the server, this is the maximum number of ticks we'll allow the client to warp to catch up.
55140
55141@ingroup GameObjects
55142*/
55143static int maxWarpTicks;
55144/*!
55145@brief Maximum number of ticks to predict on the client from the last known move obtained from the server.
55146
55147@ingroup GameObjects
55148*/
55149static int maxPredictionTicks;
55150/*!
55151@brief The maximum velocity allowed due to a single impulse.
55152
55153@ingroup GameObjects
55154*/
55155static float maxImpulseVelocity;
55156/*!
55157@brief The move trigger index used for player jumping.
55158
55159@ingroup GameObjects
55160*/
55161static int jumpTrigger;
55162/*!
55163@brief The move trigger index used for player crouching.
55164
55165@ingroup GameObjects
55166*/
55167static int crouchTrigger;
55168/*!
55169@brief The move trigger index used for player prone pose.
55170
55171@ingroup GameObjects
55172*/
55173static int proneTrigger;
55174/*!
55175@brief The move trigger index used for player sprinting.
55176
55177@ingroup GameObjects
55178*/
55179static int sprintTrigger;
55180/*!
55181@brief The move trigger index used to trigger mounted image 0.
55182
55183@ingroup GameObjects
55184*/
55185static int imageTrigger0;
55186/*!
55187@brief The move trigger index used to trigger mounted image 1 or alternate fire on mounted image 0.
55188
55189@ingroup GameObjects
55190*/
55191static int imageTrigger1;
55192/*!
55193@brief The move trigger index used for player jump jetting.
55194
55195@ingroup GameObjects
55196*/
55197static int jumpJetTrigger;
55198/*!
55199@brief The move trigger index used to dismount player.
55200
55201@ingroup GameObjects
55202*/
55203static int vehicleDismountTrigger;
55204/*!
55205@brief The ExtendedMove position/rotation index used for head movements.
55206
55207@ingroup GameObjects
55208*/
55209static int extendedMoveHeadPosRotIndex;
55210/*!
55211@brief Disables rendering of all instances of this type.
55212
55213
55214@ingroup UNDOCUMENTED
55215*/
55216static bool isRenderable;
55217/*!
55218@brief Disables selection of all instances of this type.
55219
55220
55221@ingroup UNDOCUMENTED
55222*/
55223static bool isSelectable;
55224
55225/*! @name Game
55226@{ */
55227/// @}
55228
55229
55230/*! @name GameObject
55231@{ */
55232/// @}
55233
55234
55235/*! @name Transform
55236@{ */
55237/// @}
55238
55239
55240/*! @name Editing
55241@{ */
55242/// @}
55243
55244
55245/*! @name Mounting
55246@{ */
55247/// @}
55248
55249
55250/*! @name Ungrouped
55251@{ */
55252/// @}
55253
55254
55255/*! @name Object
55256@{ */
55257/// @}
55258
55259
55260/*! @name Editing
55261@{ */
55262/// @}
55263
55264
55265/*! @name Persistence
55266@{ */
55267/// @}
55268
55269};
55270
55271/*!
55272@brief A Player object not controlled by conventional input, but by an AI engine.
55273
55274The AIPlayer provides a Player object that may be controlled from script.  You control where the player moves and how fast.  You may also set where the AIPlayer is aiming at -- either a location or another game object.
55275
55276The AIPlayer class does not have a datablock of its own.  It makes use of the PlayerData datablock to define how it looks, etc.  As the AIPlayer is an extension of the Player class it can mount objects and fire weapons, or mount vehicles and drive them.
55277
55278While the PlayerData datablock is used, there are a number of additional callbacks that are implemented by AIPlayer on the datablock.  These are listed here:
55279
55280void onReachDestination(AIPlayer obj) 
55281Called when the player has reached its set destination using the setMoveDestination() method.  The actual point at which this callback is called is when the AIPlayer is within the mMoveTolerance of the defined destination.
55282
55283void onMoveStuck(AIPlayer obj) 
55284While in motion, if an AIPlayer has moved less than moveStuckTolerance within a single tick, this callback is called.  From here you could choose an alternate destination to get the AIPlayer moving again.
55285
55286void onTargetEnterLOS(AIPlayer obj) 
55287When an object is being aimed at (following a call to setAimObject()) and the targeted object enters the AIPlayer's line of sight, this callback is called.  The LOS test is a ray from the AIPlayer's eye position to the center of the target's bounding box.  The LOS ray test only checks against interiors, statis shapes, and terrain.
55288
55289void onTargetExitLOS(AIPlayer obj) 
55290When an object is being aimed at (following a call to setAimObject()) and the targeted object leaves the AIPlayer's line of sight, this callback is called.  The LOS test is a ray from the AIPlayer's eye position to the center of the target's bounding box.  The LOS ray test only checks against interiors, statis shapes, and terrain.
55291
55292@tsexample
55293// Create the demo player object
55294%player = new AiPlayer()
55295{
55296  dataBlock = DemoPlayer;
55297  path = "";
55298};
55299@endtsexample
55300
55301@see Player for a list of all inherited functions, variables, and base description
55302@ingroup AI
55303@ingroup gameObjects
55304
55305*/
55306class AIPlayer : public Player {
55307public:
55308/*!
55309@brief Sets the AIPlayer's target object.  May optionally set an offset from target location
55310
55311@param targetObject The object to target
55312@param offset Optional three-element offset vector which will be added to the position of the aim object.
55313
55314@tsexample
55315// Without an offset
55316%ai.setAimObject(%target);
55317
55318// With an offset
55319// Cause our AI object to aim at the target
55320// offset (0, 0, 1) so you don't aim at the target's feet
55321%ai.setAimObject(%target, "0 0 1");
55322@endtsexample
55323
55324@see getAimLocation()
55325@see getAimObject()
55326@see clearAim()
55327*/
55328
55329void setAimObject(GameBase targetObject, Point3F offset);
55330/*!
55331@brief Tells the AI to find a path to the location provided
55332
55333@param goal Coordinates in world space representing location to move to.
55334@return True if a path was found.
55335
55336@see getPathDestination()
55337@see setMoveDestination()*/
55338bool setPathDestination( Point3F goal );
55339/*!
55340@brief Get the AIPlayer's current pathfinding destination.
55341
55342@return Returns a point containing the "x y z" position of the AIPlayer's current path destination. If no path destination has yet been set, this returns "0 0 0".@see setPathDestination()*/
55343Point3F getPathDestination();
55344/*!
55345@brief Tell the AIPlayer to follow a path.
55346
55347@param obj ID of a NavPath object for the character to follow.*/
55348void followNavPath( SimObjectId obj );
55349/*!
55350@brief Tell the AIPlayer to follow another object.
55351
55352@param obj ID of the object to follow.
55353@param radius Maximum distance we let the target escape to.*/
55354void followObject( SimObjectId obj, float radius );
55355/*!
55356@brief Tells the AI to re-plan its path. Does nothing if the character has no path, or if it is following a mission path.*/
55357void repath();
55358/*!
55359@brief Tells the AI to find cover nearby.
55360
55361@param from   Location to find cover from (i.e., enemy position).
55362@param radius Distance to search for cover.
55363@return Cover point ID if cover was found, -1 otherwise.*/
55364int findCover( Point3F from, float radius );
55365/*!
55366@brief Get the NavMesh object this AIPlayer is currently using.
55367
55368@return The ID of the NavPath object this character is using for pathfinding. This is determined by the character's location, navigation type and other factors. Returns -1 if no NavMesh is found.*/
55369int findNavMesh();
55370/*!
55371@brief Return the NavMesh this AIPlayer is using to navigate.*/
55372int getNavMesh();
55373/*!
55374@brief Set the size of NavMesh this character uses. One of "Small", "Regular" or "Large".*/
55375void setNavSize( string size );
55376/*!
55377@brief Return the size of NavMesh this character uses for pathfinding.*/
55378string getNavSize();
55379/*!
55380@brief Tells the AIPlayer to stop moving.*/
55381void stop();
55382/*!
55383@brief Use this to stop aiming at an object or a point.
55384
55385@see setAimLocation()
55386@see setAimObject()*/
55387void clearAim();
55388/*!
55389@brief Sets the move speed for an AI object.
55390
55391@param speed A speed multiplier between 0.0 and 1.0.  This is multiplied by the AIPlayer's base movement rates (as defined in its PlayerData datablock)
55392
55393@see getMoveDestination()*/
55394void setMoveSpeed( float speed );
55395/*!
55396@brief Gets the move speed of an AI object.
55397
55398@return A speed multiplier between 0.0 and 1.0.
55399
55400@see setMoveSpeed()*/
55401float getMoveSpeed();
55402/*!
55403@brief Tells the AI to move to the location provided
55404
55405@param goal Coordinates in world space representing location to move to.
55406@param slowDown A boolean value. If set to true, the bot will slow down when it gets within 5-meters of its move destination. If false, the bot will stop abruptly when it reaches the move destination. By default, this is true.
55407
55408@note Upon reaching a move destination, the bot will clear its move destination and calls to getMoveDestination will return "0 0 0".@see getMoveDestination()*/
55409void setMoveDestination( Point3F goal, bool slowDown=true );
55410/*!
55411@brief Get the AIPlayer's current destination.
55412
55413@return Returns a point containing the "x y z" position of the AIPlayer's current move destination. If no move destination has yet been set, this returns "0 0 0".@see setMoveDestination()*/
55414Point3F getMoveDestination();
55415/*!
55416@brief Tells the AIPlayer to aim at the location provided.
55417
55418@param target An "x y z" position in the game world to target.
55419
55420@see getAimLocation()*/
55421void setAimLocation( Point3F target );
55422/*!
55423@brief Returns the point the AIPlayer is aiming at.
55424
55425This will reflect the position set by setAimLocation(), or the position of the object that the bot is now aiming at.  If the bot is not aiming at anything, this value will change to whatever point the bot's current line-of-sight intercepts.@return World space coordinates of the object AI is aiming at. Formatted as "X Y Z".
55426
55427@see setAimLocation()
55428@see setAimObject()*/
55429Point3F getAimLocation();
55430/*!
55431@brief Gets the object the AIPlayer is targeting.
55432
55433@return Returns -1 if no object is being aimed at, or the SimObjectID of the object the AIPlayer is aiming at.
55434
55435@see setAimObject()*/
55436int getAimObject();
55437/*!
55438@brief Check whether an object is in line of sight.
55439@obj Object to check. (If blank, it will check the current target).
55440@useMuzzle Use muzzle position. Otherwise use eye position. (defaults to false).
55441@checkEnabled check whether the object can take damage and if so is still alive.(Defaults to false)*/
55442bool checkInLos( ShapeBase obj=nullAsType<ShapeBase*>(), bool useMuzzle=false, bool checkEnabled=false );
55443/*!
55444@brief Check whether an object is within a specified veiw cone.
55445@obj Object to check. (If blank, it will check the current target).
55446@fov view angle in degrees.(Defaults to 45)
55447@checkEnabled check whether the object can take damage and if so is still alive.(Defaults to false)*/
55448bool checkInFoV( ShapeBase obj=nullAsType<ShapeBase*>(), float fov=45.0f, bool checkEnabled=false );
55449/*!
55450@brief Sets a movement trigger on an AI object.
55451
55452@param slot The trigger slot to set.
55453@see getMoveTrigger()
55454@see clearMoveTrigger()
55455@see clearMoveTriggers()*/
55456void setMoveTrigger( uint slot );
55457/*!
55458@brief Clears a movement trigger on an AI object.
55459
55460@param slot The trigger slot to set.
55461@see setMoveTrigger()
55462@see getMoveTrigger()
55463@see clearMoveTriggers()*/
55464void clearMoveTrigger( uint slot );
55465/*!
55466@brief Tests if a movement trigger on an AI object is set.
55467
55468@param slot The trigger slot to check.
55469@return a boolean indicating if the trigger is set/unset.
55470@see setMoveTrigger()
55471@see clearMoveTrigger()
55472@see clearMoveTriggers()*/
55473bool getMoveTrigger( uint slot );
55474/*!
55475@brief Clear ALL movement triggers on an AI object.
55476@see setMoveTrigger()
55477@see getMoveTrigger()
55478@see clearMoveTrigger()*/
55479void clearMoveTriggers();
55480/*!
55481@brief The distance to a given object.
55482@obj Object to check. (If blank, it will check the current target).
55483@checkEnabled check whether the object can take damage and if so is still alive.(Defaults to false)*/
55484float getTargetDistance( ShapeBase obj=nullAsType<ShapeBase*>(), bool checkEnabled=false );
55485/*!
55486@brief Sets the AiPose for an AI object.
55487@param pose StandPose=0, CrouchPose=1, PronePose=2, SprintPose=3.
55488Uses the new AiPose variable from shapebase (as defined in its PlayerData datablock).*/
55489void setAiPose( int pose );
55490/*!
55491@brief Get the object's current AiPose.
55492@return StandPose=0, CrouchPose=1, PronePose=2, SprintPose=3.*/
55493int getAiPose();
55494
55495/*! @name Callbacks
55496@{ */
55497/// @}
55498
55499/*!
55500@brief Disables rendering of all instances of this type.
55501
55502
55503@ingroup UNDOCUMENTED
55504*/
55505static bool isRenderable;
55506/*!
55507@brief Disables selection of all instances of this type.
55508
55509
55510@ingroup UNDOCUMENTED
55511*/
55512static bool isSelectable;
55513
55514/*! @name AI
55515@{ */
55516/*!
55517@brief @brief Distance from destination before stopping.
55518
55519
55520When the AIPlayer is moving to a given destination it will move to within this distance of the destination and then stop.  By providing this tolerance it helps the AIPlayer from never reaching its destination due to minor obstacles, rounding errors on its position calculation, etc.  By default it is set to 0.25.
55521
55522*/
55523float mMoveTolerance;
55524/*!
55525@brief @brief Distance tolerance on stuck check.
55526
55527
55528When the AIPlayer is moving to a given destination, if it ever moves less than this tolerance during a single tick, the AIPlayer is considered stuck.  At this point the onMoveStuck() callback is called on the datablock.
55529
55530*/
55531float moveStuckTolerance;
55532/*!
55533@brief @brief The number of ticks to wait before testing if the AIPlayer is stuck.
55534
55535
55536When the AIPlayer is asked to move, this property is the number of ticks to wait before the AIPlayer starts to check if it is stuck.  This delay allows the AIPlayer to accelerate to full speed without its initial slow start being considered as stuck.
55537@note Set to zero to have the stuck test start immediately.
55538
55539*/
55540int moveStuckTestDelay;
55541/*!
55542@brief @brief Distance considered in firing range for callback purposes.
55543*/
55544float AttackRadius;
55545/// @}
55546
55547
55548/*! @name Pathfinding
55549@{ */
55550/*!
55551@brief Allow the character to walk on dry land.
55552*/
55553bool allowWalk;
55554/*!
55555@brief Allow the character to use jump links.
55556*/
55557bool allowJump;
55558/*!
55559@brief Allow the character to use drop links.
55560*/
55561bool allowDrop;
55562/*!
55563@brief Allow the character to move in water.
55564*/
55565bool allowSwim;
55566/*!
55567@brief Allow the character to jump ledges.
55568*/
55569bool allowLedge;
55570/*!
55571@brief Allow the character to use climb links.
55572*/
55573bool allowClimb;
55574/*!
55575@brief Allow the character to use teleporters.
55576*/
55577bool allowTeleport;
55578/// @}
55579
55580
55581/*! @name Game
55582@{ */
55583/// @}
55584
55585
55586/*! @name GameObject
55587@{ */
55588/// @}
55589
55590
55591/*! @name Transform
55592@{ */
55593/// @}
55594
55595
55596/*! @name Editing
55597@{ */
55598/// @}
55599
55600
55601/*! @name Mounting
55602@{ */
55603/// @}
55604
55605
55606/*! @name Ungrouped
55607@{ */
55608/// @}
55609
55610
55611/*! @name Object
55612@{ */
55613/// @}
55614
55615
55616/*! @name Editing
55617@{ */
55618/// @}
55619
55620
55621/*! @name Persistence
55622@{ */
55623/// @}
55624
55625};
55626
55627/*!
55628@brief Represents a position, direction and field of view to render a scene from.
55629
55630A camera is typically manipulated by a GameConnection.  When set as the connection's control object, the camera handles all movement actions ($mvForwardAction, $mvPitch, etc.) just like a Player.
55631@tsexample
55632// Set an already created camera as the GameConnection's control object
55633%connection.setControlObject(%camera);
55634@endtsexample
55635
55636<h3>Methods of Operation</h3>
55637
55638The camera has two general methods of operation.  The first is the standard mode where the camera starts and stops its motion and rotation instantly.  This is the default operation of the camera and is used by most games.  It may be specifically set with Camera::setFlyMode() for 6 DoF motion.  It is also typically the method used with Camera::setOrbitMode() or one of its helper methods to orbit about a specific object (such as the Player's dead body) or a specific point.
55639
55640The second method goes under the name of Newton as it follows Newton's 2nd law of motion: F=ma.  This provides the camera with an ease-in and ease-out feel for both movement and rotation.  To activate this method for movement, either use Camera::setNewtonFlyMode() or set the Camera::newtonMode field to true.  To activate this method for rotation, set the Camera::newtonRotation to true.  This method of operation is not typically used in games, and was developed to allow for a smooth fly through of a game level while recording a demo video.  But with the right force and drag settings, it may give a more organic feel to the camera to games that use an overhead view, such as a RTS.
55641
55642There is a third, minor method of operation but it is not generally used for games.  This is when the camera is used with Torque's World Editor in Edit Orbit Mode.  When set, this allows the camera to rotate about a specific point in the world, and move towards and away from this point.  See Camera::setEditOrbitMode() and Camera::setEditOrbitPoint().  While in this mode, Camera::autoFitRadius() may also be used.
55643
55644@tsexample
55645// Create a camera in the level and set its position to a given spawn point.
55646// Note: The camera starts in the standard fly mode.
55647%cam = new Camera() {
55648   datablock = "Observer";
55649};
55650MissionCleanup.add( %cam );
55651%cam.setTransform( %spawnPoint.getTransform() );
55652@endtsexample
55653
55654@tsexample
55655// Create a camera at the given spawn point for the specified
55656// GameConnection i.e. the client.  Uses the standard
55657// Sim::spawnObject() function to create the camera using the
55658// defined default settings.
55659// Note: The camera starts in the standard fly mode.
55660function GameConnection::spawnCamera(%this, %spawnPoint)
55661{
55662   // Set the control object to the default camera
55663   if (!isObject(%this.camera))
55664   {
55665      if (isDefined("$Game::DefaultCameraClass"))
55666         %this.camera = spawnObject($Game::DefaultCameraClass, $Game::DefaultCameraDataBlock);
55667   }
55668
55669   // If we have a camera then set up some properties
55670   if (isObject(%this.camera))
55671   {
55672      // Make sure we're cleaned up when the mission ends
55673      MissionCleanup.add( %this.camera );
55674
55675      // Make sure the camera is always in scope for the connection
55676      %this.camera.scopeToClient(%this);
55677
55678      // Send all user input from the connection to the camera
55679      %this.setControlObject(%this.camera);
55680
55681      if (isDefined("%spawnPoint"))
55682      {
55683         // Attempt to treat %spawnPoint as an object, such as a
55684         // SpawnSphere class.
55685         if (getWordCount(%spawnPoint) == 1 && isObject(%spawnPoint))
55686         {
55687            %this.camera.setTransform(%spawnPoint.getTransform());
55688         }
55689         else
55690         {
55691            // Treat %spawnPoint as an AngleAxis transform
55692            %this.camera.setTransform(%spawnPoint);
55693         }
55694      }
55695   }
55696}
55697@endtsexample
55698
55699<h3>Motion Modes</h3>
55700
55701Beyond the different operation methods, the Camera may be set to one of a number of motion modes.  These motion modes determine how the camera will respond to input and may be used to constrain how the Camera moves.  The CameraMotionMode enumeration defines the possible set of modes and the Camera's current may be obtained by using getMode().
55702
55703Some of the motion modes may be set using specific script methods.  These often provide additional parameters to set up the mode in one go.  Otherwise, it is always possible to set a Camera's motion mode using the controlMode property.  Just pass in the name of the mode enum.  The following table lists the motion modes, how to set them up, and what they offer:
55704
55705<table border='1' cellpadding='1'><tr><th>Mode</th><th>Set From Script</th><th>Input Move</th><th>Input Rotate</th><th>Can Use Newton Mode?</th></tr><tr><td>Stationary</td><td>controlMode property</td><td>No</td><td>No</td><td>No</td></tr><tr><td>FreeRotate</td><td>controlMode property</td><td>No</td><td>Yes</td><td>Rotate Only</td></tr><tr><td>Fly</td><td>setFlyMode()</td><td>Yes</td><td>Yes</td><td>Yes</td></tr><tr><td>OrbitObject</td><td>setOrbitMode()</td><td>Orbits object</td><td>Points to object</td><td>Move only</td></tr><tr><td>OrbitPoint</td><td>setOrbitPoint()</td><td>Orbits point</td><td>Points to location</td><td>Move only</td></tr><tr><td>TrackObject</td><td>setTrackObject()</td><td>No</td><td>Points to object</td><td>Yes</td></tr><tr><td>Overhead</td><td>controlMode property</td><td>Yes</td><td>No</td><td>Yes</td></tr><tr><td>EditOrbit (object selected)</td><td>setEditOrbitMode()</td><td>Orbits object</td><td>Points to object</td><td>Move only</td></tr><tr><td>EditOrbit (no object)</td><td>setEditOrbitMode()</td><td>Yes</td><td>Yes</td><td>Yes</td></tr></table>
55706
55707<h3>%Trigger Input</h3>
55708
55709Passing a move trigger ($mvTriggerCount0, $mvTriggerCount1, etc.) on to a Camera performs different actions depending on which mode the camera is in.  While in Fly, Overhead or EditOrbit mode, either trigger0 or trigger1 will cause a camera to move twice its normal movement speed.  You can see this in action within the World Editor, where holding down the left mouse button while in mouse look mode (right mouse button is also down) causes the Camera to move faster.
55710
55711Passing along trigger2 will put the camera into strafe mode.  While in this mode a Fly, FreeRotate or Overhead Camera will not rotate from the move input.  Instead the yaw motion will be applied to the Camera's x motion, and the pitch motion will be applied to the Camera's z motion.  You can see this in action within the World Editor where holding down the middle mouse button allows the user to move the camera up, down and side-to-side.
55712
55713While the camera is operating in Newton Mode, trigger0 and trigger1 behave slightly differently.  Here trigger0 activates a multiplier to the applied acceleration force as defined by speedMultiplier.  This has the affect of making the camera move up to speed faster.  trigger1 has the opposite affect by acting as a brake.  When trigger1 is active a multiplier is added to the Camera's drag as defined by brakeMultiplier.
55714
55715@see CameraData
55716@see CameraMotionMode
55717@see Camera::movementSpeed
55718
55719@ingroup BaseCamera
55720
55721*/
55722class Camera : public ShapeBase {
55723public:
55724/*!
55725@brief Returns the current camera control mode.
55726
55727
55728@see CameraMotionMode*/
55729Camera::CameraMotionMode getMode();
55730/*!
55731@brief Get the camera's position in the world.
55732
55733
55734@returns The position in the form of "x y z".*/
55735Point3F getPosition();
55736/*!
55737@brief Get the camera's Euler rotation in radians.
55738
55739
55740@returns The rotation in radians in the form of "x y z".*/
55741Point3F getRotation();
55742/*!
55743@brief Set the camera's Euler rotation in radians.
55744
55745
55746@param rot The rotation in radians in the form of "x y z".@note Rotation around the Y axis is ignored*/
55747void setRotation( Point3F rot );
55748/*!
55749@brief Get the camera's offset from its orbit or tracking point.
55750
55751
55752The offset is added to the camera's position when set to CameraMode::OrbitObject.
55753@returns The offset in the form of "x y z".*/
55754Point3F getOffset();
55755/*!
55756@brief Set the camera's offset.
55757
55758
55759The offset is added to the camera's position when set to CameraMode::OrbitObject.
55760@param offset The distance to offset the camera by in the form of "x y z".*/
55761void setOffset( Point3F offset );
55762/*!
55763@brief Set the camera to orbit around the given object, or if none is given, around the given point.
55764
55765
55766@param orbitObject The object to orbit around.  If no object is given (0 or blank string is passed in) use the orbitPoint instead
55767@param orbitPoint The point to orbit around when no object is given.  In the form of "x y z ax ay az aa" such as returned by SceneObject::getTransform().
55768@param minDistance The minimum distance allowed to the orbit object or point.
55769@param maxDistance The maximum distance allowed from the orbit object or point.
55770@param initDistance The initial distance from the orbit object or point.
55771@param ownClientObj [optional] Are we orbiting an object that is owned by us?  Default is false.
55772@param offset [optional] An offset added to the camera's position.  Default is no offset.
55773@param locked [optional] Indicates the camera does not receive input from the player.  Default is false.
55774@see Camera::setOrbitObject()
55775@see Camera::setOrbitPoint()
55776*/
55777void setOrbitMode( GameBase orbitObject, TransformF orbitPoint, float minDistance, float maxDistance, float initDistance, bool ownClientObj=false, Point3F offset=Point3F::Zero, bool locked=false );
55778/*!
55779@brief Set the camera to orbit around a given object.
55780
55781
55782@param orbitObject The object to orbit around.
55783@param rotation The initial camera rotation about the object in radians in the form of "x y z".
55784@param minDistance The minimum distance allowed to the orbit object or point.
55785@param maxDistance The maximum distance allowed from the orbit object or point.
55786@param initDistance The initial distance from the orbit object or point.
55787@param ownClientObject [optional] Are we orbiting an object that is owned by us?  Default is false.
55788@param offset [optional] An offset added to the camera's position.  Default is no offset.
55789@param locked [optional] Indicates the camera does not receive input from the player.  Default is false.
55790@returns false if the given object could not be found.
55791@see Camera::setOrbitMode()
55792*/
55793bool setOrbitObject( GameBase orbitObject, VectorF rotation, float minDistance, float maxDistance, float initDistance, bool ownClientObject=false, Point3F offset=Point3F::Zero, bool locked=false );
55794/*!
55795@brief Set the camera to orbit around a given point.
55796
55797
55798@param orbitPoint The point to orbit around.  In the form of "x y z ax ay az aa" such as returned by SceneObject::getTransform().
55799@param minDistance The minimum distance allowed to the orbit object or point.
55800@param maxDistance The maximum distance allowed from the orbit object or point.
55801@param initDistance The initial distance from the orbit object or point.
55802@param offset [optional] An offset added to the camera's position.  Default is no offset.
55803@param locked [optional] Indicates the camera does not receive input from the player.  Default is false.
55804@see Camera::setOrbitMode()
55805*/
55806void setOrbitPoint( TransformF orbitPoint, float minDistance, float maxDistance, float initDistance, Point3F offset=Point3F::Zero, bool locked=false );
55807/*!
55808@brief Set the camera to track a given object.
55809
55810
55811@param trackObject The object to track.
55812@param offset [optional] An offset added to the camera's position.  Default is no offset.
55813@returns false if the given object could not be found.
55814*/
55815bool setTrackObject( GameBase trackObject, Point3F offset=Point3F::Zero );
55816/*!
55817@brief Set the editor camera to orbit around a point set with Camera::setEditOrbitPoint().
55818
55819
55820@note This method is generally used only within the World Editor and other tools.  To orbit about an object or point within a game, see Camera::setOrbitMode() and its helper methods.
55821*/
55822void setEditOrbitMode();
55823/*!
55824@brief Set the camera to fly freely.
55825
55826
55827Allows the camera to have 6 degrees of freedom.  Provides for instantaneous motion and rotation unless one of the Newton fields has been set to true.  See Camera::newtonMode and Camera::newtonRotation.
55828*/
55829void setFlyMode();
55830/*!
55831@brief Set the camera to fly freely, but with ease-in and ease-out.
55832
55833
55834This method allows for the same 6 degrees of freedom as Camera::setFlyMode() but activates the ease-in and ease-out on the camera's movement.  To also activate Newton mode for the camera's rotation, set Camera::newtonRotation to true.*/
55835void setNewtonFlyMode();
55836/*!
55837@brief Is this a Newton Fly mode camera with damped rotation?
55838
55839
55840@returns true if the camera uses a damped rotation.  i.e. Camera::newtonRotation is set to true.
55841*/
55842bool isRotationDamped();
55843/*!
55844@brief Get the angular velocity for a Newton mode camera.
55845
55846
55847@returns The angular velocity in the form of "x y z".
55848@note Only returns useful results when Camera::newtonRotation is set to true.*/
55849VectorF getAngularVelocity();
55850/*!
55851@brief Set the angular velocity for a Newton mode camera.
55852
55853
55854@param velocity The angular velocity infor form of "x y z".
55855@note Only takes affect when Camera::newtonRotation is set to true.*/
55856void setAngularVelocity( VectorF velocity );
55857/*!
55858@brief Set the angular force for a Newton mode camera.
55859
55860
55861@param force The angular force applied when attempting to rotate the camera.@note Only takes affect when Camera::newtonRotation is set to true.*/
55862void setAngularForce( float force );
55863/*!
55864@brief Set the angular drag for a Newton mode camera.
55865
55866
55867@param drag The angular drag applied while the camera is rotating.@note Only takes affect when Camera::newtonRotation is set to true.*/
55868void setAngularDrag( float drag );
55869/*!
55870@brief Set the mass for a Newton mode camera.
55871
55872
55873@param mass The mass used during ease-in and ease-out calculations.@note Only used when Camera is in Newton mode.*/
55874void setMass( float mass );
55875/*!
55876@brief Get the velocity for the camera.
55877
55878
55879@returns The camera's velocity in the form of "x y z".@note Only useful when the Camera is in Newton mode.*/
55880VectorF getVelocity();
55881/*!
55882@brief Set the velocity for the camera.
55883
55884
55885@param velocity The camera's velocity in the form of "x y z".@note Only affects the Camera when in Newton mode.*/
55886void setVelocity( VectorF velocity );
55887/*!
55888@brief Set the drag for a Newton mode camera.
55889
55890
55891@param drag The drag applied to the camera while moving.@note Only used when Camera is in Newton mode.*/
55892void setDrag( float drag );
55893/*!
55894@brief Set the force applied to a Newton mode camera while moving.
55895
55896
55897@param force The force applied to the camera while attempting to move.@note Only used when Camera is in Newton mode.*/
55898void setFlyForce( float force );
55899/*!
55900@brief Set the Newton mode camera speed multiplier when trigger[0] is active.
55901
55902
55903@param multiplier The speed multiplier to apply.@note Only used when Camera is in Newton mode.*/
55904void setSpeedMultiplier( float multiplier );
55905/*!
55906@brief Set the Newton mode camera brake multiplier when trigger[1] is active.
55907
55908
55909@param multiplier The brake multiplier to apply.@note Only used when Camera is in Newton mode.*/
55910void setBrakeMultiplier( float multiplier );
55911/*!
55912@brief Is the camera in edit orbit mode?
55913
55914
55915@returns true if the camera is in edit orbit mode.*/
55916bool isEditOrbitMode();
55917/*!
55918@brief Set if there is a valid editor camera orbit point.
55919
55920When validPoint is set to false the Camera operates as if it is in Fly mode rather than an Orbit mode.
55921
55922@param validPoint Indicates the validity of the orbit point.@note Only used when Camera is in Edit Orbit Mode.*/
55923void setValidEditOrbitPoint( bool validPoint );
55924/*!
55925@brief Set the editor camera's orbit point.
55926
55927
55928@param point The point the camera will orbit in the form of "x y z".*/
55929void setEditOrbitPoint( Point3F point );
55930/*!
55931@brief Move the camera to fully view the given radius.
55932
55933
55934@note For this operation to take affect a valid edit orbit point must first be specified.  See Camera::setEditOrbitPoint().
55935@param radius The radius to view.*/
55936void autoFitRadius( float radius );
55937/*!
55938@brief Point the camera at the specified position.  Does not work in Orbit or Track modes.
55939
55940
55941@param point The position to point the camera at.*/
55942void lookAt( Point3F point );
55943
55944/*! @name Callbacks
55945@{ */
55946/// @}
55947
55948/*!
55949@brief Global camera movement speed in units/s (typically m/s), with a base value of 40.
55950
55951Used in the following camera modes:
55952- Edit Orbit Mode
55953- Fly Mode
55954- Overhead Mode
55955@ingroup BaseCamera
55956*/
55957static float movementSpeed;
55958/*!
55959@brief The ExtendedMove position/rotation index used for camera movements.
55960
55961@ingroup BaseCamera
55962*/
55963static int extendedMovePosRotIndex;
55964/*!
55965@brief Disables rendering of all instances of this type.
55966
55967
55968@ingroup UNDOCUMENTED
55969*/
55970static bool isRenderable;
55971/*!
55972@brief Disables selection of all instances of this type.
55973
55974
55975@ingroup UNDOCUMENTED
55976*/
55977static bool isSelectable;
55978
55979/*! @name Camera
55980@{ */
55981/*!
55982@brief The current camera control mode.
55983*/
55984CameraMotionMode controlMode;
55985/// @}
55986
55987
55988/*! @name Camera: Newton Mode
55989@{ */
55990/*!
55991@brief Apply smoothing (acceleration and damping) to camera movements.
55992*/
55993bool newtonMode;
55994/*!
55995@brief Apply smoothing (acceleration and damping) to camera rotations.
55996*/
55997bool newtonRotation;
55998/*!
55999@brief The camera's mass (Newton mode only).  Default value is 10.
56000*/
56001float mass;
56002/*!
56003@brief Drag on camera when moving (Newton mode only).  Default value is 2.
56004*/
56005float drag;
56006/*!
56007@brief Force applied on camera when asked to move (Newton mode only).  Default value is 500.
56008*/
56009float force;
56010/*!
56011@brief Drag on camera when rotating (Newton mode only).  Default value is 2.
56012*/
56013float angularDrag;
56014/*!
56015@brief Force applied on camera when asked to rotate (Newton mode only).  Default value is 100.
56016*/
56017float angularForce;
56018/*!
56019@brief Speed multiplier when triggering the accelerator (Newton mode only).  Default value is 2.
56020*/
56021float speedMultiplier;
56022/*!
56023@brief Speed multiplier when triggering the brake (Newton mode only).  Default value is 2.
56024*/
56025float brakeMultiplier;
56026/// @}
56027
56028
56029/*! @name Game
56030@{ */
56031/// @}
56032
56033
56034/*! @name GameObject
56035@{ */
56036/// @}
56037
56038
56039/*! @name Transform
56040@{ */
56041/// @}
56042
56043
56044/*! @name Editing
56045@{ */
56046/// @}
56047
56048
56049/*! @name Mounting
56050@{ */
56051/// @}
56052
56053
56054/*! @name Ungrouped
56055@{ */
56056/// @}
56057
56058
56059/*! @name Object
56060@{ */
56061/// @}
56062
56063
56064/*! @name Editing
56065@{ */
56066/// @}
56067
56068
56069/*! @name Persistence
56070@{ */
56071/// @}
56072
56073};
56074
56075/*!
56076@brief Base debris class. Uses the DebrisData datablock for properties of individual debris objects.
56077
56078Debris is typically made up of a shape and up to two particle emitters.  In most cases Debris objects are not created directly.  They are usually produced automatically by other means, such as through the Explosion class.  When an explosion goes off, its ExplosionData datablock determines what Debris to emit.
56079@tsexample
56080datablock ExplosionData(GrenadeLauncherExplosion)
56081{
56082   // Assiging debris data
56083   debris = GrenadeDebris;
56084
56085   // Adjust how debris is ejected
56086   debrisThetaMin = 10;
56087   debrisThetaMax = 60;
56088   debrisNum = 4;
56089   debrisNumVariance = 2;
56090   debrisVelocity = 25;
56091   debrisVelocityVariance = 5;
56092
56093   // Note: other ExplosionData properties are not listed for this example
56094};
56095@endtsexample
56096
56097@note Debris are client side only objects.
56098@see DebrisData
56099@see ExplosionData
56100@see Explosion
56101@ingroup FX
56102
56103*/
56104class Debris : public GameBase {
56105public:
56106/*!
56107@brief Manually set this piece of debris at the given position with the given velocity.
56108
56109Usually you do not manually create Debris objects as they are generated through other means, such as an Explosion.  This method exists when you do manually create a Debris object and want to have it start moving.
56110@param inputPosition Position to place the debris.
56111@param inputVelocity Velocity to move the debris after it has been placed.
56112@return Always returns true.
56113@tsexample
56114// Define the position
56115%position = "1.0 1.0 1.0";
56116
56117// Define the velocity
56118%velocity = "1.0 0.0 0.0";
56119
56120// Inform the debris object of its new position and velocity
56121%debris.init(%position,%velocity);
56122@endtsexample*/
56123bool init( string inputPosition="1.0 1.0 1.0", string inputVelocity="1.0 0.0 0.0" );
56124
56125/*! @name Callbacks
56126@{ */
56127/// @}
56128
56129/*!
56130@brief Disables rendering of all instances of this type.
56131
56132
56133@ingroup UNDOCUMENTED
56134*/
56135static bool isRenderable;
56136/*!
56137@brief Disables selection of all instances of this type.
56138
56139
56140@ingroup UNDOCUMENTED
56141*/
56142static bool isSelectable;
56143
56144/*! @name Debris
56145@{ */
56146/*!
56147@brief @brief Length of time for this debris object to exist. When expired, the object will be deleted.
56148
56149
56150The initial lifetime value comes from the DebrisData datablock.
56151@see DebrisData::lifetime
56152@see DebrisData::lifetimeVariance
56153
56154*/
56155float lifetime;
56156/// @}
56157
56158
56159/*! @name Game
56160@{ */
56161/// @}
56162
56163
56164/*! @name GameObject
56165@{ */
56166/// @}
56167
56168
56169/*! @name Transform
56170@{ */
56171/// @}
56172
56173
56174/*! @name Editing
56175@{ */
56176/// @}
56177
56178
56179/*! @name Mounting
56180@{ */
56181/// @}
56182
56183
56184/*! @name Ungrouped
56185@{ */
56186/// @}
56187
56188
56189/*! @name Object
56190@{ */
56191/// @}
56192
56193
56194/*! @name Editing
56195@{ */
56196/// @}
56197
56198
56199/*! @name Persistence
56200@{ */
56201/// @}
56202
56203};
56204
56205/*!
56206@brief An infinite plane extending in all direction.
56207
56208%GroundPlane is useful for setting up simple testing scenes, or it can be placed under an existing scene to keep objects from falling into 'nothing'.
56209
56210%GroundPlane may not be moved or rotated, it is always at the world origin.
56211
56212@ingroup Terrain
56213*/
56214class GroundPlane : public SceneObject {
56215public:
56216/*!
56217@brief Intended as a helper to developers and editor scripts.
56218
56219Force trigger an inspectPostApply. This will transmit material and other fields to client objects.*/
56220void postApply();
56221
56222/*! @name Callbacks
56223@{ */
56224/// @}
56225
56226/*!
56227@brief Disables rendering of all instances of this type.
56228
56229
56230@ingroup UNDOCUMENTED
56231*/
56232static bool isRenderable;
56233/*!
56234@brief Disables selection of all instances of this type.
56235
56236
56237@ingroup UNDOCUMENTED
56238*/
56239static bool isSelectable;
56240
56241/*! @name Plane
56242@{ */
56243/*!
56244@brief Square size in meters to which %GroundPlane subdivides its geometry.
56245*/
56246float squareSize;
56247/*!
56248@brief Scale of texture repeat in the U direction.
56249*/
56250float scaleU;
56251/*!
56252@brief Scale of texture repeat in the V direction.
56253*/
56254float scaleV;
56255/*!
56256@brief  ¨ç
56257*/
56258string MaterialFile;
56259/*!
56260@brief ðŒE 
56261*/
56262assetIdString MaterialAsset;
56263/// @}
56264
56265
56266/*! @name GameObject
56267@{ */
56268/// @}
56269
56270
56271/*! @name Transform
56272@{ */
56273/// @}
56274
56275
56276/*! @name Editing
56277@{ */
56278/// @}
56279
56280
56281/*! @name Mounting
56282@{ */
56283/// @}
56284
56285
56286/*! @name Ungrouped
56287@{ */
56288/// @}
56289
56290
56291/*! @name Object
56292@{ */
56293/// @}
56294
56295
56296/*! @name Editing
56297@{ */
56298/// @}
56299
56300
56301/*! @name Persistence
56302@{ */
56303/// @}
56304
56305};
56306
56307/*!
56308@brief GUI control which displays a 3D model.
56309
56310Model displayed in the control can have other objects mounted onto it, and the light settings can be adjusted.
56311
56312@tsexample
56313   new GuiObjectView(ObjectPreview)
56314   {
56315      shapeFile = "art/shapes/items/kit/healthkit.dts";
56316      mountedNode = "mount0";
56317      lightColor = "1 1 1 1";
56318      lightAmbient = "0.5 0.5 0.5 1";
56319      lightDirection = "0 0.707 -0.707";
56320      orbitDiststance = "2";
56321      minOrbitDiststance = "0.917688";
56322      maxOrbitDiststance = "5";
56323      cameraSpeed = "0.01";
56324      cameraZRot = "0";
56325      forceFOV = "0";
56326      reflectPriority = "0";
56327   };
56328@endtsexample
56329
56330@see GuiControl
56331
56332@ingroup Gui3D
56333
56334*/
56335class GuiObjectView : public GuiTSCtrl {
56336public:
56337/*!
56338@brief Return the model displayed in this view.
56339
56340@tsexample
56341// Request the displayed model name from the GuiObjectView object.
56342%modelName = %thisGuiObjectView.getModel();
56343@endtsexample
56344
56345@return Name of the displayed model.
56346
56347@see GuiControl*/
56348string getModel();
56349/*!
56350@brief Sets the model to be displayed in this control.
56351
56352@param shapeName Name of the model to display.
56353@tsexample
56354// Define the model we want to display
56355%shapeName = "gideon.dts";
56356
56357// Tell the GuiObjectView object to display the defined model
56358%thisGuiObjectView.setModel(%shapeName);
56359@endtsexample
56360
56361@see GuiControl*/
56362void setModel( string shapeName );
56363/*!
56364@brief Return the name of the mounted model.
56365
56366@tsexample
56367// Request the name of the mounted model from the GuiObjectView object
56368%mountedModelName = %thisGuiObjectView.getMountedModel();
56369@endtsexample
56370
56371@return Name of the mounted model.
56372
56373@see GuiControl*/
56374string getMountedModel();
56375/*!
56376@brief Sets the model to be mounted on the primary model.
56377
56378@param shapeName Name of the model to mount.
56379@tsexample
56380// Define the model name to mount
56381%modelToMount = "GideonGlasses.dts";
56382
56383// Inform the GuiObjectView object to mount the defined model to the existing model in the control
56384%thisGuiObjectView.setMountedModel(%modelToMount);
56385@endtsexample
56386
56387@see GuiControl*/
56388void setMountedModel( string shapeName );
56389/*!
56390@brief Return the name of skin used on the primary model.
56391
56392@tsexample
56393// Request the name of the skin used on the primary model in the control
56394%skinName = %thisGuiObjectView.getSkin();
56395@endtsexample
56396
56397@return Name of the skin used on the primary model.
56398
56399@see GuiControl*/
56400string getSkin();
56401/*!
56402@brief Sets the skin to use on the model being displayed.
56403
56404@param skinName Name of the skin to use.
56405@tsexample
56406// Define the skin we want to apply to the main model in the control
56407%skinName = "disco_gideon";
56408
56409// Inform the GuiObjectView control to update the skin the to defined skin
56410%thisGuiObjectView.setSkin(%skinName);
56411@endtsexample
56412
56413@see GuiControl*/
56414void setSkin( string skinName );
56415/*!
56416@brief Return the name of skin used on the mounted model.
56417
56418@tsexample
56419// Request the skin name from the model mounted on to the main model in the control
56420%mountModelSkin = %thisGuiObjectView.getMountSkin();
56421@endtsexample
56422
56423@return Name of the skin used on the mounted model.
56424
56425@see GuiControl*/
56426string getMountSkin( int param1, int param2 );
56427/*!
56428@brief Sets the skin to use on the mounted model.
56429
56430@param skinName Name of the skin to set on the model mounted to the main model in the control
56431@tsexample
56432// Define the name of the skin
56433%skinName = "BronzeGlasses";
56434
56435// Inform the GuiObjectView Control of the skin to use on the mounted model
56436%thisGuiObjectViewCtrl.setMountSkin(%skinName);
56437@endtsexample
56438
56439@see GuiControl*/
56440void setMountSkin( string skinName );
56441/*!
56442@brief Sets the animation to play for the viewed object.
56443
56444@param indexOrName The index or name of the animation to play.
56445@tsexample
56446// Set the animation index value, or animation sequence name.
56447%indexVal = "3";
56448//OR:
56449%indexVal = "idle";
56450
56451// Inform the GuiObjectView object to set the animation sequence of the object in the control.
56452%thisGuiObjectVew.setSeq(%indexVal);
56453@endtsexample
56454
56455@see GuiControl*/
56456void setSeq( string indexOrName );
56457/*!
56458@brief Mounts the given model to the specified mount point of the primary model displayed in this control.
56459
56460Detailed description
56461
56462@param shapeName Name of the model to mount.
56463@param mountNodeIndexOrName Index or name of the mount point to be mounted to. If index, corresponds to "mountN" in your shape where N is the number passed here.
56464@tsexample
56465// Set the shapeName to mount
56466%shapeName = "GideonGlasses.dts"
56467
56468// Set the mount node of the primary model in the control to mount the new shape at
56469%mountNodeIndexOrName = "3";
56470//OR:
56471%mountNodeIndexOrName = "Face";
56472
56473// Inform the GuiObjectView object to mount the shape at the specified node.
56474%thisGuiObjectView.setMount(%shapeName,%mountNodeIndexOrName);
56475@endtsexample
56476
56477@see GuiControl*/
56478void setMount( string shapeName, string mountNodeIndexOrName );
56479/*!
56480@brief Return the current distance at which the camera orbits the object.
56481
56482@tsexample
56483// Request the current orbit distance
56484%orbitDistance = %thisGuiObjectView.getOrbitDistance();
56485@endtsexample
56486
56487@return The distance at which the camera orbits the object.
56488
56489@see GuiControl*/
56490float getOrbitDistance();
56491/*!
56492@brief Sets the distance at which the camera orbits the object. Clamped to the acceptable range defined in the class by min and max orbit distances.
56493
56494Detailed description
56495
56496@param distance The distance to set the orbit to (will be clamped).
56497@tsexample
56498// Define the orbit distance value
56499%orbitDistance = "1.5";
56500
56501// Inform the GuiObjectView object to set the orbit distance to the defined value
56502%thisGuiObjectView.setOrbitDistance(%orbitDistance);
56503@endtsexample
56504
56505@see GuiControl*/
56506void setOrbitDistance( float distance );
56507/*!
56508@brief Return the current multiplier for camera zooming and rotation.
56509
56510@tsexample
56511// Request the current camera zooming and rotation multiplier value
56512%multiplier = %thisGuiObjectView.getCameraSpeed();
56513@endtsexample
56514
56515@return Camera zooming / rotation multiplier value.
56516
56517@see GuiControl*/
56518float getCameraSpeed();
56519/*!
56520@brief Sets the multiplier for the camera rotation and zoom speed.
56521
56522@param factor Multiplier for camera rotation and zoom speed.
56523@tsexample
56524// Set the factor value
56525%factor = "0.75";
56526
56527// Inform the GuiObjectView object to set the camera speed.
56528%thisGuiObjectView.setCameraSpeed(%factor);
56529@endtsexample
56530
56531@see GuiControl*/
56532void setCameraSpeed( float factor );
56533/*!
56534@brief Set the light color on the sun object used to render the model.
56535
56536@param color Color of sunlight.
56537@tsexample
56538// Set the color value for the sun
56539%color = "1.0 0.4 0.5";
56540
56541// Inform the GuiObjectView object to change the sun color to the defined value
56542%thisGuiObjectView.setLightColor(%color);
56543@endtsexample
56544
56545@see GuiControl*/
56546void setLightColor( LinearColorF color );
56547/*!
56548@brief Set the light ambient color on the sun object used to render the model.
56549
56550@param color Ambient color of sunlight.
56551@tsexample
56552// Define the sun ambient color value
56553%color = "1.0 0.4 0.6";
56554
56555// Inform the GuiObjectView object to set the sun ambient color to the requested value
56556%thisGuiObjectView.setLightAmbient(%color);
56557@endtsexample
56558
56559@see GuiControl*/
56560void setLightAmbient( LinearColorF color );
56561/*!
56562@brief Set the light direction from which to light the model.
56563
56564@param direction XYZ direction from which the light will shine on the model
56565@tsexample
56566// Set the light direction
56567%direction = "1.0 0.2 0.4"
56568
56569// Inform the GuiObjectView object to change the light direction to the defined value
56570%thisGuiObjectView.setLightDirection(%direction);
56571@endtsexample
56572
56573@see GuiControl*/
56574void setLightDirection( Point3F direction );
56575
56576/*! @name Callbacks
56577@{ */
56578/*!
56579@brief Called whenever the mouse enters the control.
56580
56581@tsexample
56582// The mouse has entered the control, causing the callback to occur
56583GuiObjectView::onMouseEnter(%this)
56584   {
56585      // Code to run when the mouse enters this control
56586   }
56587@endtsexample
56588
56589@see GuiControl*/
56590void onMouseEnter();
56591/*!
56592@brief Called whenever the mouse leaves the control.
56593
56594@tsexample
56595// The mouse has left the control, causing the callback to occur
56596GuiObjectView::onMouseLeave(%this)
56597   {
56598      // Code to run when the mouse leaves this control
56599   }
56600@endtsexample
56601
56602@see GuiControl*/
56603void onMouseLeave();
56604/// @}
56605
56606
56607/*! @name Model
56608@{ */
56609/*!
56610@brief The object model shape file to show in the view.
56611*/
56612filename shapeFile;
56613/*!
56614@brief The skin to use on the object model.
56615*/
56616string skin;
56617/// @}
56618
56619
56620/*! @name Animation
56621@{ */
56622/*!
56623@brief The animation sequence to play on the model.
56624*/
56625string animSequence;
56626/// @}
56627
56628
56629/*! @name Mounting
56630@{ */
56631/*!
56632@brief Optional shape file to mount on the primary model (e.g. weapon).
56633*/
56634filename mountedShapeFile;
56635/*!
56636@brief Skin name used on mounted shape file.
56637*/
56638string mountedSkin;
56639/*!
56640@brief Name of node on primary model to which to mount the secondary shape.
56641*/
56642string mountedNode;
56643/// @}
56644
56645
56646/*! @name Lighting
56647@{ */
56648/*!
56649@brief Diffuse color of the sunlight used to render the model.
56650*/
56651LinearColorF lightColor;
56652/*!
56653@brief Ambient color of the sunlight used to render the model.
56654*/
56655LinearColorF lightAmbient;
56656/*!
56657@brief Direction from which the model is illuminated.
56658*/
56659Point3F lightDirection;
56660/// @}
56661
56662
56663/*! @name Camera
56664@{ */
56665/*!
56666@brief Distance from which to render the model.
56667*/
56668float orbitDiststance;
56669/*!
56670@brief Maxiumum distance to which the camera can be zoomed out.
56671*/
56672float minOrbitDiststance;
56673/*!
56674@brief Minimum distance below which the camera will not zoom in further.
56675*/
56676float maxOrbitDiststance;
56677/*!
56678@brief Multiplier for mouse camera operations.
56679*/
56680float cameraSpeed;
56681/*!
56682@brief Set the camera rotation.
56683*/
56684Point3F cameraRotation;
56685/// @}
56686
56687
56688/*! @name Camera
56689@{ */
56690/// @}
56691
56692
56693/*! @name Rendering
56694@{ */
56695/// @}
56696
56697
56698/*! @name Layout
56699@{ */
56700/// @}
56701
56702
56703/*! @name Layout
56704@{ */
56705/// @}
56706
56707
56708/*! @name Control
56709@{ */
56710/// @}
56711
56712
56713/*! @name ToolTip
56714@{ */
56715/// @}
56716
56717
56718/*! @name Editing
56719@{ */
56720/// @}
56721
56722
56723/*! @name Localization
56724@{ */
56725/// @}
56726
56727
56728/*! @name Ungrouped
56729@{ */
56730/// @}
56731
56732
56733/*! @name Object
56734@{ */
56735/// @}
56736
56737
56738/*! @name Editing
56739@{ */
56740/// @}
56741
56742
56743/*! @name Persistence
56744@{ */
56745/// @}
56746
56747};
56748
56749/*!
56750@brief Base Item class. Uses the ItemData datablock for common properties.
56751
56752Items represent an object in the world, usually one that the player will interact with.  One example is a health kit on the group that is automatically picked up when the player comes into contact with it.
56753
56754@tsexample
56755// This is the "health patch" dropped by a dying player.
56756datablock ItemData(HealthKitPatch)
56757{
56758   // Mission editor category, this datablock will show up in the
56759   // specified category under the "shapes" root category.
56760   category = "Health";
56761
56762   className = "HealthPatch";
56763
56764   // Basic Item properties
56765   shapeFile = "art/shapes/items/patch/healthpatch.dts";
56766   mass = 2;
56767   friction = 1;
56768   elasticity = 0.3;
56769   emap = true;
56770
56771   // Dynamic properties used by the scripts
56772   pickupName = "a health patch";
56773   repairAmount = 50;
56774};
56775
56776%obj = new Item()
56777{
56778   dataBlock = HealthKitSmall;
56779   parentGroup = EWCreatorWindow.objectGroup;
56780   static = true;
56781   rotate = true;
56782};
56783@endtsexample
56784
56785@see ItemData
56786@ingroup gameObjects
56787
56788*/
56789class Item : public ShapeBase {
56790public:
56791/*!
56792@brief Is the object static (ie, non-movable)?
56793
56794@return True if the object is static, false if it is not.
56795@tsexample
56796// Query the item on if it is or is not static.
56797%isStatic = %itemData.isStatic();
56798
56799@endtsexample
56800
56801@see static*/
56802bool isStatic();
56803/*!
56804@brief Is the object at rest (ie, no longer moving)?
56805
56806@return True if the object is at rest, false if it is not.
56807@tsexample
56808// Query the item on if it is or is not at rest.
56809%isAtRest = %item.isAtRest();
56810
56811@endtsexample*/
56812bool isAtRest();
56813/*!
56814@brief Is the object still rotating?
56815
56816@return True if the object is still rotating, false if it is not.
56817@tsexample
56818// Query the item on if it is or is not rotating.
56819%isRotating = %itemData.isRotating();
56820
56821@endtsexample
56822
56823@see rotate*/
56824bool isRotating();
56825/*!
56826@brief Temporarily disable collisions against a specific ShapeBase object.
56827
56828This is useful to prevent a player from immediately picking up an Item they have just thrown.  Only one object may be on the timeout list at a time.  The timeout is defined as 15 ticks.
56829
56830@param objectID ShapeBase object ID to disable collisions against.
56831@return Returns true if the ShapeBase object requested could be found, false if it could not.
56832@tsexample
56833// Set the ShapeBase Object ID to disable collisions against
56834%ignoreColObj = %player.getID();
56835
56836// Inform this Item object to ignore collisions temproarily against the %ignoreColObj.
56837%item.setCollisionTimeout(%ignoreColObj);
56838
56839@endtsexample*/
56840bool setCollisionTimeout( int ignoreColObj );
56841/*!
56842@brief Get the position on the surface on which this Item is stuck.
56843
56844@return Returns The XYZ position of where this Item is stuck.
56845@tsexample
56846// Acquire the position where this Item is currently stuck
56847%stuckPosition = %item.getLastStickPos();
56848
56849@endtsexample
56850
56851@note Server side only.*/
56852string getLastStickyPos();
56853/*!
56854@brief Get the normal of the surface on which the object is stuck.
56855
56856@return Returns The XYZ normal from where this Item is stuck.
56857@tsexample
56858// Acquire the position where this Item is currently stuck
56859%stuckPosition = %item.getLastStickPos();
56860
56861@endtsexample
56862
56863@note Server side only.*/
56864string getLastStickyNormal();
56865
56866/*! @name Callbacks
56867@{ */
56868/*!
56869@brief Informs the Item object that it is now sticking to another object.
56870
56871This callback is only called if the ItemData::sticky property for this Item is true.
56872@param objID Object ID this Item object.
56873@note Server side only.
56874@see Item, ItemData*/
56875void onStickyCollision( string objID );
56876/*!
56877@brief Informs an Item object that it has entered liquid, along with information about the liquid type.
56878
56879@param objID Object ID for this Item object.
56880@param waterCoverage How much coverage of water this Item object has.
56881@param liquidType The type of liquid that this Item object has entered.
56882@note Server side only.
56883@see Item, ItemData, WaterObject
56884*/
56885void onEnterLiquid( string objID, float waterCoverage, string liquidType );
56886/*!
56887@brief Informs an Item object that it has left a liquid, along with information about the liquid type.
56888
56889@param objID Object ID for this Item object.
56890@param liquidType The type of liquid that this Item object has left.
56891@note Server side only.
56892@see Item, ItemData, WaterObject
56893*/
56894void onLeaveLiquid( string objID, string liquidType );
56895/// @}
56896
56897/*!
56898@brief Disables rendering of all instances of this type.
56899
56900
56901@ingroup UNDOCUMENTED
56902*/
56903static bool isRenderable;
56904/*!
56905@brief Disables selection of all instances of this type.
56906
56907
56908@ingroup UNDOCUMENTED
56909*/
56910static bool isSelectable;
56911/*!
56912@brief Fraction of tick at which instant warp occures on the client.
56913
56914@ingroup GameObjects*/
56915static float minWarpTicks;
56916/*!
56917@brief When a warp needs to occur due to the client being too far off from the server, this is the maximum number of ticks we'll allow the client to warp to catch up.
56918
56919@ingroup GameObjects*/
56920static int maxWarpTicks;
56921
56922/*! @name Misc
56923@{ */
56924/*!
56925@brief If true, the object is not moving in the world.
56926
56927
56928*/
56929bool static;
56930/*!
56931@brief If true, the object will automatically rotate around its Z axis.
56932
56933
56934*/
56935bool rotate;
56936/// @}
56937
56938
56939/*! @name Game
56940@{ */
56941/// @}
56942
56943
56944/*! @name GameObject
56945@{ */
56946/// @}
56947
56948
56949/*! @name Transform
56950@{ */
56951/// @}
56952
56953
56954/*! @name Editing
56955@{ */
56956/// @}
56957
56958
56959/*! @name Mounting
56960@{ */
56961/// @}
56962
56963
56964/*! @name Ungrouped
56965@{ */
56966/// @}
56967
56968
56969/*! @name Object
56970@{ */
56971/// @}
56972
56973
56974/*! @name Editing
56975@{ */
56976/// @}
56977
56978
56979/*! @name Persistence
56980@{ */
56981/// @}
56982
56983};
56984
56985/*!
56986@brief A helper datablock used by classes (such as shapebase) that submit lights to the scene but do not use actual "LightBase" objects.
56987
56988This datablock stores the properties of that light as fields that can be initialized from script.@tsexample
56989// Declare a light description to be used on a rocket launcher projectile
56990datablock LightDescription(RocketLauncherLightDesc)
56991{
56992   range = 4.0;
56993   color = "1 1 0";
56994   brightness = 5.0;
56995   animationType = PulseLightAnim;
56996   animationPeriod = 0.25;
56997};
56998
56999// Declare a ProjectileDatablock which uses the light description
57000datablock ProjectileData(RocketLauncherProjectile)
57001{
57002   lightDesc = RocketLauncherLightDesc;
57003
57004   projectileShapeName = "art/shapes/weapons/SwarmGun/rocket.dts";
57005
57006   directDamage = 30;
57007   radiusDamage = 30;
57008   damageRadius = 5;
57009   areaImpulse = 2500;
57010
57011   // ... remaining ProjectileData fields not listed for this example
57012};
57013@endtsexample
57014
57015@see LightBase
57016
57017@ingroup Lighting
57018
57019*/
57020class LightDescription : public SimDataBlock {
57021public:
57022/*!
57023@brief Force an inspectPostApply call for the benefit of tweaking via the console
57024
57025Normally this functionality is only exposed to objects via the World Editor, once changes have been made. Exposing apply to script allows you to make changes to it on the fly without the World Editor.
57026
57027@note This is intended for debugging and tweaking, not for game play
57028
57029@tsexample
57030// Change a property of the light description
57031RocketLauncherLightDesc.brightness = 10;
57032
57033// Make it so
57034RocketLauncherLightDesc.apply();
57035@endtsexample*/
57036void apply();
57037
57038/*! @name Callbacks
57039@{ */
57040/// @}
57041
57042
57043/*! @name Light
57044@{ */
57045/*!
57046@brief Changes the base color hue of the light.
57047*/
57048LinearColorF color;
57049/*!
57050@brief Adjusts the lights power, 0 being off completely.
57051*/
57052float brightness;
57053/*!
57054@brief Controls the size (radius) of the light
57055*/
57056float range;
57057/*!
57058@brief Enables/disabled shadow casts by this light.
57059*/
57060bool castShadows;
57061/*!
57062@brief static shadow refresh rate (milliseconds)
57063*/
57064int staticRefreshFreq;
57065/*!
57066@brief dynamic shadow refresh rate (milliseconds)
57067*/
57068int dynamicRefreshFreq;
57069/// @}
57070
57071
57072/*! @name Light Animation
57073@{ */
57074/*!
57075@brief Datablock containing light animation information (LightAnimData)
57076*/
57077LightAnimData animationType;
57078/*!
57079@brief The length of time in seconds for a single playback of the light animation
57080*/
57081float animationPeriod;
57082/*!
57083@brief The phase used to offset the animation start time to vary the animation of nearby lights.
57084*/
57085float animationPhase;
57086/// @}
57087
57088
57089/*! @name Misc
57090@{ */
57091/*!
57092@brief Datablock containing light flare information (LightFlareData)
57093*/
57094LightFlareData flareType;
57095/*!
57096@brief Globally scales all features of the light flare
57097*/
57098float flareScale;
57099/// @}
57100
57101
57102/*! @name Advanced Lighting
57103@{ */
57104/*!
57105@brief The proportions of constant, linear, and quadratic attenuation to use for the falloff for point and spot lights.
57106*/
57107Point3F attenuationRatio;
57108/*!
57109@brief The type of shadow to use on this light.
57110*/
57111ShadowType shadowType;
57112/*!
57113@brief A custom pattern texture which is projected from the light.
57114*/
57115filename cookie;
57116/*!
57117@brief The texture size of the shadow map.
57118*/
57119int texSize;
57120/*!
57121@brief The ESM shadow darkening factor
57122*/
57123Point4F overDarkFactor;
57124/*!
57125@brief The distance from the camera to extend the PSSM shadow.
57126*/
57127float shadowDistance;
57128/*!
57129*/
57130float shadowSoftness;
57131/*!
57132@brief The logrithmic PSSM split distance factor.
57133*/
57134int numSplits;
57135/*!
57136@brief The logrithmic PSSM split distance factor.
57137*/
57138float logWeight;
57139/*!
57140@brief Start fading shadows out at this distance.  0 = auto calculate this distance.
57141*/
57142float fadeStartDistance;
57143/*!
57144@brief This toggles only terrain being rendered to the last split of a PSSM shadow map.
57145*/
57146bool lastSplitTerrainOnly;
57147/// @}
57148
57149
57150/*! @name Advanced Lighting Lightmap
57151@{ */
57152/*!
57153@brief This light is represented in lightmaps (static light, default: false)
57154*/
57155bool representedInLightmap;
57156/*!
57157@brief The color that should be used to multiply-blend dynamic shadows onto lightmapped geometry (ignored if 'representedInLightmap' is false)
57158*/
57159LinearColorF shadowDarkenColor;
57160/*!
57161@brief This light should render lightmapped geometry during its shadow-map update (ignored if 'representedInLightmap' is false)
57162*/
57163bool includeLightmappedGeometryInShadow;
57164/// @}
57165
57166
57167/*! @name Ungrouped
57168@{ */
57169/// @}
57170
57171
57172/*! @name Object
57173@{ */
57174/// @}
57175
57176
57177/*! @name Editing
57178@{ */
57179/// @}
57180
57181
57182/*! @name Persistence
57183@{ */
57184/// @}
57185
57186};
57187
57188/*!
57189@brief Defines a light flare effect usable by scene lights.
57190
57191%LightFlareData is a datablock which defines a type of flare effect. This may then be referenced by other classes which support the rendering of a flare: Sun, ScatterSky, LightBase.
57192
57193A flare contains one or more elements defined in the element* named fields of %LightFlareData, with a maximum of ten elements. Each element is rendered as a 2D sprite in screenspace.
57194
57195@tsexample
57196// example from Full Template, core/art/datablocks/lights.cs
57197datablock LightFlareData( LightFlareExample0 )
57198{
57199   overallScale = 2.0;
57200   flareEnabled = true;
57201   renderReflectPass = true;
57202   flareTexture = "./../special/lensFlareSheet1";
57203   occlusionRadius = 0.25;
57204   
57205   elementRect[0] = "0 512 512 512";
57206   elementDist[0] = 0.0;
57207   elementScale[0] = 0.5;
57208   elementTint[0] = "1.0 1.0 1.0";
57209   elementRotate[0] = false;
57210   elementUseLightColor[0] = false;
57211   
57212   elementRect[1] = "512 0 512 512";
57213   elementDist[1] = 0.0;
57214   elementScale[1] = 2.0;
57215   elementTint[1] = "0.5 0.5 0.5";
57216   elementRotate[1] = false;
57217   elementUseLightColor[1] = false;
57218};
57219@endtsexample
57220The elementDist field defines where along the flare's beam the element appears. A distance of 0.0 is directly over the light source, a distance of 1.0 is at the screen center, and a distance of 2.0 is at the position of the light source mirrored across the screen center.
57221@image html images/lightFlareData_diagram.png
57222@ingroup Lighting
57223*/
57224class LightFlareData : public SimDataBlock {
57225public:
57226/*!
57227@brief Intended as a helper to developers and editor scripts.
57228
57229Force trigger an inspectPostApply*/
57230void apply();
57231
57232/*! @name Callbacks
57233@{ */
57234/// @}
57235
57236
57237/*! @name LightFlareData
57238@{ */
57239/*!
57240@brief Size scale applied to all elements of the flare.
57241*/
57242float overallScale;
57243/*!
57244@brief If positive an occlusion query is used to test flare visibility, else it uses simple raycasts.
57245*/
57246float occlusionRadius;
57247/*!
57248@brief If false the flare does not render in reflections, else only non-zero distance elements are rendered.
57249*/
57250bool renderReflectPass;
57251/// @}
57252
57253
57254/*! @name FlareElements
57255@{ */
57256/*!
57257@brief Allows the user to disable this flare globally for any lights referencing it.
57258*/
57259bool flareEnabled;
57260/*!
57261@brief The texture / sprite sheet for this flare.
57262*/
57263filename flareTexture;
57264/*!
57265@brief A rectangle specified in pixels of the flareTexture image.
57266*/
57267RectF elementRect[ 20 ];
57268/*!
57269@brief Where this element appears along the flare beam.
57270*/
57271float elementDist[ 20 ];
57272/*!
57273@brief Size scale applied to this element.
57274*/
57275float elementScale[ 20 ];
57276/*!
57277@brief Used to modulate this element's color if elementUseLightColor is false.
57278
57279@see elementUseLightColor
57280*/
57281LinearColorF elementTint[ 20 ];
57282/*!
57283@brief Defines if this element orients to point along the flare beam or if it is always upright.
57284*/
57285bool elementRotate[ 20 ];
57286/*!
57287@brief If true this element's color is modulated by the light color. If false, elementTint will be used.
57288
57289@see elementTint
57290*/
57291bool elementUseLightColor[ 20 ];
57292/// @}
57293
57294
57295/*! @name Ungrouped
57296@{ */
57297/// @}
57298
57299
57300/*! @name Object
57301@{ */
57302/// @}
57303
57304
57305/*! @name Editing
57306@{ */
57307/// @}
57308
57309
57310/*! @name Persistence
57311@{ */
57312/// @}
57313
57314};
57315
57316/*!
57317@brief Level object which defines the boundaries of the level.
57318
57319This is a simple box with starting points, width, depth, and height. It does not have any default functionality. Instead, when objects hit the boundaries certain script callbacks will be made allowing you to control the reaction.
57320
57321@tsexample
57322new MissionArea(GlobalMissionArea)
57323{
57324     Area = "-152 -352 1008 864";
57325     flightCeiling = "300";
57326     flightCeilingRange = "20";
57327     canSaveDynamicFields = "1";
57328       enabled = "1";
57329       TypeBool locked = "false";
57330};
57331@endtsexample
57332
57333@ingroup enviroMisc
57334
57335*/
57336class MissionArea : public NetObject {
57337public:
57338/*!
57339@brief Returns 4 fields: starting x, starting y, extents x, extents y.
57340
57341*/
57342string getArea();
57343/*!
57344@brief - Defines the size of the MissionArea
57345
57346param x Starting X coordinate position for MissionArea
57347param y Starting Y coordinate position for MissionArea
57348param width New width of the MissionArea
57349param height New height of the MissionArea
57350@note Only the server object may be set.*/
57351void setArea( int x, int y, int width, int height );
57352/*!
57353@brief Intended as a helper to developers and editor scripts.
57354
57355Force trigger an inspectPostApply. This will transmit material and other fields ( not including nodes ) to client objects.*/
57356void postApply();
57357
57358/*! @name Callbacks
57359@{ */
57360/// @}
57361
57362
57363/*! @name Dimensions
57364@{ */
57365/*!
57366@brief Four corners (X1, X2, Y1, Y2) that makes up the level's boundaries
57367*/
57368RectI area;
57369/*!
57370@brief Represents the top of the mission area, used by FlyingVehicle. 
57371*/
57372float flightCeiling;
57373/*!
57374@brief Distance from ceiling before FlyingVehicle thrust is cut off. 
57375*/
57376float flightCeilingRange;
57377/// @}
57378
57379
57380/*! @name Ungrouped
57381@{ */
57382/// @}
57383
57384
57385/*! @name Object
57386@{ */
57387/// @}
57388
57389
57390/*! @name Editing
57391@{ */
57392/// @}
57393
57394
57395/*! @name Persistence
57396@{ */
57397/// @}
57398
57399};
57400
57401/*!
57402@brief This class is used for creating any type of game object, assigning it a class, datablock, and other properties when it is spawned.
57403
57404Torque 3D uses a simple spawn system, which can be easily modified to spawn any kind of object (of any class). Each new level already contains at least one SpawnSphere, which is represented by a green octahedron in stock Torque 3D. The spawnClass field determines the object type, such as Player, AIPlayer, etc. The spawnDataBlock field applies the pre-defined datablock to each spawned object instance. The really powerful feature of this class is provided by the spawnScript field which allows you to define a simple script (multiple lines) that will be executed once the object has been spawned.
57405
57406@tsexample
57407// Define an SpawnSphere that essentially performs the following each time an object is spawned
57408//$SpawnObject = new Player()
57409//{
57410//   dataBlock = "DefaultPlayerData";
57411//   name = "Bob";
57412//   lifeTotal = 3;
57413//};
57414//echo("Spawned a Player: " @ $SpawnObject);
57415
57416new SpawnSphere(DefaultSpawnSphere)
57417{
57418   spawnClass = "Player";
57419   spawnDatablock = "DefaultPlayerData";
57420   spawnScript = "echo(\"Spawned a Player: \" @ $SpawnObject);"; // embedded quotes must be escaped with \ 
57421   spawnProperties = "name = \"Bob\";lifeTotal = 3;"; // embedded quotes must be escaped with \ 
57422   autoSpawn = "1";
57423   dataBlock = "SpawnSphereMarker";
57424   position = "-0.77266 -19.882 17.8153";
57425   rotation = "1 0 0 0";
57426   scale = "1 1 1";
57427   canSave = "1";
57428   canSaveDynamicFields = "1";
57429};
57430
57431// Because autoSpawn is set to true in the above example, the following lines
57432// of code will execute AFTER the Player object has been spawned.
57433echo("Object Spawned");
57434echo("Hello World");
57435
57436@endtsexample
57437
57438@see MissionMarker
57439
57440@see MissionMarkerData
57441
57442@ingroup gameObjects
57443@ingroup enviroMisc
57444
57445*/
57446class SpawnSphere : public MissionMarker {
57447public:
57448/*!
57449@brief Dynamically create a new game object with a specified class, datablock, and optional properties.
57450
57451This is called on the actual SpawnSphere, not to be confused with the Sim::spawnObject() global function
57452
57453@param additionalProps Optional set of semiconlon delimited parameters applied to the spawn object during creation.
57454
57455@tsexample
57456// Use the SpawnSphere::spawnObject function to create a game object
57457// No additional properties assigned
57458%player = DefaultSpawnSphere.spawnObject();
57459
57460@endtsexample
57461
57462*/
57463
57464bool spawnObject(string additionalProps);
57465
57466/*! @name Callbacks
57467@{ */
57468/*!
57469@brief Called when the SpawnSphere is being created.
57470
57471@param objectId The unique SimObjectId generated when SpawnSphere is created (%%this in script)
57472*/
57473void onAdd( uint objectId );
57474/// @}
57475
57476/*!
57477@brief Disables rendering of all instances of this type.
57478
57479
57480@ingroup UNDOCUMENTED
57481*/
57482static bool isRenderable;
57483/*!
57484@brief Disables selection of all instances of this type.
57485
57486
57487@ingroup UNDOCUMENTED
57488*/
57489static bool isSelectable;
57490
57491/*! @name Spawn
57492@{ */
57493/*!
57494@brief Object class to create (eg. Player, AIPlayer, Debris etc)
57495*/
57496string spawnClass;
57497/*!
57498@brief Predefined datablock assigned to the object when created
57499*/
57500string spawnDatablock;
57501/*!
57502@brief String containing semicolon (;) delimited properties to set when the object is created.
57503*/
57504string spawnProperties;
57505/*!
57506@brief Command to execute immediately after spawning an object. New object id is stored in $SpawnObject.  Max 255 characters.
57507*/
57508string spawnScript;
57509/*!
57510@brief Flag to spawn object as soon as SpawnSphere is created, true to enable or false to disable.
57511*/
57512bool autoSpawn;
57513/*!
57514@brief Flag to set the spawned object's transform to the SpawnSphere's transform.
57515*/
57516bool spawnTransform;
57517/// @}
57518
57519
57520/*! @name Dimensions
57521@{ */
57522/*!
57523@brief Deprecated
57524*/
57525float radius;
57526/// @}
57527
57528
57529/*! @name Weight
57530@{ */
57531/*!
57532@brief Deprecated
57533*/
57534float sphereWeight;
57535/*!
57536@brief Deprecated
57537*/
57538float indoorWeight;
57539/*!
57540@brief Deprecated
57541*/
57542float outdoorWeight;
57543/// @}
57544
57545
57546/*! @name Game
57547@{ */
57548/// @}
57549
57550
57551/*! @name GameObject
57552@{ */
57553/// @}
57554
57555
57556/*! @name Transform
57557@{ */
57558/// @}
57559
57560
57561/*! @name Editing
57562@{ */
57563/// @}
57564
57565
57566/*! @name Mounting
57567@{ */
57568/// @}
57569
57570
57571/*! @name Ungrouped
57572@{ */
57573/// @}
57574
57575
57576/*! @name Object
57577@{ */
57578/// @}
57579
57580
57581/*! @name Editing
57582@{ */
57583/// @}
57584
57585
57586/*! @name Persistence
57587@{ */
57588/// @}
57589
57590};
57591
57592/*!
57593@brief A camera that moves along a path. The camera can then be made to travel along this path forwards or backwards.
57594
57595A camera's path is made up of knots, which define a position, rotation and speed for the camera.  Traversal from one knot to another may be either linear or using a Catmull-Rom spline.  If the knot is part of a spline, then it may be a normal knot or defined as a kink.  Kinked knots are a hard transition on the spline rather than a smooth one.  A knot may also be defined as a position only.  In this case the knot is treated as a normal knot but is ignored when determining how to smoothly rotate the camera while it is travelling along the path (the algorithm moves on to the next knot in the path for determining rotation).
57596
57597The datablock field for a PathCamera is a previously created PathCameraData, which acts as the interface between the script and the engine for this PathCamera object.
57598
57599@see PathCameraData
57600@tsexample
57601%newPathCamera = new PathCamera()
57602{
57603  dataBlock = LoopingCam;
57604  position = "0 0 300 1 0 0 0";
57605};
57606@endtsexample
57607@ingroup PathCameras
57608
57609*/
57610class PathCamera : public ShapeBase {
57611public:
57612/*!
57613@brief Set the current position of the camera along the path.
57614
57615@param position Position along the path, from 0.0 (path start) - 1.0 (path end), to place the camera.
57616@tsexample
57617// Set the camera on a position along its path from 0.0 - 1.0.
57618%position = "0.35";
57619
57620// Force the pathCamera to its new position along the path.
57621%pathCamera.setPosition(%position);
57622@endtsexample
57623*/
57624void setPosition( float position=0.0f );
57625/*!
57626@brief Set the movement target for this camera along its path.
57627
57628The camera will attempt to move along the path to the given target in the direction provided by setState() (the default is forwards).  Once the camera moves past this target it will come to a stop, and the target state will be cleared.
57629@param position Target position, between 0.0 (path start) and 1.0 (path end), for the camera to move to along its path.
57630@tsexample
57631// Set the position target, between 0.0 (path start) and 1.0 (path end), for this camera to move to.
57632%position = "0.50";
57633
57634// Inform the pathCamera of the new target position it will move to.
57635%pathCamera.setTarget(%position);
57636@endtsexample*/
57637void setTarget( float position=1.0f );
57638/*!
57639@brief Set the movement state for this path camera.
57640
57641@param newState New movement state type for this camera. Forward, Backward or Stop.
57642@tsexample
57643// Set the state type (forward, backward, stop).
57644// In this example, the camera will travel from the first node
57645// to the last node (or target if given with setTarget())
57646%state = "forward";
57647
57648// Inform the pathCamera to change its movement state to the defined value.
57649%pathCamera.setState(%state);
57650@endtsexample
57651*/
57652void setState( string newState="forward" );
57653/*!
57654@brief Clear the camera's path and set the camera's current transform as the start of the new path.
57655
57656What specifically occurs is a new knot is created from the camera's current transform.  Then the current path is cleared and the new knot is pushed onto the path.  Any previous target is cleared and the camera's movement state is set to Forward.  The camera is now ready for a new path to be defined.
57657@param speed Speed for the camera to move along its path after being reset.
57658@tsexample
57659//Determine the new movement speed of this camera. If not set, the speed will default to 1.0.
57660%speed = "0.50";
57661
57662// Inform the path camera to start a new path at// the camera's current position, and set the new // path's speed value.
57663%pathCamera.reset(%speed);
57664@endtsexample*/
57665void reset( float speed=1.0f );
57666/*!
57667@brief Adds a new knot to the back of a path camera's path.
57668@param transform Transform for the new knot.  In the form of "x y z ax ay az aa" such as returned by SceneObject::getTransform()
57669@param speed Speed setting for this knot.
57670@param type Knot type (Normal, Position Only, Kink).
57671@param path %Path type (Linear, Spline).
57672@tsexample
57673// Transform vector for new knot. (Pos_X Pos_Y Pos_Z Rot_X Rot_Y Rot_Z Angle)
57674%transform = "15.0 5.0 5.0 1.4 1.0 0.2 1.0"
57675
57676// Speed setting for knot.
57677%speed = "1.0"
57678
57679// Knot type. (Normal, Position Only, Kink)
57680%type = "Normal";
57681
57682// Path Type. (Linear, Spline)
57683%path = "Linear";
57684
57685// Inform the path camera to add a new knot to the back of its path
57686%pathCamera.pushBack(%transform,%speed,%type,%path);
57687@endtsexample*/
57688void pushBack( TransformF transform, float speed=1.0f, string type="Normal", string path="Linear" );
57689/*!
57690@brief Adds a new knot to the front of a path camera's path.
57691@param transform Transform for the new knot. In the form of "x y z ax ay az aa" such as returned by SceneObject::getTransform()
57692@param speed Speed setting for this knot.
57693@param type Knot type (Normal, Position Only, Kink).
57694@param path %Path type (Linear, Spline).
57695@tsexample
57696// Transform vector for new knot. (Pos_X,Pos_Y,Pos_Z,Rot_X,Rot_Y,Rot_Z,Angle)
57697%transform = "15.0 5.0 5.0 1.4 1.0 0.2 1.0"
57698
57699// Speed setting for knot.
57700%speed = "1.0";
57701
57702// Knot type. (Normal, Position Only, Kink)
57703%type = "Normal";
57704
57705// Path Type. (Linear, Spline)
57706%path = "Linear";
57707
57708// Inform the path camera to add a new knot to the front of its path
57709%pathCamera.pushFront(%transform, %speed, %type, %path);
57710@endtsexample*/
57711void pushFront( TransformF transform, float speed=1.0f, string type="Normal", string path="Linear" );
57712/*!
57713@brief Removes the knot at the front of the camera's path.
57714
57715@tsexample
57716// Remove the first knot in the camera's path.
57717%pathCamera.popFront();
57718@endtsexample
57719*/
57720void popFront();
57721
57722/*! @name Callbacks
57723@{ */
57724/*!
57725@brief A script callback that indicates the path camera has arrived at a specific node in its path.  Server side only.
57726
57727@param Node Unique ID assigned to this node.
57728*/
57729void onNode( int node );
57730/// @}
57731
57732/*!
57733@brief Disables rendering of all instances of this type.
57734
57735
57736@ingroup UNDOCUMENTED
57737*/
57738static bool isRenderable;
57739/*!
57740@brief Disables selection of all instances of this type.
57741
57742
57743@ingroup UNDOCUMENTED
57744*/
57745static bool isSelectable;
57746
57747/*! @name Game
57748@{ */
57749/// @}
57750
57751
57752/*! @name GameObject
57753@{ */
57754/// @}
57755
57756
57757/*! @name Transform
57758@{ */
57759/// @}
57760
57761
57762/*! @name Editing
57763@{ */
57764/// @}
57765
57766
57767/*! @name Mounting
57768@{ */
57769/// @}
57770
57771
57772/*! @name Ungrouped
57773@{ */
57774/// @}
57775
57776
57777/*! @name Object
57778@{ */
57779/// @}
57780
57781
57782/*! @name Editing
57783@{ */
57784/// @}
57785
57786
57787/*! @name Persistence
57788@{ */
57789/// @}
57790
57791};
57792
57793/*! UNDOCUMENTED!
57794@ingroup UNDOCUMENTED
57795 */
57796class PathShape : public StaticShape {
57797public:
57798/*!
57799@brief Set the current position of the camera along the path.
57800
57801@param position Position along the path, from 0.0 (path start) - 1.0 (path end), to place the camera.
57802@tsexample
57803// Set the camera on a position along its path from 0.0 - 1.0.
57804%position = "0.35";
57805
57806// Force the pathCamera to its new position along the path.
57807%pathCamera.setPosition(%position);
57808@endtsexample
57809*/
57810void setPosition( float position=0.0f );
57811/*!
57812@brief Set the movement target for this camera along its path.
57813
57814The camera will attempt to move along the path to the given target in the direction provided by setState() (the default is forwards).  Once the camera moves past this target it will come to a stop, and the target state will be cleared.
57815@param position Target position, between 0.0 (path start) and 1.0 (path end), for the camera to move to along its path.
57816@tsexample
57817// Set the position target, between 0.0 (path start) and 1.0 (path end), for this camera to move to.
57818%position = "0.50";
57819
57820// Inform the pathCamera of the new target position it will move to.
57821%pathCamera.setTarget(%position);
57822@endtsexample*/
57823void setTarget( float position=1.0f );
57824/*!
57825@brief Set the movement state for this path camera.
57826
57827@param newState New movement state type for this camera. Forward, Backward or Stop.
57828@tsexample
57829// Set the state type (forward, backward, stop).
57830// In this example, the camera will travel from the first node
57831// to the last node (or target if given with setTarget())
57832%state = "forward";
57833
57834// Inform the pathCamera to change its movement state to the defined value.
57835%pathCamera.setState(%state);
57836@endtsexample
57837*/
57838void setState( string newState="forward" );
57839/*!
57840@brief Clear the camera's path and set the camera's current transform as the start of the new path.
57841
57842What specifically occurs is a new knot is created from the camera's current transform.  Then the current path is cleared and the new knot is pushed onto the path.  Any previous target is cleared and the camera's movement state is set to Forward.  The camera is now ready for a new path to be defined.
57843@param speed Speed for the camera to move along its path after being reset.
57844@tsexample
57845//Determine the new movement speed of this camera. If not set, the speed will default to 1.0.
57846%speed = "0.50";
57847
57848// Inform the path camera to start a new path at// the camera's current position, and set the new // path's speed value.
57849%pathCamera.reset(%speed);
57850@endtsexample*/
57851void reset( float speed=1.0f );
57852/*!
57853@brief Adds a new knot to the back of a path camera's path.
57854@param transform Transform for the new knot.  In the form of "x y z ax ay az aa" such as returned by SceneObject::getTransform()
57855@param speed Speed setting for this knot.
57856@param type Knot type (Normal, Position Only, Kink).
57857@param path %Path type (Linear, Spline).
57858@tsexample
57859// Transform vector for new knot. (Pos_X Pos_Y Pos_Z Rot_X Rot_Y Rot_Z Angle)
57860%transform = "15.0 5.0 5.0 1.4 1.0 0.2 1.0"
57861
57862// Speed setting for knot.
57863%speed = "1.0"
57864
57865// Knot type. (Normal, Position Only, Kink)
57866%type = "Normal";
57867
57868// Path Type. (Linear, Spline)
57869%path = "Linear";
57870
57871// Inform the path camera to add a new knot to the back of its path
57872%pathCamera.pushBack(%transform,%speed,%type,%path);
57873@endtsexample*/
57874void pushBack( TransformF transform=TransformF::Identity, float speed=1.0f, string type="Normal", string path="Linear" );
57875/*!
57876@brief Adds a new knot to the front of a path camera's path.
57877@param transform Transform for the new knot. In the form of "x y z ax ay az aa" such as returned by SceneObject::getTransform()
57878@param speed Speed setting for this knot.
57879@param type Knot type (Normal, Position Only, Kink).
57880@param path %Path type (Linear, Spline).
57881@tsexample
57882// Transform vector for new knot. (Pos_X,Pos_Y,Pos_Z,Rot_X,Rot_Y,Rot_Z,Angle)
57883%transform = "15.0 5.0 5.0 1.4 1.0 0.2 1.0"
57884
57885// Speed setting for knot.
57886%speed = "1.0";
57887
57888// Knot type. (Normal, Position Only, Kink)
57889%type = "Normal";
57890
57891// Path Type. (Linear, Spline)
57892%path = "Linear";
57893
57894// Inform the path camera to add a new knot to the front of its path
57895%pathCamera.pushFront(%transform, %speed, %type, %path);
57896@endtsexample*/
57897void pushFront( TransformF transform, float speed=1.0f, string type="Normal", string path="Linear" );
57898/*!
57899@brief Removes the knot at the front of the camera's path.
57900
57901@tsexample
57902// Remove the first knot in the camera's path.
57903%pathCamera.popFront();
57904@endtsexample
57905*/
57906void popFront();
57907/*!
57908@brief PathShape.getState()
57909
57910*/
57911int getState();
57912
57913/*! @name Callbacks
57914@{ */
57915/// @}
57916
57917/*!
57918@brief Disables rendering of all instances of this type.
57919
57920
57921@ingroup UNDOCUMENTED
57922*/
57923static bool isRenderable;
57924/*!
57925@brief Disables selection of all instances of this type.
57926
57927
57928@ingroup UNDOCUMENTED
57929*/
57930static bool isSelectable;
57931/*!
57932@brief @brief Name of a Path to follow.
57933*/
57934Path Path;
57935/*!
57936@brief controlers
57937*/
57938string Controler[ 4 ];
57939
57940/*! @name Game
57941@{ */
57942/// @}
57943
57944
57945/*! @name GameObject
57946@{ */
57947/// @}
57948
57949
57950/*! @name Transform
57951@{ */
57952/// @}
57953
57954
57955/*! @name Editing
57956@{ */
57957/// @}
57958
57959
57960/*! @name Mounting
57961@{ */
57962/// @}
57963
57964
57965/*! @name Ungrouped
57966@{ */
57967/// @}
57968
57969
57970/*! @name Object
57971@{ */
57972/// @}
57973
57974
57975/*! @name Editing
57976@{ */
57977/// @}
57978
57979
57980/*! @name Persistence
57981@{ */
57982/// @}
57983
57984};
57985
57986/*!
57987@brief Physical Zones are areas that modify the player's gravity and/or velocity and/or applied force.
57988
57989The datablock properties determine how the physics, velocity and applied forces affect a player who enters this zone.
57990@tsexample
57991new PhysicalZone(Team1JumpPad) {
57992velocityMod = "1";gravityMod = "0";
57993appliedForce = "0 0 20000";
57994polyhedron = "0.0000000 0.0000000 0.0000000 1.0000000 0.0000000 0.0000000 0.0000000 -1.0000000 0.0000000 0.0000000 0.0000000 1.0000000";
57995position = "273.559 -166.371 249.856";
57996rotation = "0 0 1 13.0216";
57997scale = "8 4.95 28.31";
57998isRenderEnabled = "true";
57999canSaveDynamicFields = "1";
58000enabled = "1";
58001};
58002@endtsexample
58003
58004@ingroup enviroMisc
58005
58006*/
58007class PhysicalZone : public SceneObject {
58008public:
58009/*!
58010@brief Activate the physical zone's effects.
58011
58012@tsexample
58013// Activate effects for a specific physical zone.
58014%thisPhysicalZone.activate();
58015@endtsexample
58016@ingroup Datablocks
58017*/
58018void activate();
58019/*!
58020@brief Deactivate the physical zone's effects.
58021
58022@tsexample
58023// Deactivate effects for a specific physical zone.
58024%thisPhysicalZone.deactivate();
58025@endtsexample
58026@ingroup Datablocks
58027*/
58028void deactivate();
58029
58030/*! @name Callbacks
58031@{ */
58032/// @}
58033
58034/*!
58035@brief If true, a box will render around the location of all PhysicalZones.
58036
58037@ingroup EnviroMisc
58038*/
58039static bool renderZones;
58040/*!
58041@brief Disables rendering of all instances of this type.
58042
58043
58044@ingroup UNDOCUMENTED
58045*/
58046static bool isRenderable;
58047/*!
58048@brief Disables selection of all instances of this type.
58049
58050
58051@ingroup UNDOCUMENTED
58052*/
58053static bool isSelectable;
58054
58055/*! @name Misc
58056@{ */
58057/*!
58058@brief Multiply velocity of objects entering zone by this value every tick.
58059*/
58060float velocityMod;
58061/*!
58062@brief Gravity in PhysicalZone. Multiplies against standard gravity.
58063*/
58064float gravityMod;
58065/*!
58066@brief Three-element floating point value representing forces in three axes to apply to objects entering PhysicalZone.
58067*/
58068Point3F appliedForce;
58069/*!
58070@brief The polyhedron type is really a quadrilateral and consists of a cornerpoint followed by three vectors representing the edges extending from the corner.
58071*/
58072floatList polyhedron;
58073/// @}
58074
58075
58076/*! @name AFX
58077@{ */
58078/*!
58079*/
58080PhysicalZone_ForceType forceType;
58081/*!
58082*/
58083bool orientForce;
58084/// @}
58085
58086
58087/*! @name GameObject
58088@{ */
58089/// @}
58090
58091
58092/*! @name Transform
58093@{ */
58094/// @}
58095
58096
58097/*! @name Editing
58098@{ */
58099/// @}
58100
58101
58102/*! @name Mounting
58103@{ */
58104/// @}
58105
58106
58107/*! @name Ungrouped
58108@{ */
58109/// @}
58110
58111
58112/*! @name Object
58113@{ */
58114/// @}
58115
58116
58117/*! @name Editing
58118@{ */
58119/// @}
58120
58121
58122/*! @name Persistence
58123@{ */
58124/// @}
58125
58126};
58127
58128/*!
58129@brief Defines properties for a Player object.
58130
58131@see Player
58132@ingroup gameObjects
58133
58134*/
58135class PlayerData : public ShapeBaseData {
58136public:
58137
58138/*! @name Callbacks
58139@{ */
58140/*!
58141@brief Called when the player changes poses.
58142
58143@param obj The Player object
58144@param oldPose The pose the player is switching from.
58145@param newPose The pose the player is switching to.*/
58146void onPoseChange( Player obj, string oldPose, string newPose );
58147/*!
58148@brief Called when the player starts swimming.
58149
58150@param obj The Player object*/
58151void onStartSwim( Player obj );
58152/*!
58153@brief Called when the player stops swimming.
58154
58155@param obj The Player object*/
58156void onStopSwim( Player obj );
58157/*!
58158@brief Called when the player starts moving while in a Sprint pose.
58159
58160@param obj The Player object*/
58161void onStartSprintMotion( Player obj );
58162/*!
58163@brief Called when the player stops moving while in a Sprint pose.
58164
58165@param obj The Player object*/
58166void onStopSprintMotion( Player obj );
58167/*!
58168@brief Called when attempting to dismount the player from a vehicle.
58169
58170It is up to the doDismount() method to actually perform the dismount.  Often there are some conditions that prevent this, such as the vehicle moving too fast.
58171@param obj The Player object*/
58172void doDismount( Player obj );
58173/*!
58174@brief Called when the player enters a liquid.
58175
58176@param obj The Player object
58177@param coverage Percentage of the player's bounding box covered by the liquid
58178@param type The type of liquid the player has entered*/
58179void onEnterLiquid( Player obj, float coverage, string type );
58180/*!
58181@brief Called when the player leaves a liquid.
58182
58183@param obj The Player object
58184@param type The type of liquid the player has left*/
58185void onLeaveLiquid( Player obj, string type );
58186/*!
58187@brief Called on the server when a scripted animation completes.
58188
58189@param obj The Player object
58190@see Player::setActionThread() for setting a scripted animation and its 'hold' parameter to determine if this callback is used.*/
58191void animationDone( Player obj );
58192/*!
58193@brief Called when the player enters the mission area.
58194
58195@param obj The Player object
58196@see MissionArea*/
58197void onEnterMissionArea( Player obj );
58198/*!
58199@brief Called when the player leaves the mission area.
58200@param obj The Player object
58201@see MissionArea*/
58202void onLeaveMissionArea( Player obj );
58203/// @}
58204
58205/*!
58206@brief @brief Radius around the player to collide with Items in the scene (on server).
58207
58208
58209Internally the pickupRadius is added to the larger side of the initial bounding box to determine the actual distance, to a maximum of 2 times the bounding box size.  The initial bounding box is that used for the root pose, and therefore doesn't take into account the change in pose.
58210
58211*/
58212float pickupRadius;
58213/*!
58214@brief @brief Maximum time scale for action animations.
58215
58216
58217If an action animation has a defined ground frame, it is automatically scaled to match the player's ground velocity.  This field limits the maximum time scale used even if the player's velocity exceeds it.
58218*/
58219float maxTimeScale;
58220
58221/*! @name Camera
58222@{ */
58223/*!
58224@brief @brief Flag controlling whether to render the player shape in first person view.
58225
58226
58227
58228*/
58229bool renderFirstPerson;
58230/*!
58231@brief @brief Forces shadows to be rendered in first person when renderFirstPerson is disabled.  Defaults to false.
58232
58233
58234
58235*/
58236bool firstPersonShadows;
58237/*!
58238@brief @brief Lowest angle (in radians) the player can look.
58239
58240
58241@note An angle of zero is straight ahead, with positive up and negative down.
58242*/
58243float minLookAngle;
58244/*!
58245@brief @brief Highest angle (in radians) the player can look.
58246
58247
58248@note An angle of zero is straight ahead, with positive up and negative down.
58249*/
58250float maxLookAngle;
58251/*!
58252@brief @brief Defines the maximum left and right angles (in radians) the player can look in freelook mode.
58253
58254
58255
58256*/
58257float maxFreelookAngle;
58258/// @}
58259
58260
58261/*! @name Movement
58262@{ */
58263/*!
58264@brief @brief Maximum height the player can step up.
58265
58266
58267The player will automatically step onto changes in ground height less than maxStepHeight.  The player will collide with ground height changes greater than this.
58268*/
58269float MaxStepHeight;
58270/*!
58271@brief @brief Force used to accelerate the player when running.
58272
58273
58274
58275*/
58276float runForce;
58277/*!
58278@brief @brief Energy value drained each tick that the player is moving.
58279
58280
58281The player will not be able to move when his energy falls below minRunEnergy.
58282@note Setting this to zero will disable any energy drain.
58283@see minRunEnergy
58284
58285*/
58286float runEnergyDrain;
58287/*!
58288@brief @brief Minimum energy level required to run or swim.
58289
58290
58291@see runEnergyDrain
58292
58293*/
58294float minRunEnergy;
58295/*!
58296@brief @brief Maximum forward speed when running.
58297*/
58298float maxForwardSpeed;
58299/*!
58300@brief @brief Maximum backward speed when running.
58301*/
58302float maxBackwardSpeed;
58303/*!
58304@brief @brief Maximum sideways speed when running.
58305*/
58306float maxSideSpeed;
58307/*!
58308@brief @brief Maximum angle from vertical (in degrees) the player can run up.
58309
58310
58311
58312*/
58313float runSurfaceAngle;
58314/*!
58315@brief @brief Minimum impact speed to apply falling damage.
58316
58317
58318This field also sets the minimum speed for the onImpact callback to be invoked.
58319@see ShapeBaseData::onImpact()
58320
58321*/
58322float minImpactSpeed;
58323/*!
58324@brief @brief Minimum impact speed to apply non-falling damage.
58325
58326
58327This field also sets the minimum speed for the onLateralImpact callback to be invoked.
58328@see ShapeBaseData::onLateralImpact()
58329
58330*/
58331float minLateralImpactSpeed;
58332/*!
58333@brief @brief Maximum horizontal speed.
58334
58335
58336@note This limit is only enforced if the player's horizontal speed exceeds horizResistSpeed.
58337@see horizResistSpeed
58338@see horizResistFactor
58339
58340*/
58341float horizMaxSpeed;
58342/*!
58343@brief @brief Horizontal speed at which resistence will take place.
58344
58345
58346@see horizMaxSpeed
58347@see horizResistFactor
58348
58349*/
58350float horizResistSpeed;
58351/*!
58352@brief @brief Factor of resistence once horizResistSpeed has been reached.
58353
58354
58355@see horizMaxSpeed
58356@see horizResistSpeed
58357
58358*/
58359float horizResistFactor;
58360/*!
58361@brief @brief Maximum upwards speed.
58362
58363
58364@note This limit is only enforced if the player's upward speed exceeds upResistSpeed.
58365@see upResistSpeed
58366@see upResistFactor
58367
58368*/
58369float upMaxSpeed;
58370/*!
58371@brief @brief Upwards speed at which resistence will take place.
58372
58373
58374@see upMaxSpeed
58375@see upResistFactor
58376
58377*/
58378float upResistSpeed;
58379/*!
58380@brief @brief Factor of resistence once upResistSpeed has been reached.
58381
58382
58383@see upMaxSpeed
58384@see upResistSpeed
58385
58386*/
58387float upResistFactor;
58388/// @}
58389
58390
58391/*! @name Movement: Jumping
58392@{ */
58393/*!
58394@brief @brief Force used to accelerate the player when a jump is initiated.
58395
58396
58397
58398*/
58399float jumpForce;
58400/*!
58401@brief @brief Energy level drained each time the player jumps.
58402
58403
58404@note Setting this to zero will disable any energy drain
58405@see minJumpEnergy
58406
58407*/
58408float jumpEnergyDrain;
58409/*!
58410@brief @brief Minimum energy level required to jump.
58411
58412
58413@see jumpEnergyDrain
58414
58415*/
58416float minJumpEnergy;
58417/*!
58418@brief @brief Minimum speed needed to jump.
58419
58420
58421If the player's own z velocity is greater than this, then it is used to scale the jump speed, up to maxJumpSpeed.
58422@see maxJumpSpeed
58423
58424*/
58425float minJumpSpeed;
58426/*!
58427@brief @brief Maximum vertical speed before the player can no longer jump.
58428
58429
58430
58431*/
58432float maxJumpSpeed;
58433/*!
58434@brief @brief Angle from vertical (in degrees) where the player can jump.
58435
58436
58437
58438*/
58439float jumpSurfaceAngle;
58440/*!
58441@brief @brief Delay time in number of ticks ticks between jumps.
58442
58443
58444
58445*/
58446int jumpDelay;
58447/*!
58448@brief @brief Amount of movement control the player has when in the air.
58449
58450
58451This is applied as a multiplier to the player's x and y motion.
58452
58453*/
58454float airControl;
58455/*!
58456@brief @brief Controls the direction of the jump impulse.
58457
58458When false, jumps are always in the vertical (+Z) direction. When true jumps are in the direction of the ground normal so long as the player is not directly facing the surface.  If the player is directly facing the surface, then they will jump straight up.
58459
58460*/
58461bool jumpTowardsNormal;
58462/// @}
58463
58464
58465/*! @name Movement: Sprinting
58466@{ */
58467/*!
58468@brief @brief Force used to accelerate the player when sprinting.
58469
58470
58471
58472*/
58473float sprintForce;
58474/*!
58475@brief @brief Energy value drained each tick that the player is sprinting.
58476
58477
58478The player will not be able to move when his energy falls below sprintEnergyDrain.
58479@note Setting this to zero will disable any energy drain.
58480@see minSprintEnergy
58481
58482*/
58483float sprintEnergyDrain;
58484/*!
58485@brief @brief Minimum energy level required to sprint.
58486
58487
58488@see sprintEnergyDrain
58489
58490*/
58491float minSprintEnergy;
58492/*!
58493@brief @brief Maximum forward speed when sprinting.
58494*/
58495float maxSprintForwardSpeed;
58496/*!
58497@brief @brief Maximum backward speed when sprinting.
58498*/
58499float maxSprintBackwardSpeed;
58500/*!
58501@brief @brief Maximum sideways speed when sprinting.
58502*/
58503float maxSprintSideSpeed;
58504/*!
58505@brief @brief Amount to scale strafing motion vector while sprinting.
58506*/
58507float sprintStrafeScale;
58508/*!
58509@brief @brief Amount to scale yaw motion while sprinting.
58510*/
58511float sprintYawScale;
58512/*!
58513@brief @brief Amount to scale pitch motion while sprinting.
58514*/
58515float sprintPitchScale;
58516/*!
58517@brief @brief Can the player jump while sprinting.
58518*/
58519bool sprintCanJump;
58520/// @}
58521
58522
58523/*! @name Movement: Swimming
58524@{ */
58525/*!
58526@brief @brief Force used to accelerate the player when swimming.
58527
58528
58529
58530*/
58531float swimForce;
58532/*!
58533@brief @brief Maximum forward speed when underwater.
58534
58535
58536
58537*/
58538float maxUnderwaterForwardSpeed;
58539/*!
58540@brief @brief Maximum backward speed when underwater.
58541
58542
58543
58544*/
58545float maxUnderwaterBackwardSpeed;
58546/*!
58547@brief @brief Maximum sideways speed when underwater.
58548
58549
58550
58551*/
58552float maxUnderwaterSideSpeed;
58553/// @}
58554
58555
58556/*! @name Movement: Crouching
58557@{ */
58558/*!
58559@brief @brief Force used to accelerate the player when crouching.
58560
58561
58562
58563*/
58564float crouchForce;
58565/*!
58566@brief @brief Maximum forward speed when crouching.
58567
58568
58569
58570*/
58571float maxCrouchForwardSpeed;
58572/*!
58573@brief @brief Maximum backward speed when crouching.
58574
58575
58576
58577*/
58578float maxCrouchBackwardSpeed;
58579/*!
58580@brief @brief Maximum sideways speed when crouching.
58581
58582
58583
58584*/
58585float maxCrouchSideSpeed;
58586/// @}
58587
58588
58589/*! @name Movement: Prone
58590@{ */
58591/*!
58592@brief @brief Force used to accelerate the player when prone (laying down).
58593
58594
58595
58596*/
58597float proneForce;
58598/*!
58599@brief @brief Maximum forward speed when prone (laying down).
58600
58601
58602
58603*/
58604float maxProneForwardSpeed;
58605/*!
58606@brief @brief Maximum backward speed when prone (laying down).
58607
58608
58609
58610*/
58611float maxProneBackwardSpeed;
58612/*!
58613@brief @brief Maximum sideways speed when prone (laying down).
58614
58615
58616
58617*/
58618float maxProneSideSpeed;
58619/// @}
58620
58621
58622/*! @name Movement: Jetting
58623@{ */
58624/*!
58625@brief @brief Force used to accelerate the player when a jet jump is initiated.
58626
58627
58628
58629*/
58630float jetJumpForce;
58631/*!
58632@brief @brief Energy level drained each time the player jet jumps.
58633
58634
58635@note Setting this to zero will disable any energy drain
58636@see jetMinJumpEnergy
58637
58638*/
58639float jetJumpEnergyDrain;
58640/*!
58641@brief @brief Minimum energy level required to jet jump.
58642
58643
58644@see jetJumpEnergyDrain
58645
58646*/
58647float jetMinJumpEnergy;
58648/*!
58649@brief @brief Minimum speed needed to jet jump.
58650
58651
58652If the player's own z velocity is greater than this, then it is used to scale the jet jump speed, up to jetMaxJumpSpeed.
58653@see jetMaxJumpSpeed
58654
58655*/
58656float jetMinJumpSpeed;
58657/*!
58658@brief @brief Maximum vertical speed before the player can no longer jet jump.
58659
58660
58661
58662*/
58663float jetMaxJumpSpeed;
58664/*!
58665@brief @brief Angle from vertical (in degrees) where the player can jet jump.
58666
58667
58668
58669*/
58670float jetJumpSurfaceAngle;
58671/// @}
58672
58673
58674/*! @name Falling
58675@{ */
58676/*!
58677@brief @brief Downward speed at which we consider the player falling.
58678
58679
58680
58681*/
58682float fallingSpeedThreshold;
58683/*!
58684@brief @brief Number of ticks for the player to recover from falling.
58685
58686
58687
58688*/
58689int recoverDelay;
58690/*!
58691@brief @brief Scale factor applied to runForce while in the recover state.
58692
58693
58694This can be used to temporarily slow the player's movement after a fall, or prevent the player from moving at all if set to zero.
58695
58696*/
58697float recoverRunForceScale;
58698/*!
58699@brief @brief Time of land sequence play back when using new recover system.
58700
58701
58702If greater than 0 then the legacy fall recovery system will be bypassed in favour of just playing the player's land sequence.  The time to recover from a fall then becomes this parameter's time and the land sequence's playback will be scaled to match.
58703@see transitionToLand
58704
58705*/
58706float landSequenceTime;
58707/*!
58708@brief @brief When going from a fall to a land, should we transition between the two.
58709
58710
58711@note Only takes affect when landSequenceTime is greater than 0.
58712@see landSequenceTime
58713
58714*/
58715bool transitionToLand;
58716/// @}
58717
58718
58719/*! @name Collision
58720@{ */
58721/*!
58722@brief @brief Size of the bounding box used by the player for collision.
58723
58724
58725Dimensions are given as "width depth height".
58726*/
58727Point3F boundingBox;
58728/*!
58729@brief @brief Collision bounding box used when the player is crouching.
58730
58731
58732@see boundingBox
58733*/
58734Point3F crouchBoundingBox;
58735/*!
58736@brief @brief Collision bounding box used when the player is prone (laying down).
58737
58738
58739@see boundingBox
58740*/
58741Point3F proneBoundingBox;
58742/*!
58743@brief @brief Collision bounding box used when the player is swimming.
58744
58745
58746@see boundingBox
58747*/
58748Point3F swimBoundingBox;
58749/*!
58750@brief @brief Percentage of the player's bounding box height that represents the head.
58751
58752
58753Used when computing the damage location.
58754@see Player::getDamageLocation
58755*/
58756float boxHeadPercentage;
58757/*!
58758@brief @brief Percentage of the player's bounding box height that represents the torso.
58759
58760
58761Used when computing the damage location.
58762@see Player::getDamageLocation
58763*/
58764float boxTorsoPercentage;
58765/*!
58766@brief @brief Percentage of the player's bounding box width that represents the left side of the head.
58767
58768
58769Used when computing the damage location.
58770@see Player::getDamageLocation
58771*/
58772float boxHeadLeftPercentage;
58773/*!
58774@brief @brief Percentage of the player's bounding box width that represents the right side of the head.
58775
58776
58777Used when computing the damage location.
58778@see Player::getDamageLocation
58779*/
58780float boxHeadRightPercentage;
58781/*!
58782@brief @brief Percentage of the player's bounding box depth that represents the back side of the head.
58783
58784
58785Used when computing the damage location.
58786@see Player::getDamageLocation
58787*/
58788float boxHeadBackPercentage;
58789/*!
58790@brief @brief Percentage of the player's bounding box depth that represents the front side of the head.
58791
58792
58793Used when computing the damage location.
58794@see Player::getDamageLocation
58795*/
58796float boxHeadFrontPercentage;
58797/// @}
58798
58799
58800/*! @name Interaction: Footsteps
58801@{ */
58802/*!
58803@brief @brief Particle emitter used to generate footpuffs (particles created as the player walks along the ground).
58804
58805
58806@note The generation of foot puffs requires the appropriate triggeres to be defined in the player's animation sequences.  Without these, no foot puffs will be generated.
58807
58808*/
58809ParticleEmitterData footPuffEmitter;
58810/*!
58811@brief @brief Number of footpuff particles to generate each step.
58812
58813
58814Each foot puff is randomly placed within the defined foot puff radius.  This includes having footPuffNumParts set to one.
58815@see footPuffRadius
58816
58817*/
58818int footPuffNumParts;
58819/*!
58820@brief @brief Particle creation radius for footpuff particles.
58821
58822
58823This is applied to each foot puff particle, even if footPuffNumParts is set to one.  So set this value to zero if you want a single foot puff placed at exactly the same location under the player each time.
58824
58825*/
58826float footPuffRadius;
58827/*!
58828@brief @brief Emitter used to generate dust particles.
58829
58830
58831@note Currently unused.
58832*/
58833ParticleEmitterData dustEmitter;
58834/*!
58835@brief @brief Decal to place on the ground for player footsteps.
58836
58837
58838
58839*/
58840DecalData DecalData;
58841/*!
58842@brief @brief Distance from the center of the model to the right foot.
58843
58844
58845While this defines the distance to the right foot, it is also used to place the left foot decal as well.  Just on the opposite side of the player.
58846*/
58847float decalOffset;
58848/// @}
58849
58850
58851/*! @name Interaction: Sounds
58852@{ */
58853/*!
58854@brief @brief Sound to play when walking on a surface with Material footstepSoundId 0.
58855
58856
58857
58858*/
58859SFXTrack FootSoftSound;
58860/*!
58861@brief @brief Sound to play when walking on a surface with Material footstepSoundId 1.
58862
58863
58864
58865*/
58866SFXTrack FootHardSound;
58867/*!
58868@brief @brief Sound to play when walking on a surface with Material footstepSoundId 2.
58869
58870
58871
58872*/
58873SFXTrack FootMetalSound;
58874/*!
58875@brief @brief Sound to play when walking on a surface with Material footstepSoundId 3.
58876
58877
58878
58879*/
58880SFXTrack FootSnowSound;
58881/*!
58882@brief @brief Sound to play when walking in water and coverage is less than footSplashHeight.
58883
58884
58885@see footSplashHeight
58886
58887*/
58888SFXTrack FootShallowSound;
58889/*!
58890@brief @brief Sound to play when walking in water and coverage is less than 1, but > footSplashHeight.
58891
58892
58893@see footSplashHeight
58894
58895*/
58896SFXTrack FootWadingSound;
58897/*!
58898@brief @brief Sound to play when walking in water and coverage equals 1.0 (fully underwater).
58899
58900
58901
58902*/
58903SFXTrack FootUnderwaterSound;
58904/*!
58905@brief @brief Sound to play when walking in water and coverage equals 1.0 (fully underwater).
58906
58907
58908
58909*/
58910SFXTrack FootBubblesSound;
58911/*!
58912@brief @brief Sound to play when in water and coverage equals 1.0 (fully underwater).
58913
58914
58915Note that unlike FootUnderwaterSound, this sound plays even if the player is not moving around in the water.
58916
58917*/
58918SFXTrack movingBubblesSound;
58919/*!
58920@brief @brief Sound to play when in water and coverage equals 1.0 (fully underwater).
58921
58922
58923Note that unlike FootUnderwaterSound, this sound plays even if the player is not moving around in the water.
58924
58925*/
58926SFXTrack waterBreathSound;
58927/*!
58928@brief @brief Sound to play after falling on a surface with Material footstepSoundId 0.
58929
58930
58931
58932*/
58933SFXTrack impactSoftSound;
58934/*!
58935@brief @brief Sound to play after falling on a surface with Material footstepSoundId 1.
58936
58937
58938
58939*/
58940SFXTrack impactHardSound;
58941/*!
58942@brief @brief Sound to play after falling on a surface with Material footstepSoundId 2.
58943
58944
58945
58946*/
58947SFXTrack impactMetalSound;
58948/*!
58949@brief @brief Sound to play after falling on a surface with Material footstepSoundId 3.
58950
58951
58952
58953*/
58954SFXTrack impactSnowSound;
58955/*!
58956@brief @brief Sound to play when entering the water with velocity < mediumSplashSoundVelocity.
58957
58958
58959@see mediumSplashSoundVelocity
58960
58961*/
58962SFXTrack impactWaterEasy;
58963/*!
58964@brief @brief Sound to play when entering the water with velocity >= mediumSplashSoundVelocity and < hardSplashSoundVelocity.
58965
58966
58967@see mediumSplashSoundVelocity
58968@see hardSplashSoundVelocity
58969
58970*/
58971SFXTrack impactWaterMedium;
58972/*!
58973@brief @brief Sound to play when entering the water with velocity >= hardSplashSoundVelocity.
58974
58975
58976@see hardSplashSoundVelocity
58977
58978*/
58979SFXTrack impactWaterHard;
58980/*!
58981@brief @brief Sound to play when exiting the water with velocity >= exitSplashSoundVelocity.
58982
58983
58984@see exitSplashSoundVelocity
58985
58986*/
58987SFXTrack exitingWater;
58988/// @}
58989
58990
58991/*! @name Interaction: Splashes
58992@{ */
58993/*!
58994@brief @brief SplashData datablock used to create splashes when the player moves through water.
58995
58996
58997
58998*/
58999SplashData Splash;
59000/*!
59001@brief @brief Minimum velocity when moving through water to generate splashes.
59002
59003
59004
59005*/
59006float splashVelocity;
59007/*!
59008@brief @brief Maximum angle (in degrees) from pure vertical movement in water to generate splashes.
59009
59010
59011
59012*/
59013float splashAngle;
59014/*!
59015@brief @brief Multipled by speed to determine the number of splash particles to generate.
59016
59017
59018
59019*/
59020float splashFreqMod;
59021/*!
59022@brief @brief Minimum speed to generate splash particles.
59023
59024
59025
59026*/
59027float splashVelEpsilon;
59028/*!
59029@brief @brief Time in seconds to generate bubble particles after entering the water.
59030
59031
59032
59033*/
59034float bubbleEmitTime;
59035/*!
59036@brief @brief Particle emitters used to generate splash particles.
59037
59038
59039
59040*/
59041ParticleEmitterData splashEmitter[ 3 ];
59042/*!
59043@brief @brief Water coverage level to choose between FootShallowSound and FootWadingSound.
59044
59045
59046@see FootShallowSound
59047@see FootWadingSound
59048
59049*/
59050float footstepSplashHeight;
59051/*!
59052@brief @brief Minimum velocity when entering the water for choosing between the impactWaterEasy and impactWaterMedium sounds to play.
59053
59054
59055@see impactWaterEasy
59056@see impactWaterMedium
59057
59058*/
59059float mediumSplashSoundVelocity;
59060/*!
59061@brief @brief Minimum velocity when entering the water for choosing between the impactWaterMedium and impactWaterHard sound to play.
59062
59063
59064@see impactWaterMedium
59065@see impactWaterHard
59066
59067*/
59068float hardSplashSoundVelocity;
59069/*!
59070@brief @brief Minimum velocity when leaving the water for the exitingWater sound to play.
59071
59072
59073@see exitingWater
59074*/
59075float exitSplashSoundVelocity;
59076/// @}
59077
59078
59079/*! @name Interaction: Ground Impact
59080@{ */
59081/*!
59082@brief @brief Minimum falling impact speed to apply damage and initiate the camera shaking effect.
59083
59084
59085
59086*/
59087float groundImpactMinSpeed;
59088/*!
59089@brief @brief Frequency of the camera shake effect after falling.
59090
59091
59092This is how fast to shake the camera.
59093
59094*/
59095Point3F groundImpactShakeFreq;
59096/*!
59097@brief @brief Amplitude of the camera shake effect after falling.
59098
59099
59100This is how much to shake the camera.
59101
59102*/
59103Point3F groundImpactShakeAmp;
59104/*!
59105@brief @brief Duration (in seconds) of the camera shake effect after falling.
59106
59107
59108This is how long to shake the camera.
59109
59110*/
59111float groundImpactShakeDuration;
59112/*!
59113@brief @brief Falloff factor of the camera shake effect after falling.
59114
59115
59116This is how to fade the camera shake over the duration.
59117
59118*/
59119float groundImpactShakeFalloff;
59120/// @}
59121
59122
59123/*! @name Physics
59124@{ */
59125/*!
59126@brief @brief Specifies the type of physics used by the player.
59127
59128
59129This depends on the physics module used.  An example is 'Capsule'.
59130@note Not current used.
59131
59132*/
59133string physicsPlayerType;
59134/// @}
59135
59136
59137/*! @name First Person Arms
59138@{ */
59139/*!
59140@brief @brief Optional prefix to all mounted image animation sequences in first person.
59141
59142
59143This defines a prefix that will be added when looking up mounted image animation sequences while in first person.  It allows for the customization of a first person image based on the type of player.
59144
59145*/
59146caseString imageAnimPrefixFP;
59147/*!
59148@brief @brief File name of this player's shape that will be used in conjunction with the corresponding mounted image.
59149
59150
59151These optional parameters correspond to each mounted image slot to indicate a shape that is rendered in addition to the mounted image shape.  Typically these are a player's arms (or arm) that is animated along with the mounted image's state animation sequences.
59152
59153*/
59154filename shapeNameFP[ 4 ];
59155/// @}
59156
59157
59158/*! @name Third Person
59159@{ */
59160/*!
59161@brief @brief Optional prefix to all mounted image animation sequences in third person.
59162
59163
59164This defines a prefix that will be added when looking up mounted image animation sequences while in third person.  It allows for the customization of a third person image based on the type of player.
59165
59166*/
59167caseString imageAnimPrefix;
59168/*!
59169@brief @brief Allow mounted images to request a sequence be played on the Player.
59170
59171
59172When true a new thread is added to the player to allow for mounted images to request a sequence be played on the player through the image's state machine.  It is only optional so that we don't create a TSThread on the player if we don't need to.
59173
59174*/
59175bool allowImageStateAnimation;
59176/// @}
59177
59178
59179/*! @name Shadows
59180@{ */
59181/// @}
59182
59183
59184/*! @name Render
59185@{ */
59186/// @}
59187
59188
59189/*! @name Destruction
59190Parameters related to the destruction effects of this object.
59191@{ */
59192/// @}
59193
59194
59195/*! @name Physics
59196@{ */
59197/// @}
59198
59199
59200/*! @name Damage/Energy
59201@{ */
59202/// @}
59203
59204
59205/*! @name Camera
59206The settings used by the shape when it is the camera.
59207@{ */
59208/// @}
59209
59210
59211/*! @name Misc
59212@{ */
59213/// @}
59214
59215
59216/*! @name Reflection
59217@{ */
59218/// @}
59219
59220
59221/*! @name Scripting
59222@{ */
59223/// @}
59224
59225
59226/*! @name Ungrouped
59227@{ */
59228/// @}
59229
59230
59231/*! @name Object
59232@{ */
59233/// @}
59234
59235
59236/*! @name Editing
59237@{ */
59238/// @}
59239
59240
59241/*! @name Persistence
59242@{ */
59243/// @}
59244
59245};
59246
59247/*!
59248@brief An object that represents an interior space.
59249
59250A zone is an invisible volume that encloses an interior space.  All objects that have their world space axis-aligned bounding boxes (AABBs) intersect the zone's volume are assigned to the zone.  This assignment happens automatically as objects are placed and transformed.  Also, assignment is not exclusive meaning that an object can be assigned to many zones at the same time if it intersects all of them.
59251
59252In itself, the volume of a zone is fully sealed off from the outside.  This means that while viewing the scene from inside the volume, only objects assigned to the zone are rendered while when viewing the scene from outside the volume, objects <em>exclusively</em> only assigned the zone are not rendered.
59253
59254Usually, you will want to connect zones to each other by means of portals.  A portal overlapping with a zone 
59255
59256@tsexample
59257// Example declaration of a Zone.  This creates a box-shaped zone.
59258new Zone( TestZone )
59259{
59260   position = "3.61793 -1.01945 14.7442";
59261   rotation = "1 0 0 0";
59262   scale = "10 10 10";
59263};
59264@endtsexample
59265
59266@section Zone_zoneGroups Zone Groups
59267
59268Normally, Zones will not connect to each other when they overlap.  This means that if viewing the scene from one zone, the contents of the other zone will not be visible except when there is a portal connecting the zones.  However, sometimes it is convenient to represent a single interior space through a combination of Zones so that when any of these zones is visible, all other zones that are part of the same interior space are visible.  This is possible by employing "zone groups".
59269
59270@see Portal
59271@ingroup enviroMisc
59272
59273*/
59274class Zone : public SceneObject {
59275public:
59276/*!
59277@brief Get the unique numeric ID of the zone in its scene.
59278
59279
59280@return The ID of the zone.*/
59281int getZoneId();
59282/*!
59283@brief Dump a list of all objects assigned to the zone to the console as well as a list of all connected zone spaces.
59284
59285
59286@param updateFirst Whether to update the contents of the zone before dumping.  Since zoning states of objects are updated on demand, the zone contents can be outdated.*/
59287void dumpZoneState( bool updateFirst=true );
59288/*!
59289@brief select a list of all objects assigned to the zone
59290
59291*/
59292void selectWithin();
59293
59294/*! @name Callbacks
59295@{ */
59296/// @}
59297
59298/*!
59299@brief Disables rendering of all instances of this type.
59300
59301
59302@ingroup UNDOCUMENTED
59303*/
59304static bool isRenderable;
59305/*!
59306@brief Disables selection of all instances of this type.
59307
59308
59309@ingroup UNDOCUMENTED
59310*/
59311static bool isSelectable;
59312/*!
59313@brief Select all in this zone
59314*/
59315bool selectAll;
59316
59317/*! @name Sound
59318@{ */
59319/*!
59320@brief Ambient sound environment for the space.
59321*/
59322SFXAmbience soundAmbience;
59323/// @}
59324
59325
59326/*! @name Internal
59327@{ */
59328/*!
59329@brief For internal use only.
59330*/
59331string plane;
59332/*!
59333@brief For internal use only.
59334*/
59335string point;
59336/*!
59337@brief For internal use only.
59338*/
59339string edge;
59340/// @}
59341
59342
59343/*! @name Lighting
59344@{ */
59345/*!
59346@brief Whether to use #ambientLightColor for ambient lighting in this zone or the global ambient color.
59347*/
59348bool useAmbientLightColor;
59349/*!
59350@brief Color of ambient lighting in this zone.
59351
59352
59353Only used if #useAmbientLightColor is true.
59354*/
59355LinearColorF ambientLightColor;
59356/// @}
59357
59358
59359/*! @name Zoning
59360@{ */
59361/*!
59362@brief ID of group the zone is part of.
59363*/
59364int zoneGroup;
59365/// @}
59366
59367
59368/*! @name GameObject
59369@{ */
59370/// @}
59371
59372
59373/*! @name Transform
59374@{ */
59375/// @}
59376
59377
59378/*! @name Editing
59379@{ */
59380/// @}
59381
59382
59383/*! @name Mounting
59384@{ */
59385/// @}
59386
59387
59388/*! @name Ungrouped
59389@{ */
59390/// @}
59391
59392
59393/*! @name Object
59394@{ */
59395/// @}
59396
59397
59398/*! @name Editing
59399@{ */
59400/// @}
59401
59402
59403/*! @name Persistence
59404@{ */
59405/// @}
59406
59407};
59408
59409/*!
59410@brief An object that provides a "window" into a zone, allowing a viewer to see what's rendered in the zone.
59411
59412A portal is an object that connects zones such that the content of one zone becomes visible in the other when looking through the portal.
59413
59414Each portal is a full zone which is divided into two sides by the portal plane that intersects it.  This intersection polygon is shown in red in the editor.  Either of the sides of a portal can be connected to one or more zones.
59415
59416A connection from a specific portal side to a zone is made in either of two ways:
59417
59418<ol>
59419<li>By moving a Zone object to intersect with the portal at the respective side.  While usually it makes sense for this overlap to be small, the connection is established correctly as long as the center of the Zone object that should connect is on the correct side of the portal plane.</li>
59420<li>By the respective side of the portal free of Zone objects that would connect to it.  In this case, given that the other side is connected to one or more Zones, the portal will automatically connect itself to the outdoor "zone" which implicitly is present in any level.</li>
59421</ol>
59422
59423From this, it follows that there are two types of portals:
59424
59425<dl>
59426<dt>Exterior Portals</dt><dd>An exterior portal is one that is connected to one or more Zone objects on one side and to the outdoor zone at the other side.  This kind of portal is most useful for covering transitions from outdoor spaces to indoor spaces.</dd><dt>Interior Portals</dt><dd>An interior portal is one that is connected to one or more Zone objects on both sides.  This kind of portal is most useful for covering transitions between indoor spaces./dd></dl>
59427
59428Strictly speaking, there is a third type of portal called an "invalid portal".  This is a portal that is not connected to a Zone object on either side in which case the portal serves no use.
59429
59430Portals in Torque are bidirectional meaning that they connect zones both ways and you can look through the portal's front side as well as through its back-side.
59431
59432Like Zones, Portals can either be box-shaped or use custom convex polyhedral shapes.
59433
59434Portals will usually be created in the editor but can, of course, also be created in script code as such:
59435
59436@tsexample
59437// Example declaration of a Portal.  This will create a box-shaped portal.
59438new Portal( PortalToTestZone )
59439{
59440   position = "12.8467 -4.02246 14.8017";
59441    rotation = "0 0 -1 97.5085";
59442    scale = "1 0.25 1";
59443    canSave = "1";
59444    canSaveDynamicFields = "1";
59445};
59446@endtsexample
59447
59448@note Keep in mind that zones and portals are more or less strictly a scene optimization mechanism meant to improve render times.
59449
59450@see Zone
59451@ingroup enviroMisc
59452
59453*/
59454class Portal : public Zone {
59455public:
59456/*!
59457@brief Test whether the portal connects interior zones only.
59458
59459
59460@return True if the portal is an interior portal.*/
59461bool isInteriorPortal();
59462/*!
59463@brief Test whether the portal connects interior zones to the outdoor zone.
59464
59465
59466@return True if the portal is an exterior portal.*/
59467bool isExteriorPortal();
59468
59469/*! @name Callbacks
59470@{ */
59471/// @}
59472
59473/*!
59474@brief Disables rendering of all instances of this type.
59475
59476
59477@ingroup UNDOCUMENTED
59478*/
59479static bool isRenderable;
59480/*!
59481@brief Disables selection of all instances of this type.
59482
59483
59484@ingroup UNDOCUMENTED
59485*/
59486static bool isSelectable;
59487
59488/*! @name Zoning
59489@{ */
59490/*!
59491@brief Whether one can view through the front-side of the portal.
59492*/
59493bool frontSidePassable;
59494/*!
59495@brief Whether one can view through the back-side of the portal.
59496*/
59497bool backSidePassable;
59498/// @}
59499
59500
59501/*! @name Sound
59502@{ */
59503/// @}
59504
59505
59506/*! @name Internal
59507@{ */
59508/// @}
59509
59510
59511/*! @name Lighting
59512@{ */
59513/// @}
59514
59515
59516/*! @name Zoning
59517@{ */
59518/// @}
59519
59520
59521/*! @name GameObject
59522@{ */
59523/// @}
59524
59525
59526/*! @name Transform
59527@{ */
59528/// @}
59529
59530
59531/*! @name Editing
59532@{ */
59533/// @}
59534
59535
59536/*! @name Mounting
59537@{ */
59538/// @}
59539
59540
59541/*! @name Ungrouped
59542@{ */
59543/// @}
59544
59545
59546/*! @name Object
59547@{ */
59548/// @}
59549
59550
59551/*! @name Editing
59552@{ */
59553/// @}
59554
59555
59556/*! @name Persistence
59557@{ */
59558/// @}
59559
59560};
59561
59562/*!
59563@brief A collection of arbitrary objects which can be allocated and manipulated as a group.
59564
59565%Prefab always points to a (.prefab) file which defines its objects. In fact more than one %Prefab can reference this file and both will update if the file is modified.
59566
59567%Prefab is a very simple object and only exists on the server. When it is created it allocates children objects by reading the (.prefab) file like a list of instructions.  It then sets their transform relative to the %Prefab and Torque networking handles the rest by ghosting the new objects to clients. %Prefab itself is not ghosted.
59568
59569@ingroup enviroMisc
59570*/
59571class Prefab : public SceneObject {
59572public:
59573
59574/*! @name Callbacks
59575@{ */
59576/*!
59577@brief Called when the prefab file is loaded and children objects are created.
59578
59579@param children SimGroup containing all children objects.
59580*/
59581void onLoad( SimGroup  children );
59582/// @}
59583
59584/*!
59585@brief Disables rendering of all instances of this type.
59586
59587
59588@ingroup UNDOCUMENTED
59589*/
59590static bool isRenderable;
59591/*!
59592@brief Disables selection of all instances of this type.
59593
59594
59595@ingroup UNDOCUMENTED
59596*/
59597static bool isSelectable;
59598
59599/*! @name Prefab
59600@{ */
59601/*!
59602@brief (.prefab) File describing objects within this prefab.
59603*/
59604filename fileName;
59605/// @}
59606
59607
59608/*! @name GameObject
59609@{ */
59610/// @}
59611
59612
59613/*! @name Transform
59614@{ */
59615/// @}
59616
59617
59618/*! @name Editing
59619@{ */
59620/// @}
59621
59622
59623/*! @name Mounting
59624@{ */
59625/// @}
59626
59627
59628/*! @name Ungrouped
59629@{ */
59630/// @}
59631
59632
59633/*! @name Object
59634@{ */
59635/// @}
59636
59637
59638/*! @name Editing
59639@{ */
59640/// @}
59641
59642
59643/*! @name Persistence
59644@{ */
59645/// @}
59646
59647};
59648
59649/*!
59650@brief Stores common properties for a ProximityMine.
59651
59652@see ProximityMine
59653@ingroup gameObjects
59654
59655*/
59656class ProximityMineData : public ItemData {
59657public:
59658
59659/*! @name Callbacks
59660@{ */
59661/*!
59662@brief Callback invoked when an object triggers the ProximityMine.
59663
59664
59665@param obj The ProximityMine object
59666@param target The object that triggered the mine
59667@note This callback is only invoked on the server.
59668@see ProximityMine
59669*/
59670void onTriggered( ProximityMine obj, SceneObject  target );
59671/*!
59672@brief Callback invoked when a ProximityMine is about to explode.
59673
59674
59675@param obj The ProximityMine object
59676@param pos The position of the mine explosion
59677@note This callback is only invoked on the server.
59678@see ProximityMine
59679*/
59680void onExplode( ProximityMine obj, Point3F pos );
59681/// @}
59682
59683
59684/*! @name Arming
59685@{ */
59686/*!
59687@brief Delay (in seconds) from when the mine is placed to when it becomes active.
59688*/
59689float armingDelay;
59690/*!
59691@brief Sound to play when the mine is armed (starts at the same time as the <i>armed</i> sequence if defined).
59692*/
59693SFXTrack armingSound;
59694/// @}
59695
59696
59697/*! @name Triggering
59698@{ */
59699/*!
59700@brief @brief Delay (in seconds) from arming until the mine automatically triggers and explodes, even if no object has entered the trigger area.
59701
59702
59703Set to 0 to disable.
59704*/
59705float autoTriggerDelay;
59706/*!
59707@brief @brief Controls whether the mine can be triggered by the object that owns it.
59708
59709
59710For example, a player could deploy mines that are only dangerous to other players and not himself.
59711*/
59712bool triggerOnOwner;
59713/*!
59714@brief Distance at which an activated mine will detect other objects and explode.
59715*/
59716float triggerRadius;
59717/*!
59718@brief Speed above which moving objects within the trigger radius will trigger the mine
59719*/
59720float triggerSpeed;
59721/*!
59722@brief Delay (in seconds) from when the mine is triggered until it explodes.
59723*/
59724float triggerDelay;
59725/*!
59726@brief Sound to play when the mine is triggered (starts at the same time as the <i>triggered</i> sequence if defined).
59727*/
59728SFXTrack triggerSound;
59729/// @}
59730
59731
59732/*! @name Explosion
59733@{ */
59734/*!
59735@brief @brief Offset from the mine's origin where the explosion emanates from.Sometimes a thrown mine may be slightly sunk into the ground.  This can be just enough to cause the explosion to occur under the ground, especially on flat ground, which can end up blocking the explosion.  This offset along the mine's 'up' normal allows you to raise the explosion origin to a better height.
59736*/
59737float explosionOffset;
59738/// @}
59739
59740
59741/*! @name Shadows
59742@{ */
59743/// @}
59744
59745
59746/*! @name Render
59747@{ */
59748/// @}
59749
59750
59751/*! @name Destruction
59752Parameters related to the destruction effects of this object.
59753@{ */
59754/// @}
59755
59756
59757/*! @name Physics
59758@{ */
59759/// @}
59760
59761
59762/*! @name Damage/Energy
59763@{ */
59764/// @}
59765
59766
59767/*! @name Camera
59768The settings used by the shape when it is the camera.
59769@{ */
59770/// @}
59771
59772
59773/*! @name Misc
59774@{ */
59775/// @}
59776
59777
59778/*! @name Reflection
59779@{ */
59780/// @}
59781
59782
59783/*! @name Scripting
59784@{ */
59785/// @}
59786
59787
59788/*! @name Ungrouped
59789@{ */
59790/// @}
59791
59792
59793/*! @name Object
59794@{ */
59795/// @}
59796
59797
59798/*! @name Editing
59799@{ */
59800/// @}
59801
59802
59803/*! @name Persistence
59804@{ */
59805/// @}
59806
59807};
59808
59809/*!
59810@brief A simple proximity mine.
59811
59812Proximity mines can be deployed using the world editor or thrown by an in-game object. Once armed, any Player or Vehicle object that moves within the mine's trigger area will cause it to explode.
59813
59814Internally, the ProximityMine object transitions through the following states:
59815<ol>
59816  <li><b>Thrown</b>: Mine has been thrown, but has not yet attached to a surface</li>
59817  <li><b>Deployed</b>: Mine has attached to a surface but is not yet armed. Start playing the #armingSound and <i>armed</i> sequence.</li>
59818  <li><b>Armed</b>: Mine is armed and will trigger if a Vehicle or Player object moves within the trigger area.</li>
59819  <li><b>Triggered</b>: Mine has been triggered and will explode soon. Invoke the onTriggered callback, and start playing the #triggerSound and <i>triggered</i> sequence.</li>
59820  <li><b>Exploded</b>: Mine has exploded and will be deleted on the server shortly. Invoke the onExplode callback on the server and generate the explosion effects on the client.</li>
59821</ol>
59822
59823@note Proximity mines with the #static field set to true will start in the <b>Armed</b> state. Use this for mines placed with the World Editor.
59824
59825The shape used for the mine may optionally define the following sequences:
59826<dl>
59827  <dt>armed</dt><dd>Sequence to play when the mine is deployed, but before it becomes active and triggerable (#armingDelay should be set appropriately).</dd>
59828  <dt>triggered</dt><dd>Sequence to play when the mine is triggered, just before it explodes (#triggerDelay should be set appropriately).<dd>
59829</dl>
59830
59831@tsexample
59832datablock ProximityMineData( SimpleMine )
59833{
59834   // ShapeBaseData fields
59835   category = "Weapon";
59836   shapeFile = "art/shapes/weapons/misc/proximityMine.dts";
59837
59838   // ItemData fields
59839   sticky = true;
59840
59841   // ProximityMineData fields
59842   armingDelay = 0.5;
59843   armingSound = MineArmedSound;
59844
59845   autoTriggerDelay = 0;
59846   triggerOnOwner = true;
59847   triggerRadius = 5.0;
59848   triggerSpeed = 1.0;
59849   triggerDelay = 0.5;
59850   triggerSound = MineTriggeredSound;
59851   explosion = RocketLauncherExplosion;
59852
59853   // dynamic fields
59854   pickUpName = "Proximity Mines";
59855   maxInventory = 20;
59856
59857   damageType = "MineDamage"; // type of damage applied to objects in radius
59858   radiusDamage = 30;           // amount of damage to apply to objects in radius
59859   damageRadius = 8;            // search radius to damage objects when exploding
59860   areaImpulse = 2000;          // magnitude of impulse to apply to objects in radius
59861};
59862
59863function ProximityMineData::onTriggered( %this, %obj, %target )
59864{
59865   echo( %this.name SPC "triggered by " @ %target.getClassName() );
59866}
59867
59868function ProximityMineData::onExplode( %this, %obj, %position )
59869{
59870   // Damage objects within the mine's damage radius
59871   if ( %this.damageRadius > 0 )
59872      radiusDamage( %obj.sourceObject, %position, %this.damageRadius, %this.radiusDamage, %this.damageType, %this.areaImpulse );
59873}
59874
59875function ProximityMineData::damage( %this, %obj, %position, %source, %amount, %damageType )
59876{
59877   // Explode if any damage is applied to the mine
59878   %obj.schedule(50 + getRandom(50), explode);
59879}
59880
59881%obj = new ProximityMine()
59882{
59883   dataBlock = SimpleMine;
59884};
59885@endtsexample
59886
59887@see ProximityMineData
59888@ingroup gameObjects
59889
59890*/
59891class ProximityMine : public Item {
59892public:
59893/*!
59894@brief Manually cause the mine to explode.*/
59895void explode();
59896
59897/*! @name Callbacks
59898@{ */
59899/// @}
59900
59901/*!
59902@brief Disables rendering of all instances of this type.
59903
59904
59905@ingroup UNDOCUMENTED
59906*/
59907static bool isRenderable;
59908/*!
59909@brief Disables selection of all instances of this type.
59910
59911
59912@ingroup UNDOCUMENTED
59913*/
59914static bool isSelectable;
59915
59916/*! @name Misc
59917@{ */
59918/// @}
59919
59920
59921/*! @name Game
59922@{ */
59923/// @}
59924
59925
59926/*! @name GameObject
59927@{ */
59928/// @}
59929
59930
59931/*! @name Transform
59932@{ */
59933/// @}
59934
59935
59936/*! @name Editing
59937@{ */
59938/// @}
59939
59940
59941/*! @name Mounting
59942@{ */
59943/// @}
59944
59945
59946/*! @name Ungrouped
59947@{ */
59948/// @}
59949
59950
59951/*! @name Object
59952@{ */
59953/// @}
59954
59955
59956/*! @name Editing
59957@{ */
59958/// @}
59959
59960
59961/*! @name Persistence
59962@{ */
59963/// @}
59964
59965};
59966
59967/*!
59968@brief Represents geometry to be mounted to a ShapeBase object.
59969
59970@ingroup gameObjects
59971
59972*/
59973class ShapeBaseImageData : public GameBaseData {
59974public:
59975
59976/*! @name Callbacks
59977@{ */
59978/*!
59979@brief Called when the Image is first mounted to the object.
59980
59981@param obj object that this Image has been mounted to
59982@param slot Image mount slot on the object
59983@param dt time remaining in this Image update*/
59984void onMount( SceneObject obj, int slot, float dt );
59985/*!
59986@brief Called when the Image is unmounted from the object.
59987
59988@param obj object that this Image has been unmounted from
59989@param slot Image mount slot on the object
59990@param dt time remaining in this Image update*/
59991void onUnmount( SceneObject obj, int slot, float dt );
59992/// @}
59993
59994/*!
59995@brief @brief Whether to enable environment mapping on this Image.
59996
59997
59998
59999*/
60000bool emap;
60001/*!
60002@brief @brief The DTS or DAE model to use for this Image.
60003
60004
60005
60006*/
60007filename shapeFile;
60008/*!
60009@brief @brief The DTS or DAE model to use for this Image when in first person.
60010
60011
60012This is an optional parameter that also requires either eyeOffset or useEyeNode to be set.  If none of these conditions is met then shapeFile will be used for all cases.
60013
60014Typically you set a first person image for a weapon that includes the player's arms attached to it for animating while firing, reloading, etc.  This is typical of many FPS games.@see eyeOffset
60015@see useEyeNode
60016
60017*/
60018filename shapeFileFP;
60019/*!
60020@brief @brief Passed along to the mounting shape to modify animation sequences played in third person. [optional]
60021
60022
60023
60024*/
60025caseString imageAnimPrefix;
60026/*!
60027@brief @brief Passed along to the mounting shape to modify animation sequences played in first person. [optional]
60028
60029
60030
60031*/
60032caseString imageAnimPrefixFP;
60033/*!
60034@brief @brief Indicates that all shapes should be animated in sync.
60035
60036
60037When multiple shapes are defined for this image datablock, each of them are automatically animated in step with each other.  This allows for easy switching between between shapes when some other condition changes, such as going from first person to third person, and keeping their look consistent.  If you know that you'll never switch between shapes on the fly, such as players only being allowed in a first person view, then you could set this to false to save some calculations.
60038
60039There are other circumstances internal to the engine that determine that only the current shape should be animated rather than all defined shapes.  In those cases, this property is ignored.
60040
60041@note This property is only important if you have more than one shape defined, such as shapeFileFP.
60042
60043@see shapeFileFP
60044
60045*/
60046bool animateAllShapes;
60047/*!
60048@brief @brief Indicates that the image should be animated on the server.
60049
60050
60051In most cases you'll want this set if you're using useEyeNode.  You may also want to set this if the muzzlePoint is animated while it shoots.  You can set this to false even if these previous cases are true if the image's shape is set up in the correct position and orientation in the 'root' pose and none of the nodes are animated at key times, such as the muzzlePoint essentially remaining at the same position at the start of the fire state (it could animate just fine after the projectile is away as the muzzle vector is only calculated at the start of the state).
60052
60053You'll also want to set this to true if you're animating the camera using the image's 'eye' node -- unless the movement is very subtle and doesn't need to be reflected on the server.
60054
60055@note Setting this to true causes up to four animation threads to be advanced on the server for each instance in use, although for most images only one or two are actually defined.
60056
60057@see useEyeNode
60058
60059*/
60060bool animateOnServer;
60061/*!
60062@brief @brief The amount of time to transition between the previous sequence and new sequence when the script prefix has changed.
60063
60064
60065When setImageScriptAnimPrefix() is used on a ShapeBase that has this image mounted, the image will attempt to switch to the new animation sequence based on the given script prefix.  This is the amount of time it takes to transition from the previously playing animation sequence tothe new script prefix-based animation sequence.
60066@see ShapeBase::setImageScriptAnimPrefix()
60067*/
60068float scriptAnimTransitionTime;
60069/*!
60070@brief @brief The projectile fired by this Image
60071
60072
60073
60074*/
60075ProjectileData Projectile;
60076/*!
60077@brief @brief Whether this Image can be cloaked.
60078
60079
60080Currently unused.
60081*/
60082bool cloakable;
60083/*!
60084@brief @brief Mount node # to mount this Image to.
60085
60086
60087This should correspond to a mount# node on the ShapeBase derived object we are mounting to.
60088*/
60089int mountPoint;
60090/*!
60091@brief @brief "X Y Z" translation offset from this Image's <i>mountPoint</i> node to attach to.
60092
60093
60094Defaults to "0 0 0". ie. attach this Image's <i>mountPoint</i> node to the ShapeBase model's mount# node without any offset.
60095@see rotation
60096*/
60097MatrixPosition offset;
60098/*!
60099@brief @brief "X Y Z ANGLE" rotation offset from this Image's <i>mountPoint</i> node to attach to.
60100
60101
60102Defaults to "0 0 0". ie. attach this Image's <i>mountPoint</i> node to the ShapeBase model's mount# node without any additional rotation.
60103@see offset
60104*/
60105MatrixRotation rotation;
60106/*!
60107@brief @brief "X Y Z" translation offset from the ShapeBase model's eye node.
60108
60109
60110When in first person view, this is the offset from the eye node to place the gun.  This gives the gun a fixed point in space, typical of a lot of FPS games.
60111@see eyeRotation
60112*/
60113MatrixPosition eyeOffset;
60114/*!
60115@brief @brief "X Y Z ANGLE" rotation offset from the ShapeBase model's eye node.
60116
60117
60118When in first person view, this is the rotation from the eye node to place the gun.
60119@see eyeOffset
60120*/
60121MatrixRotation eyeRotation;
60122/*!
60123@brief @brief Mount image using image's eyeMount node and place the camera at the image's eye node (or at the eyeMount node if the eye node is missing).
60124
60125
60126When in first person view, if an 'eyeMount' node is present in the image's shape, this indicates that the image should mount eyeMount node to Player eye node for image placement.  The Player's camera should also mount to the image's eye node to inherit any animation (or the eyeMount node if the image doesn't have an eye node).
60127
60128@note Used instead of eyeOffset.
60129
60130@note Read about the animateOnServer field as you may want to set it to true if you're using useEyeNode.
60131
60132@see eyeOffset
60133
60134@see animateOnServer
60135
60136
60137*/
60138bool useEyeNode;
60139/*!
60140@brief @brief Flag to adjust the aiming vector to the eye's LOS point when in 1st person view.
60141
60142
60143@see ShapeBase::getMuzzleVector()
60144*/
60145bool correctMuzzleVector;
60146/*!
60147@brief @brief Flag to adjust the aiming vector to the camera's LOS point when in 3rd person view.
60148
60149
60150@see ShapeBase::getMuzzleVector()
60151*/
60152bool correctMuzzleVectorTP;
60153/*!
60154@brief @brief Set to true to render the image in first person.
60155*/
60156bool firstPerson;
60157/*!
60158@brief @brief Mass of this Image.
60159
60160
60161This is added to the total mass of the ShapeBase object.
60162*/
60163float mass;
60164/*!
60165@brief @brief Flag indicating whether this Image uses energy instead of ammo.  The energy level comes from the ShapeBase object we're mounted to.
60166
60167
60168@see ShapeBase::setEnergyLevel()
60169*/
60170bool usesEnergy;
60171/*!
60172@brief @brief Minimum Image energy for it to be operable.
60173
60174
60175@see usesEnergy
60176*/
60177float minEnergy;
60178/*!
60179@brief @brief Flag to control whether the Image's aim is automatically converged with the crosshair.
60180
60181
60182Currently unused.
60183*/
60184bool accuFire;
60185/*!
60186@brief @brief The type of light this Image emits.
60187
60188
60189@see ShapeBaseImageLightType
60190*/
60191ShapeBaseImageLightType lightType;
60192/*!
60193@brief @brief The color of light this Image emits.
60194
60195
60196@see lightType
60197*/
60198LinearColorF lightColor;
60199/*!
60200@brief @brief Duration in SimTime of Pulsing and WeaponFire type lights.
60201
60202
60203@see lightType
60204*/
60205int lightDuration;
60206/*!
60207@brief @brief Radius of the light this Image emits.
60208
60209
60210@see lightType
60211*/
60212float lightRadius;
60213/*!
60214@brief @brief Brightness of the light this Image emits.
60215
60216
60217Only valid for WeaponFireLight.@see lightType
60218*/
60219float lightBrightness;
60220/*!
60221@brief @brief Flag indicating whether the camera should shake when this Image fires.
60222
60223
60224
60225*/
60226bool ShakeCamera;
60227/*!
60228@brief @brief Frequency of the camera shaking effect.
60229
60230
60231@see shakeCamera
60232*/
60233Point3F camShakeFreq;
60234/*!
60235@brief @brief Amplitude of the camera shaking effect.
60236
60237
60238@see shakeCamera
60239*/
60240Point3F camShakeAmp;
60241/*!
60242@brief Duration (in seconds) to shake the camera.
60243*/
60244float camShakeDuration;
60245/*!
60246@brief Radial distance that a camera's position must be within relative to the center of the explosion to be shaken.
60247*/
60248float camShakeRadius;
60249/*!
60250@brief Falloff value for the camera shake.
60251*/
60252float camShakeFalloff;
60253/*!
60254@brief @brief DebrisData datablock to use for ejected casings.
60255
60256
60257@see stateEjectShell
60258*/
60259DebrisData casing;
60260/*!
60261@brief @brief Vector direction to eject shell casings.
60262
60263
60264@see casing
60265*/
60266Point3F shellExitDir;
60267/*!
60268@brief @brief Variance (in degrees) from the shellExitDir vector to eject casings.
60269
60270
60271@see shellExitDir
60272*/
60273float shellExitVariance;
60274/*!
60275@brief @brief Speed at which to eject casings.
60276
60277
60278@see casing
60279*/
60280float shellVelocity;
60281/*!
60282@brief Name of this state.
60283*/
60284caseString stateName[ 31 ];
60285/*!
60286@brief Name of the state to transition to when the loaded state of the Image changes to 'Loaded'.
60287*/
60288string stateTransitionOnLoaded[ 31 ];
60289/*!
60290@brief Name of the state to transition to when the loaded state of the Image changes to 'Empty'.
60291*/
60292string stateTransitionOnNotLoaded[ 31 ];
60293/*!
60294@brief Name of the state to transition to when the ammo state of the Image changes to true.
60295*/
60296string stateTransitionOnAmmo[ 31 ];
60297/*!
60298@brief Name of the state to transition to when the ammo state of the Image changes to false.
60299*/
60300string stateTransitionOnNoAmmo[ 31 ];
60301/*!
60302@brief Name of the state to transition to when the Image gains a target.
60303*/
60304string stateTransitionOnTarget[ 31 ];
60305/*!
60306@brief Name of the state to transition to when the Image loses a target.
60307*/
60308string stateTransitionOnNoTarget[ 31 ];
60309/*!
60310@brief Name of the state to transition to when the Image enters the water.
60311*/
60312string stateTransitionOnWet[ 31 ];
60313/*!
60314@brief Name of the state to transition to when the Image exits the water.
60315*/
60316string stateTransitionOnNotWet[ 31 ];
60317/*!
60318@brief Name of the state to transition to when the Player moves.
60319*/
60320string stateTransitionOnMotion[ 31 ];
60321/*!
60322@brief Name of the state to transition to when the Player stops moving.
60323*/
60324string stateTransitionOnNoMotion[ 31 ];
60325/*!
60326@brief Name of the state to transition to when the trigger state of the Image changes to true (fire button down).
60327*/
60328string stateTransitionOnTriggerUp[ 31 ];
60329/*!
60330@brief Name of the state to transition to when the trigger state of the Image changes to false (fire button released).
60331*/
60332string stateTransitionOnTriggerDown[ 31 ];
60333/*!
60334@brief Name of the state to transition to when the alt trigger state of the Image changes to true (alt fire button down).
60335*/
60336string stateTransitionOnAltTriggerUp[ 31 ];
60337/*!
60338@brief Name of the state to transition to when the alt trigger state of the Image changes to false (alt fire button up).
60339*/
60340string stateTransitionOnAltTriggerDown[ 31 ];
60341/*!
60342@brief Name of the state to transition to when we have been in this state for stateTimeoutValue seconds.
60343*/
60344string stateTransitionOnTimeout[ 31 ];
60345/*!
60346@brief Name of the state to transition to when the generic trigger 0 state changes to true.
60347*/
60348string stateTransitionGeneric0In[ 31 ];
60349/*!
60350@brief Name of the state to transition to when the generic trigger 0 state changes to false.
60351*/
60352string stateTransitionGeneric0Out[ 31 ];
60353/*!
60354@brief Name of the state to transition to when the generic trigger 1 state changes to true.
60355*/
60356string stateTransitionGeneric1In[ 31 ];
60357/*!
60358@brief Name of the state to transition to when the generic trigger 1 state changes to false.
60359*/
60360string stateTransitionGeneric1Out[ 31 ];
60361/*!
60362@brief Name of the state to transition to when the generic trigger 2 state changes to true.
60363*/
60364string stateTransitionGeneric2In[ 31 ];
60365/*!
60366@brief Name of the state to transition to when the generic trigger 2 state changes to false.
60367*/
60368string stateTransitionGeneric2Out[ 31 ];
60369/*!
60370@brief Name of the state to transition to when the generic trigger 3 state changes to true.
60371*/
60372string stateTransitionGeneric3In[ 31 ];
60373/*!
60374@brief Name of the state to transition to when the generic trigger 3 state changes to false.
60375*/
60376string stateTransitionGeneric3Out[ 31 ];
60377/*!
60378@brief Time in seconds to wait before transitioning to stateTransitionOnTimeout.
60379*/
60380float stateTimeoutValue[ 31 ];
60381/*!
60382@brief If false, this state ignores stateTimeoutValue and transitions immediately if other transition conditions are met.
60383*/
60384bool stateWaitForTimeout[ 31 ];
60385/*!
60386@brief The first state with this set to true is the state entered by the client when it receives the 'fire' event.
60387*/
60388bool stateFire[ 31 ];
60389/*!
60390@brief The first state with this set to true is the state entered by the client when it receives the 'altFire' event.
60391*/
60392bool stateAlternateFire[ 31 ];
60393/*!
60394@brief The first state with this set to true is the state entered by the client when it receives the 'reload' event.
60395*/
60396bool stateReload[ 31 ];
60397/*!
60398@brief If true, a shell casing will be ejected in this state.
60399*/
60400bool stateEjectShell[ 31 ];
60401/*!
60402@brief @brief Amount of energy to subtract from the Image in this state.
60403
60404
60405Energy is drained at stateEnergyDrain units/tick as long as we are in this state.
60406@see usesEnergy
60407*/
60408float stateEnergyDrain[ 31 ];
60409/*!
60410@brief @brief If false, other Images will temporarily be blocked from mounting while the state machine is executing the tasks in this state.
60411
60412
60413For instance, if we have a rocket launcher, the player shouldn't be able to switch out <i>while</i> firing. So, you'd set stateAllowImageChange to false in firing states, and true the rest of the time.
60414*/
60415bool stateAllowImageChange[ 31 ];
60416/*!
60417@brief @brief Direction of the animation to play in this state.
60418
60419
60420True is forward, false is backward.
60421*/
60422bool stateDirection[ 31 ];
60423/*!
60424@brief @brief Set the loaded state of the Image.
60425
60426
60427<ul><li>IgnoreLoaded: Don't change Image loaded state.</li><li>Loaded: Set Image loaded state to true.</li><li>NotLoaded: Set Image loaded state to false.</li></ul>
60428@see ShapeBaseImageLoadedState
60429*/
60430ShapeBaseImageLoadedState stateLoadedFlag[ 31 ];
60431/*!
60432@brief @brief Controls how fast the 'spin' animation sequence will be played in this state.
60433
60434
60435<ul><li>Ignore: No change to the spin sequence.</li><li>Stop: Stops the spin sequence at its current position.</li><li>SpinUp: Increase spin sequence timeScale from 0 (on state entry) to 1 (after stateTimeoutValue seconds).</li><li>SpinDown: Decrease spin sequence timeScale from 1 (on state entry) to 0 (after stateTimeoutValue seconds).</li><li>FullSpeed: Resume the spin sequence playback at its current position with timeScale=1.</li></ul>
60436@see ShapeBaseImageSpinState
60437*/
60438ShapeBaseImageSpinState stateSpinThread[ 31 ];
60439/*!
60440@brief @brief Type of recoil sequence to play on the ShapeBase object on entry to this state.
60441
60442
60443<ul><li>NoRecoil: Do not play a recoil sequence.</li><li>LightRecoil: Play the light_recoil sequence.</li><li>MediumRecoil: Play the medium_recoil sequence.</li><li>HeavyRecoil: Play the heavy_recoil sequence.</li></ul>
60444@see ShapeBaseImageRecoilState
60445*/
60446ShapeBaseImageRecoilState stateRecoil[ 31 ];
60447/*!
60448@brief Name of the sequence to play on entry to this state.
60449*/
60450string stateSequence[ 31 ];
60451/*!
60452@brief @brief If true, the muzzle flash sequence will be played while in this state.
60453
60454
60455The name of the muzzle flash sequence is the same as stateSequence, with "_vis" at the end.
60456*/
60457bool stateSequenceRandomFlash[ 31 ];
60458/*!
60459@brief If true, the timeScale of the stateSequence animation will be adjusted such that the sequence plays for stateTimeoutValue seconds. 
60460*/
60461bool stateScaleAnimation[ 31 ];
60462/*!
60463@brief If true, the timeScale of the first person stateSequence animation will be adjusted such that the sequence plays for stateTimeoutValue seconds. 
60464*/
60465bool stateScaleAnimationFP[ 31 ];
60466/*!
60467@brief Do we transition to the state's sequence when we enter the state?
60468*/
60469bool stateSequenceTransitionIn[ 31 ];
60470/*!
60471@brief Do we transition to the new state's sequence when we leave the state?
60472*/
60473bool stateSequenceTransitionOut[ 31 ];
60474/*!
60475@brief Never allow a transition to this sequence.  Often used for a fire sequence.
60476*/
60477bool stateSequenceNeverTransition[ 31 ];
60478/*!
60479@brief The time to transition in or out of a sequence.
60480*/
60481float stateSequenceTransitionTime[ 31 ];
60482/*!
60483@brief Name of the sequence that is played on the mounting shape.
60484*/
60485string stateShapeSequence[ 31 ];
60486/*!
60487@brief Indicates if the sequence to be played on the mounting shape should be scaled to the length of the state.
60488*/
60489bool stateScaleShapeSequence[ 31 ];
60490/*!
60491@brief Sound to play on entry to this state.
60492*/
60493SFXTrack stateSound[ 31 ];
60494/*!
60495@brief @brief Method to execute on entering this state.
60496
60497
60498Scoped to this image class name, then ShapeBaseImageData. The script callback function takes the same arguments as the onMount callback.
60499@see onMount() for the same arguments as this callback.
60500*/
60501caseString stateScript[ 31 ];
60502/*!
60503@brief @brief Emitter to generate particles in this state (from muzzle point or specified node).
60504
60505
60506@see stateEmitterNode
60507*/
60508ParticleEmitterData stateEmitter[ 31 ];
60509/*!
60510@brief How long (in seconds) to emit particles on entry to this state.
60511*/
60512float stateEmitterTime[ 31 ];
60513/*!
60514@brief @brief Name of the node to emit particles from.
60515
60516
60517@see stateEmitter
60518*/
60519string stateEmitterNode[ 31 ];
60520/*!
60521@brief @brief If set to true, and both ready and loaded transitions are true, the ready transition will be taken instead of the loaded transition.
60522
60523
60524A state is 'ready' if pressing the fire trigger in that state would transition to the fire state.
60525*/
60526bool stateIgnoreLoadedForReady[ 31 ];
60527/*!
60528@brief If true, verify that the CRC of the client's Image matches the server's CRC for the Image when loaded by the client.
60529*/
60530bool computeCRC;
60531/*!
60532@brief @brief Maximum number of sounds this Image can play at a time.
60533
60534
60535Any value <= 0 indicates that it can play an infinite number of sounds.
60536*/
60537int maxConcurrentSounds;
60538/*!
60539@brief @brief If true, allow multiple timeout transitions to occur within a single tick (useful if states have a very small timeout).
60540
60541
60542
60543*/
60544bool useRemainderDT;
60545
60546/*! @name Scripting
60547@{ */
60548/// @}
60549
60550
60551/*! @name Ungrouped
60552@{ */
60553/// @}
60554
60555
60556/*! @name Object
60557@{ */
60558/// @}
60559
60560
60561/*! @name Editing
60562@{ */
60563/// @}
60564
60565
60566/*! @name Persistence
60567@{ */
60568/// @}
60569
60570};
60571
60572/*!
60573@brief Defines shared properties for Trigger objects.
60574
60575The primary focus of the TriggerData datablock is the callbacks it provides when an object is within or leaves the Trigger bounds.
60576@see Trigger.
60577@ingroup gameObjects
60578@ingroup Datablocks
60579
60580*/
60581class TriggerData : public GameBaseData {
60582public:
60583
60584/*! @name Callbacks
60585@{ */
60586/*!
60587@brief Called when an object enters the volume of the Trigger instance using this TriggerData.
60588
60589@param trigger the Trigger instance whose volume the object entered
60590@param obj the object that entered the volume of the Trigger instance*/
60591void onEnterTrigger( Trigger trigger, GameBase obj );
60592/*!
60593@brief Called every tickPeriodMS number of milliseconds (as specified in the TriggerData) whenever one or more objects are inside the volume of the trigger.
60594
60595The Trigger has methods to retrieve the objects that are within the Trigger's bounds if you want to do something with them in this callback.
60596@param trigger the Trigger instance whose volume the object is inside
60597@see tickPeriodMS
60598@see Trigger::getNumObjects()
60599@see Trigger::getObject()*/
60600void onTickTrigger( Trigger trigger );
60601/*!
60602@brief Called when an object leaves the volume of the Trigger instance using this TriggerData.
60603
60604@param trigger the Trigger instance whose volume the object left
60605@param obj the object that left the volume of the Trigger instance*/
60606void onLeaveTrigger( Trigger trigger, GameBase obj );
60607/// @}
60608
60609
60610/*! @name Callbacks
60611@{ */
60612/*!
60613@brief @brief Time in milliseconds between calls to onTickTrigger() while at least one object is within a Trigger's bounds.
60614
60615
60616@see onTickTrigger()
60617
60618*/
60619int tickPeriodMS;
60620/*!
60621@brief Forces Trigger callbacks to only be called on clients.
60622*/
60623bool clientSide;
60624/// @}
60625
60626
60627/*! @name Scripting
60628@{ */
60629/// @}
60630
60631
60632/*! @name Ungrouped
60633@{ */
60634/// @}
60635
60636
60637/*! @name Object
60638@{ */
60639/// @}
60640
60641
60642/*! @name Editing
60643@{ */
60644/// @}
60645
60646
60647/*! @name Persistence
60648@{ */
60649/// @}
60650
60651};
60652
60653/*!
60654@brief A Trigger is a volume of space that initiates script callbacks when objects pass through the Trigger.
60655
60656TriggerData provides the callbacks for the Trigger when an object enters, stays inside or leaves the Trigger's volume.
60657
60658@see TriggerData
60659@ingroup gameObjects
60660
60661*/
60662class Trigger : public GameBase {
60663public:
60664/*!
60665@brief Get the number of objects that are within the Trigger's bounds.
60666
60667@see getObject()*/
60668int getNumObjects();
60669/*!
60670@brief Retrieve the requested object that is within the Trigger's bounds.
60671
60672@param index Index of the object to get (range is 0 to getNumObjects()-1)
60673@returns The SimObjectID of the object, or -1 if the requested index is invalid.
60674@see getNumObjects()*/
60675int getObject( int index );
60676
60677/*! @name Callbacks
60678@{ */
60679/*!
60680@brief Called when the Trigger is being created.
60681
60682@param objectId the object id of the Trigger being created*/
60683void onAdd( uint objectId );
60684/*!
60685@brief Called just before the Trigger is deleted.
60686
60687@param objectId the object id of the Trigger being deleted*/
60688void onRemove( uint objectId );
60689/// @}
60690
60691/*!
60692@brief Forces all Trigger's to render.
60693
60694Used by the Tools and debug render modes.
60695@ingroup gameObjects*/
60696static bool renderTriggers;
60697/*!
60698@brief Disables rendering of all instances of this type.
60699
60700
60701@ingroup UNDOCUMENTED
60702*/
60703static bool isRenderable;
60704/*!
60705@brief Disables selection of all instances of this type.
60706
60707
60708@ingroup UNDOCUMENTED
60709*/
60710static bool isSelectable;
60711/*!
60712@brief @brief Defines a non-rectangular area for the trigger.
60713
60714
60715Rather than the standard rectangular bounds, this optional parameter defines a quadrilateral trigger area.  The quadrilateral is defined as a corner point followed by three vectors representing the edges extending from the corner.
60716
60717*/
60718floatList polyhedron;
60719/*!
60720@brief Do we trigger callacks just the once?
60721*/
60722bool TripOnce;
60723/*!
60724@brief evaluation condition to trip callbacks (true/false)
60725*/
60726string TripCondition;
60727/*!
60728@brief typemask filter
60729*/
60730int TrippedBy;
60731/*!
60732@brief The command to execute when an object enters this trigger. Object id stored in %%obj. Maximum 1023 characters.
60733*/
60734string enterCommand;
60735/*!
60736@brief The command to execute when an object leaves this trigger. Object id stored in %%obj. Maximum 1023 characters.
60737*/
60738string leaveCommand;
60739/*!
60740@brief The command to execute while an object is inside this trigger. Maximum 1023 characters.
60741*/
60742string tickCommand;
60743
60744/*! @name Game
60745@{ */
60746/// @}
60747
60748
60749/*! @name GameObject
60750@{ */
60751/// @}
60752
60753
60754/*! @name Transform
60755@{ */
60756/// @}
60757
60758
60759/*! @name Editing
60760@{ */
60761/// @}
60762
60763
60764/*! @name Mounting
60765@{ */
60766/// @}
60767
60768
60769/*! @name Ungrouped
60770@{ */
60771/// @}
60772
60773
60774/*! @name Object
60775@{ */
60776/// @}
60777
60778
60779/*! @name Editing
60780@{ */
60781/// @}
60782
60783
60784/*! @name Persistence
60785@{ */
60786/// @}
60787
60788};
60789
60790/*!
60791@brief A static object derived from a 3D model file and placed within the game world.
60792
60793TSStatic is the most basic 3D shape in Torque.  Unlike StaticShape it doesn't make use of a datablock.  It derrives directly from SceneObject.  This makes TSStatic extremely light weight, which is why the Tools use this class when you want to drop in a DTS or DAE object.
60794
60795While a TSStatic doesn't provide any motion -- it stays were you initally put it -- it does allow for a single ambient animation sequence to play when the object is first added to the scene.
60796
60797@tsexample
60798new TSStatic(Team1Base) {
60799   shapeName = "art/shapes/desertStructures/station01.dts";
60800   playAmbient = "1";
60801   receiveSunLight = "1";
60802   receiveLMLighting = "1";
60803   useCustomAmbientLighting = "0";
60804   customAmbientLighting = "0 0 0 1";
60805   collisionType = "Visible Mesh";
60806   decalType = "Collision Mesh";
60807   allowPlayerStep = "1";
60808   renderNormals = "0";
60809   forceDetail = "-1";
60810   position = "315.18 -180.418 244.313";
60811   rotation = "0 0 1 195.952";
60812   scale = "1 1 1";
60813   isRenderEnabled = "true";
60814   canSaveDynamicFields = "1";
60815};
60816@endtsexample
60817@ingroup gameObjects
60818
60819*/
60820class TSStatic : public SceneObject {
60821public:
60822/*!
60823@brief Get the name of the indexed shape material.
60824
60825@param index index of the material to get (valid range is 0 - getTargetCount()-1).
60826@return the name of the indexed material.
60827@see getTargetCount()
60828*/
60829string getTargetName( int index=0 );
60830/*!
60831@brief Get the number of materials in the shape.
60832
60833@return the number of materials in the shape.
60834@see getTargetName()
60835*/
60836int getTargetCount();
60837/*!
60838@brief Change one of the materials on the shape.
60839
60840This method changes materials per mapTo with others. The material that is being replaced is mapped to unmapped_mat as a part of this transition.
60841@note Warning, right now this only sort of works. It doesn't do a live update like it should.
60842@param mapTo the name of the material target to remap (from getTargetName)
60843@param oldMat the old Material that was mapped 
60844@param newMat the new Material to map
60845
60846@tsexample
60847// remap the first material in the shape
60848%mapTo = %obj.getTargetName( 0 );
60849%obj.changeMaterial( %mapTo, 0, MyMaterial );
60850@endtsexample*/
60851void changeMaterial( string mapTo="", Material oldMat=nullAsType<Material*>(), Material newMat=nullAsType<Material*>() );
60852/*!
60853@brief Get the model filename used by this shape.
60854
60855@return the shape filename
60856
60857@tsexample
60858// Acquire the model filename used on this shape.
60859%modelFilename = %obj.getModelFile();
60860@endtsexample*/
60861string getModelFile();
60862
60863/*! @name Callbacks
60864@{ */
60865/// @}
60866
60867/*!
60868@brief Disables rendering of all instances of this type.
60869
60870
60871@ingroup UNDOCUMENTED
60872*/
60873static bool isRenderable;
60874/*!
60875@brief Disables selection of all instances of this type.
60876
60877
60878@ingroup UNDOCUMENTED
60879*/
60880static bool isSelectable;
60881/*!
60882@brief Percent Animation Offset.
60883*/
60884float AnimOffset;
60885/*!
60886@brief Percent Animation Speed.
60887*/
60888float AnimSpeed;
60889
60890/*! @name Shape
60891@{ */
60892/*!
60893@brief The source shape asset.
60894*/
60895assetIdString ShapeAsset;
60896/*!
60897@brief %Path and filename of the model file (.DTS, .DAE) to use for this TSStatic. Legacy field. Any loose files assigned here will attempt to be auto-imported in as an asset.
60898*/
60899filename shapeName;
60900/// @}
60901
60902
60903/*! @name Materials
60904@{ */
60905/*!
60906@brief @brief The skin applied to the shape.
60907
60908
60909'Skinning' the shape effectively renames the material targets, allowing different materials to be used on different instances of the same model.
60910
60911Any material targets that start with the old skin name have that part of the name replaced with the new skin name. The initial old skin name is "base". For example, if a new skin of "blue" was applied to a model that had material targets <i>base_body</i> and <i>face</i>, the new targets would be <i>blue_body</i> and <i>face</i>. Note that <i>face</i> was not renamed since it did not start with the old skin name of "base".
60912
60913To support models that do not use the default "base" naming convention, you can also specify the part of the name to replace in the skin field itself. For example, if a model had a material target called <i>shapemat</i>, we could apply a new skin "shape=blue", and the material target would be renamed to <i>bluemat</i> (note "shape" has been replaced with "blue").
60914
60915Multiple skin updates can also be applied at the same time by separating them with a semicolon. For example: "base=blue;face=happy_face".
60916
60917Material targets are only renamed if an existing Material maps to that name, or if there is a diffuse texture in the model folder with the same name as the new target.
60918
60919
60920*/
60921string skin;
60922/// @}
60923
60924
60925/*! @name Rendering
60926@{ */
60927/*!
60928@brief Enables automatic playing of the animation sequence named "ambient" (if it exists) when the TSStatic is loaded.
60929*/
60930bool playAmbient;
60931/*!
60932@brief Enables detailed culling of meshes within the TSStatic. Should only be used with large complex shapes like buildings which contain many submeshes.
60933*/
60934bool meshCulling;
60935/*!
60936@brief Enables translucent sorting of the TSStatic by its origin instead of the bounds.
60937*/
60938bool originSort;
60939/// @}
60940
60941
60942/*! @name Reflection
60943@{ */
60944/*!
60945@brief References a ReflectorDesc datablock that defines performance and quality properties for dynamic reflections.
60946
60947
60948*/
60949string cubeReflectorDesc;
60950/// @}
60951
60952
60953/*! @name Collision
60954@{ */
60955/*!
60956@brief The type of mesh data to use for collision queries.
60957*/
60958TSMeshType collisionType;
60959/*!
60960@brief The type of mesh data used to clip decal polygons against.
60961*/
60962TSMeshType decalType;
60963/*!
60964@brief @brief Allow a Player to walk up sloping polygons in the TSStatic (based on the collisionType).
60965
60966
60967When set to false, the slightest bump will stop the player from walking on top of the object.
60968
60969*/
60970bool allowPlayerStep;
60971/// @}
60972
60973
60974/*! @name AlphaFade
60975@{ */
60976/*!
60977@brief Turn on/off Alpha Fade
60978*/
60979bool alphaFadeEnable;
60980/*!
60981@brief Distance of start Alpha Fade
60982*/
60983float alphaFadeStart;
60984/*!
60985@brief Distance of end Alpha Fade
60986*/
60987float alphaFadeEnd;
60988/*!
60989@brief Invert Alpha Fade's Start & End Distance
60990*/
60991bool alphaFadeInverse;
60992/// @}
60993
60994
60995/*! @name Debug
60996@{ */
60997/*!
60998@brief Debug rendering mode shows the normals for each point in the TSStatic's mesh.
60999*/
61000float renderNormals;
61001/*!
61002@brief Forces rendering to a particular detail level.
61003*/
61004int forceDetail;
61005/// @}
61006
61007
61008/*! @name AFX
61009@{ */
61010/*!
61011*/
61012bool ignoreZodiacs;
61013/*!
61014*/
61015bool useGradientRange;
61016/*!
61017*/
61018Point2F gradientRange;
61019/*!
61020*/
61021bool invertGradientRange;
61022/// @}
61023
61024
61025/*! @name GameObject
61026@{ */
61027/// @}
61028
61029
61030/*! @name Transform
61031@{ */
61032/// @}
61033
61034
61035/*! @name Editing
61036@{ */
61037/// @}
61038
61039
61040/*! @name Mounting
61041@{ */
61042/// @}
61043
61044
61045/*! @name Ungrouped
61046@{ */
61047/// @}
61048
61049
61050/*! @name Object
61051@{ */
61052/// @}
61053
61054
61055/*! @name Editing
61056@{ */
61057/// @}
61058
61059
61060/*! @name Persistence
61061@{ */
61062/// @}
61063
61064};
61065
61066/*!
61067@brief An example scene object which renders a mesh.
61068
61069This class implements a basic SceneObject that can exist in the world at a 3D position and render itself. There are several valid ways to render an object in Torque. This class implements the preferred rendering method which is to submit a MeshRenderInst along with a Material, vertex buffer, primitive buffer, and transform and allow the RenderMeshMgr handle the actual setup and rendering for you.
61070
61071See the C++ code for implementation details.
61072
61073@ingroup Examples
61074
61075*/
61076class RenderMeshExample : public SceneObject {
61077public:
61078/*!
61079@brief A utility method for forcing a network update.
61080
61081*/
61082void postApply();
61083
61084/*! @name Callbacks
61085@{ */
61086/// @}
61087
61088/*!
61089@brief Disables rendering of all instances of this type.
61090
61091
61092@ingroup UNDOCUMENTED
61093*/
61094static bool isRenderable;
61095/*!
61096@brief Disables selection of all instances of this type.
61097
61098
61099@ingroup UNDOCUMENTED
61100*/
61101static bool isSelectable;
61102
61103/*! @name Rendering
61104@{ */
61105/*!
61106@brief °_è
61107*/
61108string MaterialFile;
61109/*!
61110@brief ðŒE 
61111*/
61112assetIdString MaterialAsset;
61113/// @}
61114
61115
61116/*! @name GameObject
61117@{ */
61118/// @}
61119
61120
61121/*! @name Transform
61122@{ */
61123/// @}
61124
61125
61126/*! @name Editing
61127@{ */
61128/// @}
61129
61130
61131/*! @name Mounting
61132@{ */
61133/// @}
61134
61135
61136/*! @name Ungrouped
61137@{ */
61138/// @}
61139
61140
61141/*! @name Object
61142@{ */
61143/// @}
61144
61145
61146/*! @name Editing
61147@{ */
61148/// @}
61149
61150
61151/*! @name Persistence
61152@{ */
61153/// @}
61154
61155};
61156
61157/*!
61158@brief Basic HUD clock. Displays the current simulation time offset from some base.
61159@tsexample
61160
61161 new GuiClockHud(){
61162   fillColor = "0.0 1.0 0.0 1.0"; // Fills with a solid green color
61163   frameColor = "1.0 1.0 1.0 1.0"; // Solid white frame color
61164   textColor = "1.0 1.0 1.0 1.0"; // Solid white text Color
61165   showFill = "true";
61166   showFrame = "true";
61167};
61168@endtsexample
61169
61170@ingroup GuiGame
61171
61172*/
61173class GuiClockHud : public GuiControl {
61174public:
61175/*!
61176@brief Sets the current base time for the clock.
61177
61178@param timeInSeconds Time to set the clock, in seconds (IE: 00:02 would be 120)
61179@tsexample
61180// Define the time, in seconds
61181%timeInSeconds = 120;
61182
61183// Change the time on the GuiClockHud control
61184%guiClockHud.setTime(%timeInSeconds);
61185@endtsexample
61186*/
61187void setTime( float timeInSeconds=60 );
61188/*!
61189@brief Sets a time for a countdown clock.
61190
61191Setting the time like this will cause the clock to count backwards from the specified time.
61192
61193@param timeInSeconds Time to set the clock, in seconds (IE: 00:02 would be 120)
61194
61195@see setTime*/
61196void setReverseTime( float timeInSeconds=60 );
61197/*!
61198@brief Returns the current time, in seconds.
61199
61200@return timeInseconds Current time, in seconds
61201@tsexample
61202// Get the current time from the GuiClockHud control
61203%timeInSeconds = %guiClockHud.getTime();
61204@endtsexample
61205*/
61206float getTime();
61207
61208/*! @name Callbacks
61209@{ */
61210/// @}
61211
61212
61213/*! @name Misc
61214@{ */
61215/*!
61216@brief If true, draws a background color behind the control.
61217*/
61218bool showFill;
61219/*!
61220@brief If true, draws a frame around the control.
61221*/
61222bool showFrame;
61223/*!
61224@brief Standard color for the background of the control.
61225*/
61226LinearColorF fillColor;
61227/*!
61228@brief Color for the control's frame.
61229*/
61230LinearColorF frameColor;
61231/*!
61232@brief Color for the text on this control.
61233*/
61234LinearColorF textColor;
61235/// @}
61236
61237
61238/*! @name Layout
61239@{ */
61240/// @}
61241
61242
61243/*! @name Control
61244@{ */
61245/// @}
61246
61247
61248/*! @name ToolTip
61249@{ */
61250/// @}
61251
61252
61253/*! @name Editing
61254@{ */
61255/// @}
61256
61257
61258/*! @name Localization
61259@{ */
61260/// @}
61261
61262
61263/*! @name Ungrouped
61264@{ */
61265/// @}
61266
61267
61268/*! @name Object
61269@{ */
61270/// @}
61271
61272
61273/*! @name Editing
61274@{ */
61275/// @}
61276
61277
61278/*! @name Persistence
61279@{ */
61280/// @}
61281
61282};
61283
61284/*!
61285@brief An emitter for lightning bolts.
61286
61287Lightning strike events are created on the server and transmitted to all clients to render the bolt. The strike may be followed by a random thunder sound. Player or Vehicle objects within the Lightning strike range can be hit and damaged by bolts.
61288@see LightningData
61289@ingroup FX
61290@ingroup Atmosphere
61291
61292*/
61293class Lightning : public GameBase {
61294public:
61295/*!
61296@brief Creates a LightningStrikeEvent that triggers harmless lightning bolts on all clients.
61297No objects will be damaged by these bolts.
61298@tsexample
61299// Generate a harmless lightning strike effect on all clients
61300%lightning.warningFlashes();
61301@endtsexample*/
61302void warningFlashes();
61303/*!
61304@brief Creates a LightningStrikeEvent which attempts to strike and damage a random object in range of the Lightning object.
61305
61306@tsexample
61307// Generate a damaging lightning strike effect on all clients
61308%lightning.strikeRandomPoint();
61309@endtsexample*/
61310void strikeRandomPoint();
61311/*!
61312@brief Creates a LightningStrikeEvent which strikes a specific object.
61313
61314@note This method is currently unimplemented.
61315*/
61316void strikeObject( ShapeBase pSB=nullAsType<ShapeBase*>() );
61317
61318/*! @name Callbacks
61319@{ */
61320/*!
61321@brief Informs an object that it was hit by a lightning bolt and needs to take damage.
61322
61323@param hitPosition World position hit by the lightning bolt.
61324@param hitNormal Surface normal at @a hitPosition.
61325@param hitObject Player or Vehicle object that was hit.
61326@tsexample
61327function Lightning::applyDamage( %this, %hitPosition, %hitNormal, %hitObject )
61328{
61329   // apply damage to the player
61330   %hitObject.applyDamage( 25 );
61331}
61332@endtsexample
61333*/
61334void applyDamage( Point3F hitPosition, Point3F hitNormal, SceneObject hitObject );
61335/// @}
61336
61337/*!
61338@brief Disables rendering of all instances of this type.
61339
61340
61341@ingroup UNDOCUMENTED
61342*/
61343static bool isRenderable;
61344/*!
61345@brief Disables selection of all instances of this type.
61346
61347
61348@ingroup UNDOCUMENTED
61349*/
61350static bool isSelectable;
61351
61352/*! @name Strikes
61353@{ */
61354/*!
61355@brief @brief Number of lightning strikes to perform per minute.
61356
61357
61358Automatically invokes strikeRandomPoint() at regular intervals.
61359*/
61360int strikesPerMinute;
61361/*!
61362@brief Width of a lightning bolt.
61363*/
61364float strikeWidth;
61365/*!
61366@brief @brief Horizontal size (XY plane) of the search box used to find and damage Player or Vehicle objects within range of the strike.
61367
61368
61369Only the object at highest altitude with a clear line of sight to the bolt will be hit.
61370*/
61371float strikeRadius;
61372/// @}
61373
61374
61375/*! @name Colors
61376@{ */
61377/*!
61378@brief Color to blend the strike texture with.
61379*/
61380LinearColorF color;
61381/*!
61382@brief @brief Color to blend the strike texture with when the bolt is fading away.
61383
61384
61385Bolts fade away automatically shortly after the strike occurs.
61386*/
61387LinearColorF fadeColor;
61388/// @}
61389
61390
61391/*! @name Bolts
61392@{ */
61393/*!
61394@brief Percentage chance (0-1) that a given lightning bolt will hit something.
61395*/
61396float chanceToHitTarget;
61397/*!
61398@brief @brief Radial distance from the center of the Lightning object for the start point of the bolt.
61399
61400
61401The actual start point will be a random point within this radius.
61402*/
61403float boltStartRadius;
61404/*!
61405@brief Controls whether lightning bolts are affected by fog when they are rendered.
61406*/
61407bool useFog;
61408/// @}
61409
61410
61411/*! @name Game
61412@{ */
61413/// @}
61414
61415
61416/*! @name GameObject
61417@{ */
61418/// @}
61419
61420
61421/*! @name Transform
61422@{ */
61423/// @}
61424
61425
61426/*! @name Editing
61427@{ */
61428/// @}
61429
61430
61431/*! @name Mounting
61432@{ */
61433/// @}
61434
61435
61436/*! @name Ungrouped
61437@{ */
61438/// @}
61439
61440
61441/*! @name Object
61442@{ */
61443/// @}
61444
61445
61446/*! @name Editing
61447@{ */
61448/// @}
61449
61450
61451/*! @name Persistence
61452@{ */
61453/// @}
61454
61455};
61456
61457/*!
61458@brief Contains information for how specific particles should look and react including particle colors, particle imagemap, acceleration value for individual particles and spin information.
61459@tsexample
61460datablock ParticleData( GLWaterExpSmoke )
61461{
61462   textureName = "art/shapes/particles/smoke";
61463   dragCoefficient = 0.4;
61464   gravityCoefficient = -0.25;
61465   inheritedVelFactor = 0.025;
61466   constantAcceleration = -1.1;
61467   lifetimeMS = 1250;
61468   lifetimeVarianceMS = 0;
61469   useInvAlpha = false;
61470   spinSpeed = 1;
61471   spinRandomMin = -200.0;
61472   spinRandomMax = 200.0;
61473
61474   colors[0] = "0.1 0.1 1.0 1.0";
61475   colors[1] = "0.4 0.4 1.0 1.0";
61476   colors[2] = "0.4 0.4 1.0 0.0";
61477
61478   sizes[0] = 2.0;
61479   sizes[1] = 6.0;
61480   sizes[2] = 2.0;
61481
61482   times[0] = 0.0;
61483   times[1] = 0.5;
61484   times[2] = 1.0;
61485};
61486@endtsexample
61487@ingroup FX
61488@see ParticleEmitter
61489@see ParticleEmitterData
61490@see ParticleEmitterNode
61491
61492*/
61493class ParticleData : public SimDataBlock {
61494public:
61495/*!
61496@brief Reloads this particle.
61497
61498@tsexample
61499// Get the editor's current particle
61500%particle = PE_ParticleEditor.currParticle
61501
61502// Change a particle value
61503%particle.setFieldValue( %propertyField, %value );
61504
61505// Reload it
61506%particle.reload();
61507@endtsexample
61508*/
61509void reload();
61510
61511/*! @name Callbacks
61512@{ */
61513/// @}
61514
61515/*!
61516@brief Particle physics drag amount.
61517*/
61518float dragCoefficient;
61519/*!
61520@brief Strength of wind on the particles.
61521*/
61522float windCoefficient;
61523/*!
61524@brief Strength of gravity on the particles.
61525*/
61526float gravityCoefficient;
61527/*!
61528@brief Amount of emitter velocity to add to particle initial velocity.
61529*/
61530float inheritedVelFactor;
61531/*!
61532@brief Constant acceleration to apply to this particle.
61533*/
61534float constantAcceleration;
61535/*!
61536@brief Time in milliseconds before this particle is destroyed.
61537*/
61538int lifetimeMS;
61539/*!
61540@brief Variance in lifetime of particle, from 0 - lifetimeMS.
61541*/
61542int lifetimeVarianceMS;
61543/*!
61544@brief Speed at which to spin the particle.
61545*/
61546float spinSpeed;
61547/*!
61548@brief Minimum allowed spin speed of this particle, between -1000 and spinRandomMax.
61549*/
61550float spinRandomMin;
61551/*!
61552@brief Maximum allowed spin speed of this particle, between spinRandomMin and 1000.
61553*/
61554float spinRandomMax;
61555/*!
61556@brief @brief Controls how particles blend with the scene.
61557
61558
61559If true, particles blend like ParticleBlendStyle NORMAL, if false, blend like ParticleBlendStyle ADDITIVE.
61560@note If ParticleEmitterData::blendStyle is set, it will override this value.
61561*/
61562bool useInvAlpha;
61563/*!
61564@brief If true, allow the particle texture to be an animated sprite.
61565*/
61566bool animateTexture;
61567/*!
61568@brief If animateTexture is true, this defines the frames per second of the sprite animation.
61569*/
61570int framesPerSec;
61571/*!
61572@brief @brief 4 element array defining the UV coords into textureName to use for this particle.
61573
61574
61575Coords should be set for the first tile only when using animTexTiling; coordinates for other tiles will be calculated automatically. "0 0" is top left and "1 1" is bottom right.
61576*/
61577Point2F textureCoords[ 4 ];
61578/*!
61579@brief @brief The number of frames, in rows and columns stored in textureName (when animateTexture is true).
61580
61581
61582A maximum of 256 frames can be stored in a single texture when using animTexTiling. Value should be "NumColumns NumRows", for example "4 4".
61583*/
61584Point2I animTexTiling;
61585/*!
61586@brief @brief A list of frames and/or frame ranges to use for particle animation if animateTexture is true.
61587
61588
61589Each frame token must be separated by whitespace. A frame token must be a positive integer frame number or a range of frame numbers separated with a '-'. The range separator, '-', cannot have any whitspace around it.
61590
61591Ranges can be specified to move through the frames in reverse as well as forward (eg. 19-14). Frame numbers exceeding the number of tiles will wrap.
61592@tsexample
61593animTexFrames = "0-16 20 19 18 17 31-21";
61594@endtsexample
61595
61596*/
61597string animTexFrames;
61598/*!
61599@brief Texture file to use for this particle.
61600*/
61601string textureName;
61602/*!
61603@brief @brief Texture file to use for this particle if animateTexture is true.
61604
61605
61606Deprecated. Use textureName instead.
61607*/
61608string animTexName;
61609/*!
61610@brief @brief Particle RGBA color keyframe values.
61611
61612
61613The particle color will linearly interpolate between the color/time keys over the lifetime of the particle.
61614*/
61615LinearColorF colors[ 8 ];
61616/*!
61617@brief @brief Particle size keyframe values.
61618
61619
61620The particle size will linearly interpolate between the size/time keys over the lifetime of the particle.
61621*/
61622float sizes[ 8 ];
61623/*!
61624@brief @brief Time keys used with the colors and sizes keyframes.
61625
61626
61627Values are from 0.0 (particle creation) to 1.0 (end of lifespace).
61628*/
61629float times[ 8 ];
61630
61631/*! @name AFX
61632@{ */
61633/*!
61634*/
61635filename textureExtName;
61636/*!
61637*/
61638bool constrainPos;
61639/*!
61640*/
61641float angle;
61642/*!
61643*/
61644float angleVariance;
61645/*!
61646*/
61647float sizeBias;
61648/*!
61649*/
61650float spinBias;
61651/*!
61652*/
61653bool randomizeSpinDir;
61654/// @}
61655
61656
61657/*! @name Ungrouped
61658@{ */
61659/// @}
61660
61661
61662/*! @name Object
61663@{ */
61664/// @}
61665
61666
61667/*! @name Editing
61668@{ */
61669/// @}
61670
61671
61672/*! @name Persistence
61673@{ */
61674/// @}
61675
61676};
61677
61678/*!
61679@brief A particle emitter object that can be positioned in the world and dynamically enabled or disabled.
61680
61681@tsexample
61682datablock ParticleEmitterNodeData( SimpleEmitterNodeData )
61683{
61684   timeMultiple = 1.0;
61685};
61686
61687%emitter = new ParticleEmitterNode()
61688{
61689   datablock = SimpleEmitterNodeData;
61690   active = true;
61691   emitter = FireEmitterData;
61692   velocity = 3.5;
61693};
61694
61695// Dynamically change emitter datablock
61696%emitter.setEmitterDataBlock( DustEmitterData );
61697@endtsexample
61698@note To change the emitter field dynamically (after the ParticleEmitterNode object has been created) you must use the setEmitterDataBlock() method or the change will not be replicated to other clients in the game.
61699Similarly, use the setActive() method instead of changing the active field directly. When changing velocity, you need to toggle setActive() on and off to force the state change to be transmitted to other clients.
61700
61701@ingroup FX
61702@see ParticleEmitterNodeData
61703@see ParticleEmitterData
61704
61705*/
61706class ParticleEmitterNode : public GameBase {
61707public:
61708/*!
61709@brief Assigns the datablock for this emitter node.
61710
61711@param emitterDatablock ParticleEmitterData datablock to assign
61712@tsexample
61713// Assign a new emitter datablock
61714%emitter.setEmitterDatablock( %emitterDatablock );
61715@endtsexample
61716*/
61717void setEmitterDataBlock( ParticleEmitterData emitterDatablock=nullAsType<ParticleEmitterData*>() );
61718/*!
61719@brief Turns the emitter on or off.
61720
61721@param active New emitter state
61722*/
61723void setActive( bool active );
61724
61725/*! @name Callbacks
61726@{ */
61727/// @}
61728
61729/*!
61730@brief Disables rendering of all instances of this type.
61731
61732
61733@ingroup UNDOCUMENTED
61734*/
61735static bool isRenderable;
61736/*!
61737@brief Disables selection of all instances of this type.
61738
61739
61740@ingroup UNDOCUMENTED
61741*/
61742static bool isSelectable;
61743/*!
61744@brief Controls whether particles are emitted from this node.
61745*/
61746bool active;
61747/*!
61748@brief Datablock to use when emitting particles.
61749*/
61750ParticleEmitterData emitter;
61751/*!
61752@brief Velocity to use when emitting particles (in the direction of the ParticleEmitterNode object's up (Z) axis).
61753*/
61754float velocity;
61755
61756/*! @name Game
61757@{ */
61758/// @}
61759
61760
61761/*! @name GameObject
61762@{ */
61763/// @}
61764
61765
61766/*! @name Transform
61767@{ */
61768/// @}
61769
61770
61771/*! @name Editing
61772@{ */
61773/// @}
61774
61775
61776/*! @name Mounting
61777@{ */
61778/// @}
61779
61780
61781/*! @name Ungrouped
61782@{ */
61783/// @}
61784
61785
61786/*! @name Object
61787@{ */
61788/// @}
61789
61790
61791/*! @name Editing
61792@{ */
61793/// @}
61794
61795
61796/*! @name Persistence
61797@{ */
61798/// @}
61799
61800};
61801
61802/*!
61803@brief Defines a precipitation based storm (rain, snow, etc).
61804
61805The Precipitation effect works by creating many 'drops' within a fixed size box. This box can be configured to move around with the camera (to simulate level-wide precipitation), or to remain in a fixed position (to simulate localized precipitation). When #followCam is true, the box containing the droplets can be thought of as centered on the camera then pushed slightly forward in the direction the camera is facing so most of the box is in front of the camera (allowing more drops to be visible on screen at once).
61806
61807The effect can also be configured to create a small 'splash' whenever a drop hits another world object.
61808
61809@tsexample
61810// The following is added to a level file (.mis) by the World Editor
61811new Precipitation( TheRain )
61812{
61813   dropSize = "0.5";
61814   splashSize = "0.5";
61815   splashMS = "250";
61816   animateSplashes = "1";
61817   dropAnimateMS = "0";
61818   fadeDist = "0";
61819   fadeDistEnd = "0";
61820   useTrueBillboards = "0";
61821   useLighting = "0";
61822   glowIntensity = "0 0 0 0";
61823   reflect = "0";
61824   rotateWithCamVel = "1";
61825   doCollision = "1";
61826   hitPlayers = "0";
61827   hitVehicles = "0";
61828   followCam = "1";
61829   useWind = "0";
61830   minSpeed = "1.5";
61831   maxSpeed = "2";
61832   minMass = "0.75";
61833   maxMass = "0.85";
61834   useTurbulence = "0";
61835   maxTurbulence = "0.1";
61836   turbulenceSpeed = "0.2";
61837   numDrops = "1024";
61838   boxWidth = "200";
61839   boxHeight = "100";
61840   dataBlock = "HeavyRain";
61841};
61842@endtsexample
61843@ingroup FX
61844@ingroup Atmosphere
61845@see PrecipitationData
61846
61847*/
61848class Precipitation : public GameBase {
61849public:
61850/*!
61851@brief Sets the maximum number of drops in the effect, as a percentage of #numDrops.
61852
61853The change occurs instantly (use modifyStorm() to change the number of drops over a period of time.
61854@param percentage New maximum number of drops value (as a percentage of #numDrops). Valid range is 0-1.
61855@tsexample
61856%percentage = 0.5;  // The percentage, from 0 to 1, of the maximum drops to display
61857%precipitation.setPercentage( %percentage );
61858@endtsexample
61859@see modifyStorm
61860*/
61861void setPercentage( float percentage=1.0f );
61862/*!
61863@brief Smoothly change the maximum number of drops in the effect (from current value to #numDrops * @a percentage).
61864
61865This method can be used to simulate a storm building or fading in intensity as the number of drops in the Precipitation box changes.
61866@param percentage New maximum number of drops value (as a percentage of #numDrops). Valid range is 0-1.
61867@param seconds Length of time (in seconds) over which to increase the drops percentage value. Set to 0 to change instantly.
61868@tsexample
61869%percentage = 0.5;  // The percentage, from 0 to 1, of the maximum drops to display
61870%seconds = 5.0;     // The length of time over which to make the change.
61871%precipitation.modifyStorm( %percentage, %seconds );
61872@endtsexample
61873*/
61874void modifyStorm( float percentage=1.0f, float seconds=5.0f );
61875/*!
61876@brief Smoothly change the turbulence parameters over a period of time.
61877
61878@param max New #maxTurbulence value. Set to 0 to disable turbulence.
61879@param speed New #turbulenceSpeed value.
61880@param seconds Length of time (in seconds) over which to interpolate the turbulence settings. Set to 0 to change instantly.
61881@tsexample
61882%turbulence = 0.5;     // Set the new turbulence value. Set to 0 to disable turbulence.
61883%speed = 5.0;          // The new speed of the turbulance effect.
61884%seconds = 5.0;        // The length of time over which to make the change.
61885%precipitation.setTurbulence( %turbulence, %speed, %seconds );
61886@endtsexample
61887*/
61888void setTurbulence( float max=1.0f, float speed=5.0f, float seconds=5.0f );
61889
61890/*! @name Callbacks
61891@{ */
61892/// @}
61893
61894/*!
61895@brief Disables rendering of all instances of this type.
61896
61897
61898@ingroup UNDOCUMENTED
61899*/
61900static bool isRenderable;
61901/*!
61902@brief Disables selection of all instances of this type.
61903
61904
61905@ingroup UNDOCUMENTED
61906*/
61907static bool isSelectable;
61908
61909/*! @name Precipitation
61910@{ */
61911/*!
61912@brief @brief Maximum number of drops allowed to exist in the precipitation box at any one time.
61913
61914
61915The actual number of drops in the effect depends on the current percentage, which can change over time using modifyStorm().
61916*/
61917int numDrops;
61918/*!
61919@brief Width and depth (horizontal dimensions) of the precipitation box.
61920*/
61921float boxWidth;
61922/*!
61923@brief Height (vertical dimension) of the precipitation box.
61924*/
61925float boxHeight;
61926/// @}
61927
61928
61929/*! @name Rendering
61930@{ */
61931/*!
61932@brief Size of each drop of precipitation. This will scale the texture.
61933*/
61934float dropSize;
61935/*!
61936@brief Size of each splash animation when a drop collides with another surface.
61937*/
61938float splashSize;
61939/*!
61940@brief Lifetime of splashes in milliseconds.
61941*/
61942int splashMS;
61943/*!
61944@brief Set to true to enable splash animations when drops collide with other surfaces.
61945*/
61946bool animateSplashes;
61947/*!
61948@brief @brief Length (in milliseconds) to display each drop frame.
61949
61950
61951If #dropAnimateMS <= 0, drops select a single random frame at creation that does not change throughout the drop's lifetime. If #dropAnimateMS > 0, each drop cycles through the the available frames in the drop texture at the given rate.
61952*/
61953int dropAnimateMS;
61954/*!
61955@brief The distance at which drops begin to fade out.
61956*/
61957float fadeDist;
61958/*!
61959@brief The distance at which drops are completely faded out.
61960*/
61961float fadeDistEnd;
61962/*!
61963@brief Set to true to make drops true (non axis-aligned) billboards.
61964*/
61965bool useTrueBillboards;
61966/*!
61967@brief Set to true to enable shading of the drops and splashes by the sun color.
61968*/
61969bool useLighting;
61970/*!
61971@brief Set to 0 to disable the glow or or use it to control the intensity of each channel.
61972*/
61973LinearColorF glowIntensity;
61974/*!
61975@brief @brief This enables precipitation rendering during reflection passes.
61976
61977
61978@note This is expensive.
61979*/
61980bool reflect;
61981/*!
61982@brief Set to true to include the camera velocity when calculating drop rotation speed.
61983*/
61984bool rotateWithCamVel;
61985/// @}
61986
61987
61988/*! @name Collision
61989@{ */
61990/*!
61991@brief @brief Allow drops to collide with world objects.
61992
61993
61994If #animateSplashes is true, drops that collide with another object will produce a simple splash animation.
61995@note This can be expensive as each drop will perform a raycast when it is created to determine where it will hit.
61996*/
61997bool doCollision;
61998/*!
61999@brief Allow drops to collide with Player objects; only valid if #doCollision is true.
62000*/
62001bool hitPlayers;
62002/*!
62003@brief Allow drops to collide with Vehicle objects; only valid if #doCollision is true.
62004*/
62005bool hitVehicles;
62006/// @}
62007
62008
62009/*! @name Movement
62010@{ */
62011/*!
62012@brief @brief Controls whether the Precipitation system follows the camera or remains where it is first placed in the scene.
62013
62014
62015Set to true to make it seem like it is raining everywhere in the level (ie. the Player will always be in the rain). Set to false to have a single area affected by rain (ie. the Player can move in and out of the rainy area).
62016*/
62017bool followCam;
62018/*!
62019@brief Controls whether drops are affected by wind.
62020
62021@see ForestWindEmitter
62022*/
62023bool useWind;
62024/*!
62025@brief @brief Minimum speed at which a drop will fall.
62026
62027
62028On creation, the drop will be assigned a random speed between #minSpeed and #maxSpeed.
62029*/
62030float minSpeed;
62031/*!
62032@brief @brief Maximum speed at which a drop will fall.
62033
62034
62035On creation, the drop will be assigned a random speed between #minSpeed and #maxSpeed.
62036*/
62037float maxSpeed;
62038/*!
62039@brief @brief Minimum mass of a drop.
62040
62041
62042Drop mass determines how strongly the drop is affected by wind and turbulence. On creation, the drop will be assigned a random speed between #minMass and #minMass.
62043*/
62044float minMass;
62045/*!
62046@brief @brief Maximum mass of a drop.
62047
62048
62049Drop mass determines how strongly the drop is affected by wind and turbulence. On creation, the drop will be assigned a random speed between #minMass and #minMass.
62050*/
62051float maxMass;
62052/// @}
62053
62054
62055/*! @name Turbulence
62056@{ */
62057/*!
62058@brief Check to enable turbulence. This causes precipitation drops to spiral while falling.
62059*/
62060bool useTurbulence;
62061/*!
62062@brief Radius at which precipitation drops spiral when turbulence is enabled.
62063*/
62064float maxTurbulence;
62065/*!
62066@brief Speed at which precipitation drops spiral when turbulence is enabled.
62067*/
62068float turbulenceSpeed;
62069/// @}
62070
62071
62072/*! @name Game
62073@{ */
62074/// @}
62075
62076
62077/*! @name GameObject
62078@{ */
62079/// @}
62080
62081
62082/*! @name Transform
62083@{ */
62084/// @}
62085
62086
62087/*! @name Editing
62088@{ */
62089/// @}
62090
62091
62092/*! @name Mounting
62093@{ */
62094/// @}
62095
62096
62097/*! @name Ungrouped
62098@{ */
62099/// @}
62100
62101
62102/*! @name Object
62103@{ */
62104/// @}
62105
62106
62107/*! @name Editing
62108@{ */
62109/// @}
62110
62111
62112/*! @name Persistence
62113@{ */
62114/// @}
62115
62116};
62117
62118/*!
62119
62120@ingroup UNDOCUMENTED
62121
62122*/
62123class RibbonNode : public GameBase {
62124public:
62125/*!
62126@brief Assigns the datablock for this ribbon node.
62127
62128@param ribbonDatablock RibbonData datablock to assign
62129@tsexample
62130// Assign a new emitter datablock
62131%emitter.setRibbonDatablock( %ribbonDatablock );
62132@endtsexample
62133*/
62134void setRibbonDatablock( RibbonData ribbonDatablock=nullAsType<RibbonData*>() );
62135/*!
62136@brief Turns the ribbon on or off.
62137
62138@param active New ribbon state
62139*/
62140void setActive( bool active );
62141
62142/*! @name Callbacks
62143@{ */
62144/// @}
62145
62146/*!
62147@brief Disables rendering of all instances of this type.
62148
62149
62150@ingroup UNDOCUMENTED
62151*/
62152static bool isRenderable;
62153/*!
62154@brief Disables selection of all instances of this type.
62155
62156
62157@ingroup UNDOCUMENTED
62158*/
62159static bool isSelectable;
62160/*!
62161@brief Controls whether ribbon is emitted from this node.
62162*/
62163bool active;
62164/*!
62165@brief Datablock to use for the ribbon.
62166*/
62167RibbonData Ribbon;
62168
62169/*! @name Game
62170@{ */
62171/// @}
62172
62173
62174/*! @name GameObject
62175@{ */
62176/// @}
62177
62178
62179/*! @name Transform
62180@{ */
62181/// @}
62182
62183
62184/*! @name Editing
62185@{ */
62186/// @}
62187
62188
62189/*! @name Mounting
62190@{ */
62191/// @}
62192
62193
62194/*! @name Ungrouped
62195@{ */
62196/// @}
62197
62198
62199/*! @name Object
62200@{ */
62201/// @}
62202
62203
62204/*! @name Editing
62205@{ */
62206/// @}
62207
62208
62209/*! @name Persistence
62210@{ */
62211/// @}
62212
62213};
62214
62215/*!
62216@brief A flying vehicle.
62217
62218@ingroup Vehicles
62219
62220*/
62221class FlyingVehicle : public Vehicle {
62222public:
62223/*!
62224@brief Set whether the vehicle should temporarily use the createHoverHeight specified in the datablock.
62225
62226This can help avoid problems with spawning.
62227@param enabled true to use the datablock createHoverHeight, false otherwise*/
62228void useCreateHeight( bool enabled );
62229
62230/*! @name Callbacks
62231@{ */
62232/// @}
62233
62234/*!
62235@brief Disables rendering of all instances of this type.
62236
62237
62238@ingroup UNDOCUMENTED
62239*/
62240static bool isRenderable;
62241/*!
62242@brief Disables selection of all instances of this type.
62243
62244
62245@ingroup UNDOCUMENTED
62246*/
62247static bool isSelectable;
62248
62249/*! @name Game
62250@{ */
62251/// @}
62252
62253
62254/*! @name GameObject
62255@{ */
62256/// @}
62257
62258
62259/*! @name Transform
62260@{ */
62261/// @}
62262
62263
62264/*! @name Editing
62265@{ */
62266/// @}
62267
62268
62269/*! @name Mounting
62270@{ */
62271/// @}
62272
62273
62274/*! @name Ungrouped
62275@{ */
62276/// @}
62277
62278
62279/*! @name Object
62280@{ */
62281/// @}
62282
62283
62284/*! @name Editing
62285@{ */
62286/// @}
62287
62288
62289/*! @name Persistence
62290@{ */
62291/// @}
62292
62293};
62294
62295/*!
62296@brief A wheeled vehicle.
62297@ingroup Vehicles
62298
62299*/
62300class WheeledVehicle : public Vehicle {
62301public:
62302/*!
62303@brief Set how much the wheel is affected by steering.
62304
62305The steering factor controls how much the wheel is rotated by the vehicle steering. For example, most cars would have their front wheels set to 1.0, and their rear wheels set to 0 since only the front wheels should turn.
62306
62307Negative values will turn the wheel in the opposite direction to the steering angle.
62308@param wheel index of the wheel to set (hub node #)
62309@param steering steering factor from -1 (full inverse) to 1 (full)
62310@return true if successful, false if failed*/
62311bool setWheelSteering( int wheel, float steering );
62312/*!
62313@brief Set whether the wheel is powered (has torque applied from the engine).
62314
62315A rear wheel drive car for example would set the front wheels to false, and the rear wheels to true.
62316@param wheel index of the wheel to set (hub node #)
62317@param powered flag indicating whether to power the wheel or not
62318@return true if successful, false if failed*/
62319bool setWheelPowered( int wheel, bool powered );
62320/*!
62321@brief Set the WheeledVehicleTire datablock for this wheel.
62322@param wheel index of the wheel to set (hub node #)
62323@param tire WheeledVehicleTire datablock
62324@return true if successful, false if failed
62325
62326@tsexample
62327%obj.setWheelTire( 0, FrontTire );
62328@endtsexample*/
62329bool setWheelTire( int wheel, WheeledVehicleTire tire );
62330/*!
62331@brief Set the WheeledVehicleSpring datablock for this wheel.
62332@param wheel index of the wheel to set (hub node #)
62333@param spring WheeledVehicleSpring datablock
62334@return true if successful, false if failed
62335
62336@tsexample
62337%obj.setWheelSpring( 0, FrontSpring );
62338@endtsexample*/
62339bool setWheelSpring( int wheel, WheeledVehicleSpring spring );
62340/*!
62341@brief Get the number of wheels on this vehicle.
62342@return the number of wheels (equal to the number of hub nodes defined in the model)*/
62343int getWheelCount();
62344
62345/*! @name Callbacks
62346@{ */
62347/// @}
62348
62349/*!
62350@brief Disables rendering of all instances of this type.
62351
62352
62353@ingroup UNDOCUMENTED
62354*/
62355static bool isRenderable;
62356/*!
62357@brief Disables selection of all instances of this type.
62358
62359
62360@ingroup UNDOCUMENTED
62361*/
62362static bool isSelectable;
62363
62364/*! @name Game
62365@{ */
62366/// @}
62367
62368
62369/*! @name GameObject
62370@{ */
62371/// @}
62372
62373
62374/*! @name Transform
62375@{ */
62376/// @}
62377
62378
62379/*! @name Editing
62380@{ */
62381/// @}
62382
62383
62384/*! @name Mounting
62385@{ */
62386/// @}
62387
62388
62389/*! @name Ungrouped
62390@{ */
62391/// @}
62392
62393
62394/*! @name Object
62395@{ */
62396/// @}
62397
62398
62399/*! @name Editing
62400@{ */
62401/// @}
62402
62403
62404/*! @name Persistence
62405@{ */
62406/// @}
62407
62408};
62409
62410/*!
62411@brief Defines the properties of a PhysicsDebris object.
62412
62413@see PhysicsDebris.
62414@ingroup Physics
62415*/
62416class PhysicsDebrisData : public GameBaseData {
62417public:
62418/*!
62419@brief Loads some information to have readily available at simulation time.
62420
62421Forces generation of shaders, materials, and other data used by the %PhysicsDebris object. This function should be used while a level is loading in order to shorten the amount of time to create a PhysicsDebris in game.*/
62422void preload();
62423
62424/*! @name Callbacks
62425@{ */
62426/// @}
62427
62428
62429/*! @name Display
62430@{ */
62431/*!
62432@brief @brief Path to the .DAE or .DTS file to use for this shape.
62433
62434
62435Compatable with Live-Asset Reloading.
62436*/
62437filename shapeFile;
62438/*!
62439@brief @brief Determines if the shape's shadow should be cast onto the environment.
62440
62441
62442
62443*/
62444bool castShadows;
62445/// @}
62446
62447
62448/*! @name Physical Properties
62449@{ */
62450/*!
62451@brief @brief Base time, in seconds, that debris persists after time of creation.
62452
62453
62454@note A %PhysicsDebris' lifetime multiplied by it's $pref::PhysicsDebris::lifetimeScale must be equal to or greater than 1.0.
62455
62456
62457*/
62458float lifetime;
62459/*!
62460@brief @brief Range of variation randomly applied to lifetime when debris is created.
62461
62462
62463Represents the maximum amount of seconds that will be added or subtracted to a shape's base lifetime. A value of 0 will apply the same lifetime to each shape created.
62464
62465
62466*/
62467float lifetimeVariance;
62468/*!
62469@brief @brief Value representing the mass of the shape.
62470
62471
62472A shape's mass influences the magnitude of any force applied to it. @note All PhysicsDebris objects are dynamic.
62473*/
62474float mass;
62475/*!
62476@brief @brief Coefficient of kinetic %friction to be applied to the shape.
62477
62478
62479Kinetic %friction reduces the velocity of a moving object while it is in contact with a surface. A larger coefficient will result in a larger reduction in velocity. A shape's friction should be smaller than it's staticFriction, but greater than 0.
62480
62481@note This value is only applied while an object is in motion. For an object starting at rest, see PhysicsDebrisData::staticFriction
62482*/
62483float friction;
62484/*!
62485@brief @brief Coefficient of static %friction to be applied to the shape.
62486
62487
62488Static %friction determines the force needed to start moving an at-rest object in contact with a surface. If the force applied onto shape cannot overcome the force of static %friction, the shape will remain at rest. A higher coefficient will require a larger force to start motion. This value should be both greater than 0 and the PhysicsDebrisData::friction.
62489
62490@note This value is only applied while an object is at rest. For an object in motion, see PhysicsDebrisData::friction
62491*/
62492float staticFriction;
62493/*!
62494@brief @brief Bounce coeffecient applied to the shape in response to a collision.
62495
62496
62497Restitution is a ratio of a shape's velocity before and after a collision. A value of 0 will zero out a shape's post-collision velocity, making it stop on contact. Larger values will remove less velocity after a collision, making it 'bounce' with greater force. Normal %restitution values range between 0 and 1.0.@note Values near or equaling 1.0 are likely to cause undesirable results in the physics simulation. Because of this, it is reccomended to avoid values close to 1.0
62498*/
62499float restitution;
62500/*!
62501@brief @brief Value that reduces an object's linear velocity over time.
62502
62503
62504Larger values will cause velocity to decay quicker.
62505
62506
62507*/
62508float linearDamping;
62509/*!
62510@brief @brief Value that reduces an object's rotational velocity over time.
62511
62512
62513Larger values will cause velocity to decay quicker.
62514
62515
62516*/
62517float angularDamping;
62518/*!
62519@brief @brief Minimum linear velocity before the shape can be put to sleep.
62520
62521
62522This should be a positive value. Shapes put to sleep will not be simulated in order to save system resources.
62523
62524@note The shape must be dynamic.
62525*/
62526float linearSleepThreshold;
62527/*!
62528@brief @brief Minimum rotational velocity before the shape can be put to sleep.
62529
62530
62531This should be a positive value. Shapes put to sleep will not be simulated in order to save system resources.
62532
62533@note The shape must be dynamic.
62534*/
62535float angularSleepThreshold;
62536/*!
62537@brief @brief Scale to apply to linear and angular dampening while underwater.
62538
62539
62540 @see angularDamping linearDamping
62541*/
62542float waterDampingScale;
62543/*!
62544@brief @brief The density of this shape for purposes of calculating buoyant forces.
62545
62546
62547The result of the calculated buoyancy is relative to the density of the WaterObject the PhysicsDebris is within.@see WaterObject::density
62548*/
62549float buoyancyDensity;
62550/// @}
62551
62552
62553/*! @name Scripting
62554@{ */
62555/// @}
62556
62557
62558/*! @name Ungrouped
62559@{ */
62560/// @}
62561
62562
62563/*! @name Object
62564@{ */
62565/// @}
62566
62567
62568/*! @name Editing
62569@{ */
62570/// @}
62571
62572
62573/*! @name Persistence
62574@{ */
62575/// @}
62576
62577};
62578
62579/*!
62580@brief Creates a physics-based impulse effect from a defined central point and magnitude.
62581
62582@see RadialImpulseEvent::send
62583@ingroup Physics
62584
62585*/
62586class RadialImpulseEvent {
62587public:
62588/*!
62589@brief Applies a radial impulse to any SceneObjects within the area of effect.
62590
62591This event is performed both server and client-side.
62592
62593@param position Center point for this radial impulse.
62594@param radius Distance from the position for this radial impulse to affect.
62595@param magnitude The force applied to objects within the radius from the position of this radial impulse effect.
62596
62597@tsexample
62598// Define the Position
62599%position = "10.0 15.0 10.0";
62600
62601// Define the Radius
62602%radius = "25.0";
62603
62604// Define the Magnitude
62605%magnitude = "30.0"
62606
62607// Create a globalRadialImpulse physics effect.
62608RadialImpulseEvent::send(%position,%radius,%magnitude);
62609@endtsexample*/
62610static void send( string inPosition="1.0 1.0 1.0", float radius=10.0f, float magnitude=20.0f );
62611
62612/*! @name Callbacks
62613@{ */
62614/// @}
62615
62616};
62617
62618/*!
62619@brief Helper object for gameplay physical forces.
62620
62621%PhysicsForces can be created and "attached" to other @link PhysicsBody PhysicsBodies@endlink to attract them to the position of the PhysicsForce.@ingroup Physics
62622
62623*/
62624class PhysicsForce : public SceneObject {
62625public:
62626/*!
62627@brief Attempts to associate the PhysicsForce with a PhysicsBody.
62628
62629Performs a physics ray cast of the provided length and direction. The %PhysicsForce will attach itself to the first dynamic PhysicsBody the ray collides with. On every tick, the attached body will be attracted towards the position of the %PhysicsForce.
62630
62631A %PhysicsForce can only be attached to one body at a time.
62632
62633@note To determine if an %attach was successful, check isAttached() immediately after calling this function.n*/
62634void attach( Point3F start, Point3F direction, float maxDist );
62635/*!
62636@brief Disassociates the PhysicsForce from any attached PhysicsBody.
62637
62638@param force Optional force to apply to the attached PhysicsBody before detaching.
62639
62640@note Has no effect if the %PhysicsForce is not attached to anything.*/
62641void detach( Point3F force=Point3F::Zero );
62642/*!
62643@brief Returns true if the %PhysicsForce is currently attached to an object.
62644
62645@see PhysicsForce::attach()*/
62646bool isAttached();
62647
62648/*! @name Callbacks
62649@{ */
62650/// @}
62651
62652/*!
62653@brief Disables rendering of all instances of this type.
62654
62655
62656@ingroup UNDOCUMENTED
62657*/
62658static bool isRenderable;
62659/*!
62660@brief Disables selection of all instances of this type.
62661
62662
62663@ingroup UNDOCUMENTED
62664*/
62665static bool isSelectable;
62666
62667/*! @name GameObject
62668@{ */
62669/// @}
62670
62671
62672/*! @name Transform
62673@{ */
62674/// @}
62675
62676
62677/*! @name Editing
62678@{ */
62679/// @}
62680
62681
62682/*! @name Mounting
62683@{ */
62684/// @}
62685
62686
62687/*! @name Ungrouped
62688@{ */
62689/// @}
62690
62691
62692/*! @name Object
62693@{ */
62694/// @}
62695
62696
62697/*! @name Editing
62698@{ */
62699/// @}
62700
62701
62702/*! @name Persistence
62703@{ */
62704/// @}
62705
62706};
62707
62708/*!
62709@brief Represents a destructible physical object simulated through the plugin system.
62710
62711@see PhysicsShapeData.
62712@ingroup Physics
62713*/
62714class PhysicsShape : public GameBase {
62715public:
62716/*!
62717@brief Returns if a PhysicsShape has been destroyed or not.*/
62718bool isDestroyed();
62719/*!
62720@brief Disables rendering and physical simulation.
62721
62722Calling destroy() will also spawn any explosions, debris, and/or destroyedShape defined for it, as well as remove it from the scene graph.
62723
62724Destroyed objects are only created on the server. Ghosting will later update the client.
62725
62726@note This does not actually delete the PhysicsShape.*/
62727void destroy();
62728/*!
62729@brief Restores the shape to its state before being destroyed.
62730
62731Re-enables rendering and physical simulation on the object and adds it to the client's scene graph. Has no effect if the shape is not destroyed.*/
62732void restore();
62733/*!
62734@brief Add a torque to a dynamic physics shape.
62735
62736@param torque to apply to the dynamic physics shape
62737@note This value is ignored on physics shapes that are not dynamic. Wakes up the dynamic physics shape if it is sleeping.*/
62738void applyTorque( Point3F torque );
62739/*!
62740@brief Add a force to a dynamic physics shape.
62741
62742@param force to apply to the dynamic physics shape
62743@note This value is ignored on physics shapes that are not dynamic. Wakes up the dynamic physics shape if it is sleeping.*/
62744void applyForce( Point3F force );
62745
62746/*! @name Callbacks
62747@{ */
62748/// @}
62749
62750/*!
62751@brief Determines if the shape will recieve corrections from the server or will instead be allowed to diverge.
62752
62753In the event that the client and server object positions/orientations differ and if this variable is true, the server will attempt to 'correct' the client object to keep it in sync. Otherwise, client and server objects may fall out of sync.
62754
62755
62756@ingroup UNDOCUMENTED
62757*/
62758static bool noCorrections;
62759/*!
62760@brief Determines if client-side shapes will attempt to smoothly transition to their new position after reciving a correction.
62761
62762If true, shapes will immediately render at the position they are corrected to.
62763
62764
62765@ingroup UNDOCUMENTED
62766*/
62767static bool noSmoothing;
62768/*!
62769@brief Disables rendering of all instances of this type.
62770
62771
62772@ingroup UNDOCUMENTED
62773*/
62774static bool isRenderable;
62775/*!
62776@brief Disables selection of all instances of this type.
62777
62778
62779@ingroup UNDOCUMENTED
62780*/
62781static bool isSelectable;
62782
62783/*! @name PhysicsShape
62784@{ */
62785/*!
62786@brief @brief Enables or disables playing of an ambient animation upon loading the shape.
62787
62788
62789@note The ambient animation must be named "ambient".
62790*/
62791bool playAmbient;
62792/// @}
62793
62794
62795/*! @name Game
62796@{ */
62797/// @}
62798
62799
62800/*! @name GameObject
62801@{ */
62802/// @}
62803
62804
62805/*! @name Transform
62806@{ */
62807/// @}
62808
62809
62810/*! @name Editing
62811@{ */
62812/// @}
62813
62814
62815/*! @name Mounting
62816@{ */
62817/// @}
62818
62819
62820/*! @name Ungrouped
62821@{ */
62822/// @}
62823
62824
62825/*! @name Object
62826@{ */
62827/// @}
62828
62829
62830/*! @name Editing
62831@{ */
62832/// @}
62833
62834
62835/*! @name Persistence
62836@{ */
62837/// @}
62838
62839};
62840
62841/*!
62842@brief A datablock describing an individual decal.
62843
62844The textures defined by the decal Material can be divided into multiple rectangular sub-textures as shown below, with a different sub-texture selected by all decals using the same DecalData (via #frame) or each decal instance (via #randomize).
62845@image html images/decal_example.png "Example of a Decal imagemap"
62846@tsexample
62847datablock DecalData(BulletHoleDecal)
62848{
62849   material = "DECAL_BulletHole";
62850   size = "5.0";
62851   lifeSpan = "50000";
62852   randomize = "1";
62853   texRows = "2";
62854   texCols = "2";
62855   clippingAngle = "60";
62856};
62857@endtsexample
62858
62859@see Decals
62860@ingroup Decals
62861@ingroup FX
62862
62863*/
62864class DecalData : public SimDataBlock {
62865public:
62866/*!
62867@brief Recompute the imagemap sub-texture rectangles for this DecalData.
62868
62869@tsexample
62870// Inform the decal object to reload its imagemap and frame data.
62871%decalData.texRows = 4;
62872%decalData.postApply();
62873@endtsexample
62874*/
62875void postApply();
62876
62877/*! @name Callbacks
62878@{ */
62879/// @}
62880
62881
62882/*! @name Decal
62883@{ */
62884/*!
62885@brief Width and height of the decal in meters before scale is applied.
62886*/
62887float size;
62888/*!
62889@brief Material to use for this decal.
62890*/
62891string Material;
62892/*!
62893@brief Time (in milliseconds) before this decal will be automatically deleted.
62894*/
62895int lifeSpan;
62896/*!
62897@brief @brief Time (in milliseconds) over which to fade out the decal before deleting it at the end of its lifetime.
62898
62899
62900@see lifeSpan
62901*/
62902int fadeTime;
62903/// @}
62904
62905
62906/*! @name Rendering
62907@{ */
62908/*!
62909@brief @brief LOD value - size in pixels at which decals of this type begin to fade out.
62910
62911
62912This should be a larger value than #fadeEndPixelSize. However, you may also set this to a negative value to disable lod-based fading.
62913*/
62914float fadeStartPixelSize;
62915/*!
62916@brief @brief LOD value - size in pixels at which decals of this type are fully faded out.
62917
62918
62919This should be a smaller value than #fadeStartPixelSize.
62920*/
62921float fadeEndPixelSize;
62922/*!
62923@brief Default renderPriority for decals of this type (determines draw order when decals overlap).
62924*/
62925char renderPriority;
62926/*!
62927@brief The angle in degrees used to clip geometry that faces away from the decal projection direction.
62928*/
62929float clippingAngle;
62930/// @}
62931
62932
62933/*! @name Texturing
62934@{ */
62935/*!
62936@brief Index of the texture rectangle within the imagemap to use for this decal.
62937*/
62938int frame;
62939/*!
62940@brief If true, a random frame from the imagemap is selected for each instance of the decal.
62941*/
62942bool randomize;
62943/*!
62944@brief Number of individual frames in the imagemap (maximum 16).
62945*/
62946int textureCoordCount;
62947/*!
62948@brief @brief Number of rows in the supplied imagemap.
62949
62950
62951Use #texRows and #texCols if the imagemap frames are arranged in a grid; use #textureCoords to manually specify UV coordinates for irregular sized frames.
62952*/
62953int texRows;
62954/*!
62955@brief @brief Number of columns in the supplied imagemap.
62956
62957
62958Use #texRows and #texCols if the imagemap frames are arranged in a grid; use #textureCoords to manually specify UV coordinates for irregular sized frames.
62959*/
62960int texCols;
62961/*!
62962@brief @brief An array of RectFs (topleft.x topleft.y extent.x extent.y) representing the UV coordinates for each frame in the imagemap.
62963
62964
62965@note This field should only be set if the imagemap frames are irregular in size. Otherwise use the #texRows and #texCols fields and the UV coordinates will be calculated automatically.
62966*/
62967RectF textureCoords[ 16 ];
62968/// @}
62969
62970
62971/*! @name Ungrouped
62972@{ */
62973/// @}
62974
62975
62976/*! @name Object
62977@{ */
62978/// @}
62979
62980
62981/*! @name Editing
62982@{ */
62983/// @}
62984
62985
62986/*! @name Persistence
62987@{ */
62988/// @}
62989
62990};
62991
62992/*!
62993@brief An invisible 3D object that emits sound.
62994
62995Sound emitters are used to place sounds in the level.  They are full 3D objects with their own position and orientation and when assigned 3D sounds, the transform and velocity of the sound emitter object will be applied to the 3D sound.
62996
62997Sound emitters can be set up of in either of two ways:
62998<ul>
62999<li><p>By assigning an existing SFXTrack to the emitter's #track property.</p>
63000<p>In this case the general sound setup (3D, streaming, looping, etc.) will be taken from #track.  However, the emitter's own properties will still override their corresponding properties in the #track's SFXDescription.</p></li>
63001<li><p>By directly assigning a sound file to the emitter's #fileName property.</p>
63002<p>In this case, the sound file will be set up for playback according to the properties defined on the emitter.</p>
63003</ul>
63004
63005Using #playOnAdd emitters can be configured to start playing immediately when they are added to the system (e.g. when the level objects are loaded from the mission file).
63006
63007@note A sound emitter need not necessarily emit a 3D sound.  Instead, sound emitters may also be used to play non-positional sounds.  For placing background audio to a level, however, it is usually easier to use LevelInfo::soundAmbience.
63008
63009@section SFXEmitter_networking Sound Emitters and Networking
63010
63011It is important to be aware of the fact that sounds will only play client-side whereas SFXEmitter objects are server-side entities.  This means that a server-side object has no connection to the actual sound playing on the client.  It is thus not possible for the server-object to perform queries about playback status and other source-related properties as these may in fact differ from client to client.
63012
63013@ingroup SFX
63014
63015*/
63016class SFXEmitter : public SceneObject {
63017public:
63018/*!
63019@brief Manually start playback of the emitter's sound.
63020
63021If this is called on the server-side object, the play command will be related to all client-side ghosts.
63022*/
63023void play();
63024/*!
63025@brief Manually stop playback of the emitter's sound.
63026
63027If this is called on the server-side object, the stop command will be related to all client-side ghosts.
63028*/
63029void stop();
63030/*!
63031@brief Get the sound source object from the emitter.
63032
63033
63034@return The sound source used by the emitter or null.@note This method will return null when called on the server-side SFXEmitter object.  Only client-side ghosts actually hold on to %SFXSources.
63035
63036*/
63037SFXSource getSource();
63038
63039/*! @name Callbacks
63040@{ */
63041/// @}
63042
63043/*!
63044@brief Whether to render enhanced range feedback in the editor on all emitters regardless of selection state.
63045
63046@ingroup SFX
63047*/
63048static bool renderEmitters;
63049/*!
63050@brief The distance between individual points in the sound emitter rendering in the editor as the points move from the emitter's center away to maxDistance.
63051
63052@ingroup SFX
63053*/
63054static float renderPointDistance;
63055/*!
63056@brief The stepping (in degrees) for the radial sweep along the axis of the XY plane sweep for sound emitter rendering in the editor.
63057
63058@ingroup SFX
63059*/
63060static float renderRadialIncrements;
63061/*!
63062@brief The stepping (in degrees) for the radial sweep on the XY plane for sound emitter rendering in the editor.
63063
63064@ingroup SFX
63065*/
63066static float renderSweepIncrements;
63067/*!
63068@brief The color with which to render a sound emitter's marker cube in the editor when the emitter's sound is playing and in range of the listener.
63069
63070@ingroup SFX
63071*/
63072static ColorI renderColorPlayingInRange;
63073/*!
63074@brief The color with which to render a sound emitter's marker cube in the editor when the emitter's sound is playing but out of the range of the listener.
63075
63076@ingroup SFX
63077*/
63078static ColorI renderColorPlayingOutOfRange;
63079/*!
63080@brief The color with which to render a sound emitter's marker cube in the editor when the emitter's sound is not playing but the emitter is in range of the listener.
63081
63082@ingroup SFX
63083*/
63084static ColorI renderColorStoppedInRange;
63085/*!
63086@brief The color with which to render a sound emitter's marker cube in the editor when the emitter's sound is not playing and the emitter is out of range of the listener.
63087
63088@ingroup SFX
63089*/
63090static ColorI renderColorStoppedOutOfRange;
63091/*!
63092@brief The color with which to render dots in the inner sound cone (Editor only).
63093
63094@ingroup SFX
63095*/
63096static ColorI renderColorInnerCone;
63097/*!
63098@brief The color with which to render dots in the outer sound cone (Editor only).
63099
63100@ingroup SFX
63101*/
63102static ColorI renderColorOuterCone;
63103/*!
63104@brief The color with which to render dots outside of the outer sound cone (Editor only).
63105
63106@ingroup SFX
63107*/
63108static ColorI renderColorOutsideVolume;
63109/*!
63110@brief The color of the range sphere with which to render sound emitters in the editor.
63111
63112@ingroup SFX
63113*/
63114static ColorI renderColorRangeSphere;
63115/*!
63116@brief Disables rendering of all instances of this type.
63117
63118
63119@ingroup UNDOCUMENTED
63120*/
63121static bool isRenderable;
63122/*!
63123@brief Disables selection of all instances of this type.
63124
63125
63126@ingroup UNDOCUMENTED
63127*/
63128static bool isSelectable;
63129
63130/*! @name Media
63131@{ */
63132/*!
63133@brief The track which the emitter should play.
63134
63135@note If assigned, this field will take precedence over a #fileName that may also be assigned to the emitter.
63136*/
63137SFXTrack track;
63138/*!
63139@brief The sound file to play.
63140
63141Use @b either this property @b or #track.  If both are assigned, #track takes precendence.  The primary purpose of this field is to avoid the need for the user to define SFXTrack datablocks for all sounds used in a level.
63142*/
63143filename fileName;
63144/// @}
63145
63146
63147/*! @name Sound
63148@{ */
63149/*!
63150@brief Whether playback of the emitter's sound should start as soon as the emitter object is added to the level.
63151
63152If this is true, the emitter will immediately start to play when the level is loaded.
63153*/
63154bool playOnAdd;
63155/*!
63156@brief If this is true, all fields except for #playOnAdd and #track are ignored on the emitter object.
63157
63158This is useful to prevent fields in the #track's description from being overridden by emitter fields.
63159*/
63160bool useTrackDescriptionOnly;
63161/*!
63162@brief Whether to play #fileName in an infinite loop.
63163
63164If a #track is assigned, the value of this field is ignored.
63165@see SFXDescription::isLooping
63166*/
63167bool isLooping;
63168/*!
63169@brief Whether to use streamed playback for #fileName.
63170
63171If a #track is assigned, the value of this field is ignored.
63172@see SFXDescription::isStreaming
63173
63174@ref SFX_streaming
63175*/
63176bool isStreaming;
63177/*!
63178@brief The SFXSource to which to assign the sound of this emitter as a child.
63179
63180@note This field is ignored if #useTrackDescriptionOnly is true.
63181
63182@see SFXDescription::sourceGroup
63183*/
63184SFXSource sourceGroup;
63185/*!
63186@brief Volume level to apply to the sound.
63187
63188@note This field is ignored if #useTrackDescriptionOnly is true.
63189
63190@see SFXDescription::volume
63191*/
63192float volume;
63193/*!
63194@brief Pitch shift to apply to the sound.  Default is 1 = play at normal speed.
63195
63196@note This field is ignored if #useTrackDescriptionOnly is true.
63197
63198@see SFXDescription::pitch
63199*/
63200float pitch;
63201/*!
63202@brief Number of seconds to gradually fade in volume from zero when playback starts.
63203
63204@note This field is ignored if #useTrackDescriptionOnly is true.
63205
63206@see SFXDescription::fadeInTime
63207*/
63208float fadeInTime;
63209/*!
63210@brief Number of seconds to gradually fade out volume down to zero when playback is stopped or paused.
63211
63212@note This field is ignored if #useTrackDescriptionOnly is true.
63213
63214@see SFXDescription::fadeOutTime
63215*/
63216float fadeOutTime;
63217/// @}
63218
63219
63220/*! @name 3D Sound
63221@{ */
63222/*!
63223@brief Whether to play #fileName as a positional (3D) sound or not.
63224
63225If a #track is assigned, the value of this field is ignored.
63226
63227@see SFXDescription::is3D
63228*/
63229bool is3D;
63230/*!
63231@brief Distance at which to start volume attenuation of the 3D sound.
63232
63233@note This field is ignored if #useTrackDescriptionOnly is true.
63234
63235@see SFXDescription::referenceDistance
63236*/
63237float referenceDistance;
63238/*!
63239@brief Distance at which to stop volume attenuation of the 3D sound.
63240
63241@note This field is ignored if #useTrackDescriptionOnly is true.
63242
63243@see SFXDescription::maxDistance
63244*/
63245float maxDistance;
63246/*!
63247@brief Bounds on random offset to apply to initial 3D sound position.
63248
63249@note This field is ignored if #useTrackDescriptionOnly is true.
63250
63251@see SFXDescription::scatterDistance
63252*/
63253Point3F scatterDistance;
63254/*!
63255@brief Angle of inner volume cone of 3D sound in degrees.
63256
63257@note This field is ignored if #useTrackDescriptionOnly is true.
63258
63259@see SFXDescription::coneInsideAngle
63260*/
63261int coneInsideAngle;
63262/*!
63263@brief Angle of outer volume cone of 3D sound in degrees
63264
63265@note This field is ignored if #useTrackDescriptionOnly is true.
63266
63267@see SFXDescription::coneOutsideAngle
63268*/
63269int coneOutsideAngle;
63270/*!
63271@brief Volume scale factor of outside of outer volume 3D sound cone.
63272
63273@note This field is ignored if #useTrackDescriptionOnly is true.
63274
63275@see SFXDescription::coneOutsideVolume
63276*/
63277float coneOutsideVolume;
63278/// @}
63279
63280
63281/*! @name GameObject
63282@{ */
63283/// @}
63284
63285
63286/*! @name Transform
63287@{ */
63288/// @}
63289
63290
63291/*! @name Editing
63292@{ */
63293/// @}
63294
63295
63296/*! @name Mounting
63297@{ */
63298/// @}
63299
63300
63301/*! @name Ungrouped
63302@{ */
63303/// @}
63304
63305
63306/*! @name Object
63307@{ */
63308/// @}
63309
63310
63311/*! @name Editing
63312@{ */
63313/// @}
63314
63315
63316/*! @name Persistence
63317@{ */
63318/// @}
63319
63320};
63321
63322/*!
63323@ingroup gameObjects
63324
63325*/
63326class TurretShape : public Item {
63327public:
63328/*!
63329@brief Get if the turret is allowed to rotate through moves.
63330
63331@return True if the turret is allowed to rotate through moves.*/
63332bool getAllowManualRotation();
63333/*!
63334@brief Set if the turret is allowed to rotate through moves.
63335
63336@param allow If true then the turret may be rotated through moves.*/
63337void setAllowManualRotation( bool allow );
63338/*!
63339@brief Get if the turret is allowed to fire through moves.
63340
63341@return True if the turret is allowed to fire through moves.*/
63342bool getAllowManualFire();
63343/*!
63344@brief Set if the turret is allowed to fire through moves.
63345
63346@param allow If true then the turret may be fired through moves.*/
63347void setAllowManualFire( bool allow );
63348/*!
63349@brief Get the name of the turret's current state.
63350
63351The state is one of the following:
63352
63353<ul><li>Dead - The TurretShape is destroyed.</li><li>Mounted - The TurretShape is mounted to an object such as a vehicle.</li><li>Ready - The TurretShape is free to move.  The usual state.</li></ul>
63354@return The current state; one of: "Dead", "Mounted", "Ready"*/
63355string getState();
63356/*!
63357@brief Get Euler rotation of this turret's heading and pitch nodes.
63358
63359@return the orientation of the turret's heading and pitch nodes in the form of rotations around the X, Y and Z axes in degrees.*/
63360Point3F getTurretEulerRotation();
63361/*!
63362@brief Set Euler rotation of this turret's heading and pitch nodes in degrees.
63363
63364@param rot The rotation in degrees.  The pitch is the X component and the heading is the Z component.  The Y component is ignored.*/
63365void setTurretEulerRotation( Point3F rot );
63366/*!
63367@brief Does the turret respawn after it has been destroyed.
63368
63369@returns True if the turret respawns.*/
63370bool doRespawn();
63371
63372/*! @name Callbacks
63373@{ */
63374/// @}
63375
63376/*!
63377@brief Disables rendering of all instances of this type.
63378
63379
63380@ingroup UNDOCUMENTED
63381*/
63382static bool isRenderable;
63383/*!
63384@brief Disables selection of all instances of this type.
63385
63386
63387@ingroup UNDOCUMENTED
63388*/
63389static bool isSelectable;
63390/*!
63391@brief @brief Respawn the turret after it has been destroyed.
63392
63393
63394If true, the turret will respawn after it is destroyed.
63395
63396*/
63397bool respawn;
63398
63399/*! @name Misc
63400@{ */
63401/// @}
63402
63403
63404/*! @name Game
63405@{ */
63406/// @}
63407
63408
63409/*! @name GameObject
63410@{ */
63411/// @}
63412
63413
63414/*! @name Transform
63415@{ */
63416/// @}
63417
63418
63419/*! @name Editing
63420@{ */
63421/// @}
63422
63423
63424/*! @name Mounting
63425@{ */
63426/// @}
63427
63428
63429/*! @name Ungrouped
63430@{ */
63431/// @}
63432
63433
63434/*! @name Object
63435@{ */
63436/// @}
63437
63438
63439/*! @name Editing
63440@{ */
63441/// @}
63442
63443
63444/*! @name Persistence
63445@{ */
63446/// @}
63447
63448};
63449
63450/*!
63451@ingroup gameObjects
63452*/
63453class AITurretShape : public TurretShape {
63454public:
63455/*!
63456@brief Adds object to the turret's ignore list.
63457
63458All objects in this list will be ignored by the turret's targeting.
63459@param obj The ShapeBase object to ignore.*/
63460void addToIgnoreList( ShapeBase obj );
63461/*!
63462@brief Removes object from the turret's ignore list.
63463
63464All objects in this list will be ignored by the turret's targeting.
63465@param obj The ShapeBase object to once again allow for targeting.*/
63466void removeFromIgnoreList( ShapeBase obj );
63467/*!
63468@brief Removes all objects from the turret's ignore list.
63469
63470All objects in this list will be ignored by the turret's targeting.*/
63471void clearIgnoreList();
63472/*!
63473@brief Returns the number of objects in the turrets ignore list.
63474
63475All objects in this list will be ignored by the turret's targeting.*/
63476int ignoreListCount();
63477/*!
63478@brief Returns the object in the ignore list at index.
63479
63480All objects in this list will be ignored by the turret's targeting.
63481@param index The index of the object in the ignore list being retrieved.*/
63482SimObject getIgnoreListObject( int index );
63483/*!
63484@brief Set the turret's current state.
63485
63486Normally the turret's state comes from updating the state machine but this method allows you to override this and jump to the requested state immediately.
63487@param newState The name of the new state.
63488@param force Is true then force the full processing of the new state even if it is the same as the current state.  If false then only the time out value is reset and the state's script method is called, if any.*/
63489void setTurretState( string newState, bool force=false );
63490/*!
63491@brief Activate a turret from a deactive state.*/
63492void activateTurret();
63493/*!
63494@brief Deactivate a turret from an active state.*/
63495void deactivateTurret();
63496/*!
63497@brief Begin scanning for a target.*/
63498void startScanForTargets();
63499/*!
63500@brief Stop scanning for targets.
63501
63502@note Only impacts the scanning for new targets.  Does not effect a turret's current target lock.*/
63503void stopScanForTargets();
63504/*!
63505@brief Have the turret track the current target.*/
63506void startTrackingTarget();
63507/*!
63508@brief Stop the turret from tracking the current target.*/
63509void stopTrackingTarget();
63510/*!
63511@brief Indicates if the turret has a target.
63512
63513@returns True if the turret has a target.*/
63514bool hasTarget();
63515/*!
63516@brief Get the turret's current target.
63517
63518@returns The object that is the target's current target, or 0 if no target.*/
63519SimObject getTarget();
63520/*!
63521@brief Resets the turret's target tracking.
63522
63523Only resets the internal target tracking.  Does not modify the turret's facing.*/
63524void resetTarget();
63525/*!
63526@brief Set the turret's projectile velocity to help lead the target.
63527
63528This value normally comes from AITurretShapeData::weaponLeadVelocity but this method allows you to override the datablock value.  This can be useful if the turret changes ammunition, uses a different weapon than the default, is damaged, etc.
63529@note Setting this to 0 will disable target leading.*/
63530void setWeaponLeadVelocity( float velocity );
63531/*!
63532@brief Get the turret's defined projectile velocity that helps with target leading.
63533
63534@returns The defined weapon projectile speed, or 0 if leading is disabled.*/
63535float getWeaponLeadVelocity();
63536/*!
63537@brief Set the firing state of the turret's guns.
63538
63539@param fire Set to true to activate all guns.  False to deactivate them.*/
63540void setAllGunsFiring( bool fire );
63541/*!
63542@brief Set the firing state of the given gun slot.
63543
63544@param slot The gun to modify.  Valid range is 0-3 that corresponds to the weapon mount point.
63545@param fire Set to true to activate the gun.  False to deactivate it.*/
63546void setGunSlotFiring( int slot, bool fire );
63547/*!
63548@brief Recenter the turret's weapon.*/
63549void recenterTurret();
63550
63551/*! @name Callbacks
63552@{ */
63553/// @}
63554
63555/*!
63556@brief Disables rendering of all instances of this type.
63557
63558
63559@ingroup UNDOCUMENTED
63560*/
63561static bool isRenderable;
63562/*!
63563@brief Disables selection of all instances of this type.
63564
63565
63566@ingroup UNDOCUMENTED
63567*/
63568static bool isSelectable;
63569
63570/*! @name Misc
63571@{ */
63572/// @}
63573
63574
63575/*! @name Game
63576@{ */
63577/// @}
63578
63579
63580/*! @name GameObject
63581@{ */
63582/// @}
63583
63584
63585/*! @name Transform
63586@{ */
63587/// @}
63588
63589
63590/*! @name Editing
63591@{ */
63592/// @}
63593
63594
63595/*! @name Mounting
63596@{ */
63597/// @}
63598
63599
63600/*! @name Ungrouped
63601@{ */
63602/// @}
63603
63604
63605/*! @name Object
63606@{ */
63607/// @}
63608
63609
63610/*! @name Editing
63611@{ */
63612/// @}
63613
63614
63615/*! @name Persistence
63616@{ */
63617/// @}
63618
63619};
63620
63621/*!
63622@brief An example scene object which renders a mesh.
63623
63624This class implements a basic SceneObject that can exist in the world at a 3D position and render itself. There are several valid ways to render an object in Torque. This class implements the preferred rendering method which is to submit a MeshRenderInst along with a Material, vertex buffer, primitive buffer, and transform and allow the RenderMeshMgr handle the actual setup and rendering for you.
63625
63626See the C++ code for implementation details.
63627
63628@ingroup Examples
63629
63630*/
63631class Skylight : public ReflectionProbe {
63632public:
63633/*!
63634@brief A utility method for forcing a network update.
63635
63636*/
63637void postApply();
63638
63639/*! @name Callbacks
63640@{ */
63641/// @}
63642
63643/*!
63644@brief Disables rendering of all instances of this type.
63645
63646
63647@ingroup UNDOCUMENTED
63648*/
63649static bool isRenderable;
63650/*!
63651@brief Disables selection of all instances of this type.
63652
63653
63654@ingroup UNDOCUMENTED
63655*/
63656static bool isSelectable;
63657
63658/*! @name Rendering
63659@{ */
63660/// @}
63661
63662
63663/*! @name Reflection
63664@{ */
63665/// @}
63666
63667
63668/*! @name GameObject
63669@{ */
63670/// @}
63671
63672
63673/*! @name Transform
63674@{ */
63675/// @}
63676
63677
63678/*! @name Editing
63679@{ */
63680/// @}
63681
63682
63683/*! @name Mounting
63684@{ */
63685/// @}
63686
63687
63688/*! @name Ungrouped
63689@{ */
63690/// @}
63691
63692
63693/*! @name Object
63694@{ */
63695/// @}
63696
63697
63698/*! @name Editing
63699@{ */
63700/// @}
63701
63702
63703/*! @name Persistence
63704@{ */
63705/// @}
63706
63707};
63708
63709/*! UNDOCUMENTED!
63710@ingroup UNDOCUMENTED
63711 */
63712class AssetQuery : public SimObject {
63713public:
63714/*!
63715@brief Clears all asset Id results.Clears all asset Id results.
63716
63717@return () No return value.
63718*/
63719void clear();
63720/*!
63721@brief Sets the asset query to a copy of the specified asset query.
63722
63723@param assetQuery The asset query to copy.
63724@return Whether the operation succeeded or not.
63725*/
63726bool set( int queryId );
63727/*!
63728@brief Gets the count of asset Id results.
63729
63730@return (int)The count of asset Id results.
63731*/
63732int getCount();
63733/*!
63734@brief Gets the asset Id at the specified query result index.
63735
63736@param resultIndex The query result index to use.
63737@return (assetId)The asset Id at the specified index or NULL if not valid.
63738*/
63739string getAsset( int resultIndex=-1 );
63740
63741/*! @name Callbacks
63742@{ */
63743/// @}
63744
63745
63746/*! @name Ungrouped
63747@{ */
63748/// @}
63749
63750
63751/*! @name Object
63752@{ */
63753/// @}
63754
63755
63756/*! @name Editing
63757@{ */
63758/// @}
63759
63760
63761/*! @name Persistence
63762@{ */
63763/// @}
63764
63765/*!
63766@brief Gets the number of results in the asset query.
63767*/
63768int count;
63769};
63770
63771/*! UNDOCUMENTED!
63772@ingroup UNDOCUMENTED
63773 */
63774class AssetTagsManifest : public SimObject {
63775public:
63776/*!
63777@brief Creates an asset tag.
63778
63779@param tagName The tag name to create.
63780@return No return value.
63781*/
63782void createTag( string tagName="" );
63783/*!
63784@brief Renames an existing asset tag.
63785
63786@param tagName The tag name to rename.
63787@param newTagName The new tag name to assign.
63788@return Whether the asset tag was renamed or not.
63789*/
63790bool renameTag( string oldTagName, string newTagName );
63791/*!
63792@brief Deletes an asset tag.
63793
63794@param tagName The tag name to delete.
63795@return Whether the asset tag was deleted or not.
63796*/
63797bool deleteTag( string tagName );
63798/*!
63799@brief Checks whether the specified asset tag exists or not.
63800
63801@param tagName The tag name to check.
63802@return Whether the specified asset tag exists or not.
63803*/
63804bool isTag( string tagName );
63805/*!
63806@brief Gets the total asset tag count.
63807
63808@return The total asset tag count.
63809*/
63810int getTagCount();
63811/*!
63812@brief Gets the asset tag at the specified index.
63813
63814@param tagIndex The asset tag index.This must be 0 to the asset tag count less one.
63815@return The asset tag at the specified index or NULL if invalid.
63816*/
63817string getTag( int tagIndex );
63818/*!
63819@brief Gets the asset tag count on the specified asset Id.
63820
63821@param assetId The asset Id to count tags on.
63822@return The asset tag count on the specified asset Id.
63823*/
63824int getAssetTagCount( string assetId );
63825/*!
63826@brief Gets the asset tag on the specified asset Id at the specified index.
63827
63828@param assetId The asset Id to count tags on.
63829@param tagIndex The asset tag index.This must be 0 to the asset tag count less one.
63830@return The asset tag on the specified asset Id at the specified index or NULL if invalid.
63831*/
63832string getAssetTag( string assetId, int tagIndex );
63833/*!
63834@brief Tags the asset Id with the specified asset tag.
63835
63836@param assetId The asset Id to tag.
63837@param tagName The tag name to assign.
63838@return Whether the tag operation was successful or not.
63839*/
63840bool tag( string assetId, string tagName );
63841/*!
63842@brief Un-tags the asset Id from the specified asset tag.
63843
63844@param assetId The asset Id to un - tag.
63845@param tagName The tag name to un - assign.
63846@return Whether the un - tag operation was successful or not.
63847*/
63848bool untag( string assetId, string tagName );
63849/*!
63850@brief Checks whether the asset Id is tagged with the specified asset tag.
63851
63852@param assetId The asset Id to check.
63853@param tagName The tag name to check.
63854@return Whether the asset Id is tagged with the specified asset tag or not.
63855*/
63856bool hasTag( string assetId, string tagName );
63857
63858/*! @name Callbacks
63859@{ */
63860/// @}
63861
63862
63863/*! @name Ungrouped
63864@{ */
63865/// @}
63866
63867
63868/*! @name Object
63869@{ */
63870/// @}
63871
63872
63873/*! @name Editing
63874@{ */
63875/// @}
63876
63877
63878/*! @name Persistence
63879@{ */
63880/// @}
63881
63882};
63883
63884/*! UNDOCUMENTED!
63885@ingroup UNDOCUMENTED
63886 */
63887class ModuleDefinition : public SimSet {
63888public:
63889/*!
63890@brief Saves the module definition to the file it was loaded from (if any).
63891
63892@return (bool success) Whether the module definition was saved or not.
63893*/
63894bool save();
63895/*!
63896@brief Gets the module manager which this module definition is registered with (if any).
63897
63898@return (moduleManager) The module manager which this module definition is registered with (zero if not registered).
63899*/
63900int getModuleManager();
63901/*!
63902@brief Gets the number of module dependencies this module definition has.
63903
63904@return (int count) The number of module dependencies this module definition has.
63905*/
63906int getDependencyCount();
63907/*!
63908@brief Gets the module dependency at the specified index.
63909
63910@param dependencyIndex The module dependency index.
63911@return (module - dependency) The module dependency at the specified index.*/
63912String getDependency( uint dependencyIndex=0 );
63913/*!
63914@brief Adds the specified moduleId and vesionId as a dependency.
63915
63916@param moduleId The module Id to add as a dependency.
63917@param versionId The version Id to add as a dependency.  Using zero indicates any version.@return (bool success) Whether the module dependency was added or not.*/
63918bool addDependency( string pModuleId="", uint versionId=0 );
63919/*!
63920@brief Removes the specified moduleId as a dependency.
63921
63922@param moduleId The module Id to remove as a dependency.
63923@return (bool success) Whether the module dependency was removed or not.*/
63924bool removeDependency( string pModuleId="" );
63925
63926/*! @name Callbacks
63927@{ */
63928/// @}
63929
63930
63931/*! @name Ungrouped
63932@{ */
63933/// @}
63934
63935
63936/*! @name Object
63937@{ */
63938/// @}
63939
63940
63941/*! @name Editing
63942@{ */
63943/// @}
63944
63945
63946/*! @name Persistence
63947@{ */
63948/// @}
63949
63950/*!
63951@brief A unique string Id for the module.  It can contain any characters except a comma or semi-colon (the asset scope character).
63952*/
63953string ModuleId;
63954/*!
63955@brief The version Id.  Breaking changes to a module should use a higher version Id.
63956*/
63957int VersionId;
63958/*!
63959@brief The build Id.  Non-breaking changes to a module should use a higher build Id.  Optional: If not specified then the build Id will be zero.
63960*/
63961int BuildId;
63962/*!
63963@brief Whether the module is enabled or not.  When disabled, it is effectively ignored.  Optional: If not specified then the module is enabled.
63964*/
63965bool Enabled;
63966/*!
63967@brief Whether the module should be synchronized or not.  Optional: If not specified then the module is not synchronized.
63968*/
63969bool Synchronized;
63970/*!
63971@brief Whether the module is deprecated or not.  Optional: If not specified then the module is not deprecated.
63972*/
63973bool Deprecated;
63974/*!
63975@brief Whether the merging of a module prior to a restart is critical or not.  Optional: If not specified then the module is not merge critical.
63976*/
63977bool CriticalMerge;
63978/*!
63979@brief Controls if when this module is loaded and the create function is executed, it will replace existing objects that share names or not.
63980*/
63981bool OverrideExistingObjects;
63982/*!
63983@brief The description typically used for debugging purposes but can be used for anything.
63984*/
63985string description;
63986/*!
63987@brief The author of the module.
63988*/
63989string Author;
63990/*!
63991@brief The module group used typically when loading modules as a group.
63992*/
63993string Group;
63994/*!
63995@brief The module type typically used to distinguish modules during module enumeration.  Optional: If not specified then the type is empty although this can still be used as a pseudo 'global' type for instance.
63996*/
63997string type;
63998/*!
63999@brief A comma-separated list of module Ids/VersionIds (<ModuleId>=<VersionId>,<ModuleId>=<VersionId>,etc) which this module depends upon. Optional: If not specified then no dependencies are assumed.
64000*/
64001string Dependencies;
64002/*!
64003@brief The name of the script file to compile when loading the module.  Optional.
64004*/
64005string scriptFile;
64006/*!
64007@brief The name of the function used to create the module.  Optional: If not specified then no create function is called.
64008*/
64009string CreateFunction;
64010/*!
64011@brief The name of the function used to destroy the module.  Optional: If not specified then no destroy function is called.
64012*/
64013string DestroyFunction;
64014/*!
64015@brief The name of tags asset manifest file if this module contains asset tags.  Optional: If not specified then no asset tags will be found for this module.  Currently, only a single asset tag manifest should exist.
64016*/
64017string AssetTagsManifest;
64018/*!
64019@brief The scope set used to control the lifetime scope of objects that the module uses.  Objects added to this set are destroyed automatically when the module is unloaded.
64020*/
64021int ScopeSet;
64022/*!
64023@brief The path of the module.  This is read-only and is available only after the module has been registered by a module manager.
64024*/
64025string ModulePath;
64026/*!
64027@brief The file of the module.  This is read-only and is available only after the module has been registered by a module manager.
64028*/
64029string ModuleFile;
64030/*!
64031@brief The file-path of the module definition.  This is read-only and is available only after the module has been registered by a module manager.
64032*/
64033string ModuleFilePath;
64034/*!
64035@brief The file-path of the script-file referenced in the module definition.  This is read-only and is available only after the module has been registered by a module manager.
64036*/
64037string ModuleScriptFilePath;
64038/*!
64039@brief A unique signature of the module definition based upon its Id, version and build.  This is read-only and is available only after the module has been registered by a module manager.
64040*/
64041string Signature;
64042};
64043
64044/*! UNDOCUMENTED!
64045@ingroup UNDOCUMENTED
64046 */
64047class GameObjectAsset : public AssetBase {
64048public:
64049/*!
64050@brief Creates an instance of the given GameObject given the asset definition.
64051
64052@return The GameObject entity created from the asset.*/
64053string createObject();
64054
64055/*! @name Callbacks
64056@{ */
64057/// @}
64058
64059
64060/*! @name Ungrouped
64061@{ */
64062/// @}
64063
64064
64065/*! @name Object
64066@{ */
64067/// @}
64068
64069
64070/*! @name Editing
64071@{ */
64072/// @}
64073
64074
64075/*! @name Persistence
64076@{ */
64077/// @}
64078
64079/*!
64080@brief Name of the game object. Defines the created object's class.
64081*/
64082string gameObjectName;
64083/*!
64084@brief Path to the script file for the GameObject's script code.
64085*/
64086assetLooseFilePath scriptFile;
64087/*!
64088@brief Path to the taml file for the GameObject's heirarchy.
64089*/
64090assetLooseFilePath TAMLFile;
64091};
64092
64093/*! UNDOCUMENTED!
64094@ingroup UNDOCUMENTED
64095 */
64096class ImageAsset : public AssetBase {
64097public:
64098/*!
64099@brief Creates an instance of the given GameObject given the asset definition.
64100
64101@return The GameObject entity created from the asset.*/
64102string getImagePath();
64103/*!
64104@brief Creates an instance of the given GameObject given the asset definition.
64105
64106@return The GameObject entity created from the asset.*/
64107string getImageInfo();
64108
64109/*! @name Callbacks
64110@{ */
64111/// @}
64112
64113
64114/*! @name Ungrouped
64115@{ */
64116/// @}
64117
64118
64119/*! @name Object
64120@{ */
64121/// @}
64122
64123
64124/*! @name Editing
64125@{ */
64126/// @}
64127
64128
64129/*! @name Persistence
64130@{ */
64131/// @}
64132
64133/*!
64134@brief Path to the image file.
64135*/
64136assetLooseFilePath imageFile;
64137/*!
64138@brief Should the image use mips? (Currently unused).
64139*/
64140bool UseMips;
64141/*!
64142@brief Is the image in an HDR format? (Currently unused)
64143*/
64144bool isHDRImage;
64145/*!
64146@brief What the main use-case for the image is for.
64147*/
64148ImageAssetType imageType;
64149};
64150
64151/*! UNDOCUMENTED!
64152@ingroup UNDOCUMENTED
64153 */
64154class LevelAsset : public AssetBase {
64155public:
64156/*!
64157@brief Gets the full path of the asset's defined level file.
64158
64159@return The string result of the level path*/
64160string getLevelPath();
64161/*!
64162@brief Gets the full path of the asset's defined preview image file.
64163
64164@return The string result of the level preview image path*/
64165string getPreviewImagePath();
64166/*!
64167@brief Gets the full path of the asset's defined postFX preset file.
64168
64169@return The string result of the postFX preset path*/
64170string getPostFXPresetPath();
64171/*!
64172@brief Gets the full path of the asset's defined decal file.
64173
64174@return The string result of the decal path*/
64175string getDecalsPath();
64176/*!
64177@brief Initiates the loading of asset dependencies for this level.
64178
64179*/
64180void loadDependencies();
64181/*!
64182@brief Initiates the unloading of previously loaded asset dependencies for this level.
64183
64184*/
64185void unloadDependencies();
64186
64187/*! @name Callbacks
64188@{ */
64189/// @}
64190
64191
64192/*! @name Ungrouped
64193@{ */
64194/// @}
64195
64196
64197/*! @name Object
64198@{ */
64199/// @}
64200
64201
64202/*! @name Editing
64203@{ */
64204/// @}
64205
64206
64207/*! @name Persistence
64208@{ */
64209/// @}
64210
64211/*!
64212@brief Path to the actual level file.
64213*/
64214assetLooseFilePath LevelFile;
64215/*!
64216@brief Human-friendly name for the level.
64217*/
64218string LevelName;
64219/*!
64220@brief Path to the image used for selection preview.
64221*/
64222assetLooseFilePath PreviewImage;
64223/*!
64224@brief Path to the level's postFXPreset.
64225*/
64226assetLooseFilePath PostFXPresetFile;
64227/*!
64228@brief Path to the decals cache file.
64229*/
64230assetLooseFilePath DecalsFile;
64231/*!
64232@brief Path to the Forest cache file.
64233*/
64234assetLooseFilePath ForestFile;
64235/*!
64236@brief Path to the navmesh file.
64237*/
64238assetLooseFilePath NavmeshFile;
64239/*!
64240@brief Path to the level file with objects that were removed as part of the baking process. Loaded when the editor is loaded for ease of editing.
64241*/
64242assetLooseFilePath EditorFile;
64243/*!
64244@brief Path to the level file with the objects generated as part of the baking process
64245*/
64246assetLooseFilePath BakedSceneFile;
64247/*!
64248@brief Is this a sublevel to another Scene
64249*/
64250bool isSubScene;
64251/*!
64252@brief Name of the Game Mode to be used with this level
64253*/
64254string gameModeName;
64255};
64256
64257/*! UNDOCUMENTED!
64258@ingroup UNDOCUMENTED
64259 */
64260class MaterialAsset : public AssetBase {
64261public:
64262/*!
64263@brief Compiles the material's generated shader, if any. Not yet implemented
64264
64265*/
64266void compileShader();
64267
64268/*! @name Callbacks
64269@{ */
64270/// @}
64271
64272
64273/*! @name Ungrouped
64274@{ */
64275/// @}
64276
64277
64278/*! @name Object
64279@{ */
64280/// @}
64281
64282
64283/*! @name Editing
64284@{ */
64285/// @}
64286
64287
64288/*! @name Persistence
64289@{ */
64290/// @}
64291
64292/*!
64293@brief Path to the file containing the material definition.
64294*/
64295assetLooseFilePath scriptFile;
64296/*!
64297@brief Name of the material definition this asset is for.
64298*/
64299string materialDefinitionName;
64300};
64301
64302/*! UNDOCUMENTED!
64303@ingroup UNDOCUMENTED
64304 */
64305class ScriptAsset : public AssetBase {
64306public:
64307/*!
64308@brief Executes the script file.
64309
64310@return The bool result of calling exec*/
64311bool execScript();
64312
64313/*! @name Callbacks
64314@{ */
64315/// @}
64316
64317
64318/*! @name Ungrouped
64319@{ */
64320/// @}
64321
64322
64323/*! @name Object
64324@{ */
64325/// @}
64326
64327
64328/*! @name Editing
64329@{ */
64330/// @}
64331
64332
64333/*! @name Persistence
64334@{ */
64335/// @}
64336
64337/*!
64338@brief Path to the script file.
64339*/
64340assetLooseFilePath scriptFile;
64341};
64342
64343/*! UNDOCUMENTED!
64344@ingroup UNDOCUMENTED
64345 */
64346class ShapeAnimationAsset : public AssetBase {
64347public:
64348/*!
64349@brief Gets the number of animations for this shape asset.
64350
64351@return Animation count.
64352*/
64353int getAnimationCount();
64354
64355/*! @name Callbacks
64356@{ */
64357/// @}
64358
64359
64360/*! @name Ungrouped
64361@{ */
64362/// @}
64363
64364
64365/*! @name Object
64366@{ */
64367/// @}
64368
64369
64370/*! @name Editing
64371@{ */
64372/// @}
64373
64374
64375/*! @name Persistence
64376@{ */
64377/// @}
64378
64379/*!
64380@brief Path to the file name containing the animation
64381*/
64382assetLooseFilePath animationFile;
64383/*!
64384@brief Name of the animation
64385*/
64386string animationName;
64387/*!
64388@brief If true, this animation asset just referrs to an embedded animation of a regular shape mesh. If false, it is a self-contained animation file
64389*/
64390bool isEmbedded;
64391/*!
64392@brief Is this animation looping?
64393*/
64394bool isCyclic;
64395/*!
64396@brief Is this animation blended with another?
64397*/
64398bool isBlend;
64399/*!
64400@brief AssetID of the animation to reference for our blending
64401*/
64402string blendRefAnimation;
64403/*!
64404@brief Which frame of the reference animation do we use for our blending
64405*/
64406int blendFrame;
64407/*!
64408@brief What frame does this animation clip start on
64409*/
64410int startFrame;
64411/*!
64412@brief What fram does this animation clip end on
64413*/
64414int endFrame;
64415/*!
64416@brief Are the rotation values padded
64417*/
64418bool padRotation;
64419/*!
64420@brief Are the transform values padded
64421*/
64422bool padTransforms;
64423};
64424
64425/*! UNDOCUMENTED!
64426@ingroup UNDOCUMENTED
64427 */
64428class ShapeAsset : public AssetBase {
64429public:
64430/*!
64431@brief Gets the number of materials for this shape asset.
64432
64433@return Material count.
64434*/
64435int getMaterialCount();
64436/*!
64437@brief Gets the number of animations for this shape asset.
64438
64439@return Animation count.
64440*/
64441int getAnimationCount();
64442/*!
64443@brief Gets a particular shape animation asset for this shape.
64444
64445@param animation asset index.
64446@return Shape Animation Asset.
64447*/
64448ShapeAnimationAsset getAnimation( int index=0 );
64449/*!
64450@brief Creates a new script asset using the targetFilePath.
64451
64452@return The bool result of calling exec*/
64453string getShapeFile();
64454string generateCachedPreviewImage( int resolution=256 );
64455
64456/*! @name Callbacks
64457@{ */
64458/// @}
64459
64460
64461/*! @name Ungrouped
64462@{ */
64463/// @}
64464
64465
64466/*! @name Object
64467@{ */
64468/// @}
64469
64470
64471/*! @name Editing
64472@{ */
64473/// @}
64474
64475
64476/*! @name Persistence
64477@{ */
64478/// @}
64479
64480/*!
64481@brief Path to the shape file we want to render
64482*/
64483assetLooseFilePath fileName;
64484/*!
64485@brief Path to the shape file we want to render
64486*/
64487assetLooseFilePath constuctorFileName;
64488};
64489
64490/*! UNDOCUMENTED!
64491@ingroup UNDOCUMENTED
64492 */
64493class SoundAsset : public AssetBase {
64494public:
64495string getSoundPath();
64496
64497/*! @name Callbacks
64498@{ */
64499/// @}
64500
64501
64502/*! @name Ungrouped
64503@{ */
64504/// @}
64505
64506
64507/*! @name Object
64508@{ */
64509/// @}
64510
64511
64512/*! @name Editing
64513@{ */
64514/// @}
64515
64516
64517/*! @name Persistence
64518@{ */
64519/// @}
64520
64521/*!
64522@brief Path to the sound file.
64523*/
64524assetLooseFilePath soundFile;
64525/*!
64526@brief Adjustment of the pitch value
64527*/
64528float PitchAdjust;
64529/*!
64530@brief Adjustment to the volume.
64531*/
64532float VolumeAdjust;
64533};
64534
64535/*! UNDOCUMENTED!
64536@ingroup UNDOCUMENTED
64537 */
64538class TerrainMaterialAsset : public AssetBase {
64539public:
64540/*!
64541@brief Compiles the material's generated shader, if any. Not yet implemented
64542
64543*/
64544void compileShader();
64545
64546/*! @name Callbacks
64547@{ */
64548/// @}
64549
64550
64551/*! @name Ungrouped
64552@{ */
64553/// @}
64554
64555
64556/*! @name Object
64557@{ */
64558/// @}
64559
64560
64561/*! @name Editing
64562@{ */
64563/// @}
64564
64565
64566/*! @name Persistence
64567@{ */
64568/// @}
64569
64570/*!
64571@brief Path to the file containing the material definition.
64572*/
64573assetLooseFilePath scriptFile;
64574/*!
64575@brief Name of the material definition this asset is for.
64576*/
64577string materialDefinitionName;
64578};
64579
64580/*!
64581@brief Defines properties for an AssetImprotConfig object.
64582@AssetImportConfig is a SimObject derived object intended to act as a container for all the necessary configuration data when running the Asset Importer.
64583@It dictates if and how any given asset type will be processed when running an import action. This is because the Asset Importer utilizes a lot of informed logic
64584@to try and automate as much of the import process as possible. In theory, you would run the import on a given file, and based on your config the importer will do
64585@everything from importing the designated file, as well as finding and importing any associated files such as images or materials, and prepping the objects at time
64586@of import to avoid as much manual post-processing as possible.
64587
64588@ingroup Assets
64589
64590*/
64591class AssetImportConfig : public SimObject {
64592public:
64593/*!
64594@brief Creates a new script asset using the targetFilePath.
64595
64596@return The bool result of calling exec*/
64597void loadImportConfig( Settings configSettings=nullAsType<Settings*>(), String configName="" );
64598
64599/*! @name Callbacks
64600@{ */
64601/// @}
64602
64603
64604/*! @name Ungrouped
64605@{ */
64606/// @}
64607
64608
64609/*! @name Object
64610@{ */
64611/// @}
64612
64613
64614/*! @name Editing
64615@{ */
64616/// @}
64617
64618
64619/*! @name Persistence
64620@{ */
64621/// @}
64622
64623
64624/*! @name General
64625@{ */
64626/*!
64627@brief Duplicate Asset Auto-Resolution Action. Options are None, AutoPrune, AutoRename
64628*/
64629string DuplicatAutoResolution;
64630/*!
64631@brief Indicates if warnings should be treated as errors
64632*/
64633bool WarningsAsErrors;
64634/*!
64635@brief Indicates if importing should be prevented from completing if any errors are detected at all
64636*/
64637bool PreventImportWithErrors;
64638/*!
64639@brief Should the importer automatically prompt to find missing files if they are not detected automatically by the importer
64640*/
64641bool AutomaticallyPromptMissingFiles;
64642/// @}
64643
64644
64645/*! @name Meshes
64646@{ */
64647/*!
64648@brief Indicates if this config supports importing meshes
64649*/
64650bool ImportMesh;
64651/*!
64652@brief When importing a shape, this indicates if it should automatically add a standard suffix onto the name
64653*/
64654bool AlwaysAddShapeSuffix;
64655/*!
64656@brief  If AlwaysAddShapeSuffix is on, this is the suffix to be added
64657*/
64658string AddedShapeSuffix;
64659/*!
64660@brief Indicates if this config should override the per-format sis files with the config's specific settings
64661*/
64662bool UseManualShapeConfigRules;
64663/*!
64664@brief Indicates if the up axis in the model file should be overridden
64665*/
64666bool DoUpAxisOverride;
64667/*!
64668@brief If overriding, what axis should be used as up. Options are X_AXIS, Y_AXIS, Z_AXIS
64669*/
64670string UpAxisOverride;
64671/*!
64672@brief Indicates if the scale in the model file should be overridden
64673*/
64674bool DoScaleOverride;
64675/*!
64676@brief If overriding, what scale should be used
64677*/
64678float ScaleOverride;
64679/*!
64680@brief Indicates if scale of nodes should be ignored
64681*/
64682bool IgnoreNodeScale;
64683/*!
64684@brief Indicates if the center of the model file should be automatically recentered
64685*/
64686bool AdjustCenter;
64687/*!
64688@brief Indicates if the floor height of the model file should be automatically zero'd
64689*/
64690bool AdjustFloor;
64691/*!
64692@brief Indicates if submeshes should be collapsed down into a single main mesh
64693*/
64694bool CollapseSubmeshes;
64695/*!
64696@brief Indicates what LOD mode the model file should utilize to process out LODs. Options are TrailingNumber, DetectDTS, SingleSize
64697*/
64698string LODType;
64699/*!
64700@brief  A list of what nodes should be guaranteed to be imported if found in the model file. Separated by either , or ;
64701*/
64702string AlwaysImportedNodes;
64703/*!
64704@brief A list of what nodes should be guaranteed to not be imported if found in the model file. Separated by either , or ;
64705*/
64706string AlwaysIgnoreNodes;
64707/*!
64708@brief A list of what mesh objects should be guaranteed to be imported if found in the model file. Separated by either , or ;
64709*/
64710string AlwaysImportMeshes;
64711/*!
64712@brief A list of what mesh objects should be guaranteed to not be imported if found in the model file. Separated by either , or ;
64713*/
64714string AlwaysIgnoreMeshes;
64715/*!
64716@brief Flag to indicate the shape loader should convert to a left-handed coordinate system
64717*/
64718bool convertLeftHanded;
64719/*!
64720@brief Should the shape loader calculate tangent space values
64721*/
64722bool calcTangentSpace;
64723/*!
64724@brief Should the shape loader automatically prune redundant/duplicate materials
64725*/
64726bool removeRedundantMats;
64727/*!
64728@brief Should the shape loader auto-generate UV Coordinates for the mesh.
64729*/
64730bool genUVCoords;
64731/*!
64732@brief Should the UV coordinates be transformed
64733*/
64734bool TransformUVs;
64735/*!
64736@brief Should the UV coordinates be flipped
64737*/
64738bool flipUVCoords;
64739/*!
64740@brief Should the shape loader automatically look for instanced submeshes in the model file
64741*/
64742bool findInstances;
64743/*!
64744@brief Should the shape loader limit the bone weights
64745*/
64746bool limitBoneWeights;
64747/*!
64748@brief Should the shape loader automatically merge identical/duplicate verts
64749*/
64750bool JoinIdenticalVerts;
64751/*!
64752@brief Should the shape loader reverse the winding order of the mesh's face indicies
64753*/
64754bool reverseWindingOrder;
64755/*!
64756@brief Should the normals on the model be inverted
64757*/
64758bool invertNormals;
64759/// @}
64760
64761
64762/*! @name Materials
64763@{ */
64764/*!
64765@brief Does this config allow for importing of materials
64766*/
64767bool ImportMaterials;
64768/*!
64769@brief When importing a material, this indicates if it should automatically add a standard suffix onto the name
64770*/
64771bool AlwaysAddMaterialSuffix;
64772/*!
64773@brief  If AlwaysAddMaterialSuffix is on, this is the suffix to be added
64774*/
64775string AddedMaterialSuffix;
64776/*!
64777@brief When importing a material, should it automatically attempt to merge Roughness, AO and Metalness maps into a single, composited PBR Configuration map
64778*/
64779bool CreateORMConfig;
64780/*!
64781@brief When generating a material off of an importing image, should the importer force appending a diffusemap suffix onto the end to avoid potential naming confusion.
64782
64783 e.g. MyCoolStuff.png is imported, generating MyCoolStuff material asset and MyCoolStuff_Diffuse image asset
64784*/
64785bool UseDiffuseSuffixOnOriginImage;
64786/*!
64787@brief Should the importer try and use existing material assets in the game directory if at all possible. (Not currently utilized)
64788*/
64789bool UseExistingMaterials;
64790/*!
64791@brief A list of material names that should not be imported. Separated by either , or ;
64792*/
64793string IgnoreMaterials;
64794/*!
64795@brief When processing a material asset, should the importer attempt to populate the various material maps on it by looking up common naming conventions for potentially relevent image files.
64796
64797 e.g. If MyCoolStuff_Diffuse.png is imported, generating MyCoolStuff material, it would also find MyCoolStuff_Normal and MyCoolStuff_PBR images and map them to the normal and ORMConfig maps respectively automatically
64798*/
64799bool PopulateMaterialMaps;
64800/// @}
64801
64802
64803/*! @name Animation
64804@{ */
64805/*!
64806@brief Does this config allow for importing Shape Animations
64807*/
64808bool ImportAnimations;
64809/*!
64810@brief When importing a shape file, should the animations within be separated out into unique files
64811*/
64812bool SeparateAnimations;
64813/*!
64814@brief If separating animations out from a source file, what prefix should be added to the names for grouping association
64815*/
64816string SeparateAnimationPrefix;
64817/*!
64818@brief Defines the animation timing for the given animation sequence. Options are FrameTime, Seconds, Milliseconds
64819*/
64820string animTiming;
64821/*!
64822@brief The FPS of the animation sequence
64823*/
64824bool animFPS;
64825/// @}
64826
64827
64828/*! @name Collision
64829@{ */
64830/*!
64831@brief Does this configuration generate collision geometry when importing. (Not currently enabled)
64832*/
64833bool GenerateCollisions;
64834/*!
64835@brief What sort of collision geometry is generated. (Not currently enabled)
64836*/
64837string GenCollisionType;
64838/*!
64839@brief What prefix is added to the collision geometry generated. (Not currently enabled)
64840*/
64841string CollisionMeshPrefix;
64842/*!
64843@brief Does this configuration generate Line of Sight collision geometry. (Not currently enabled)
64844*/
64845bool GenerateLOSCollisions;
64846/*!
64847@brief What sort of Line of Sight collision geometry is generated. (Not currently enabled)
64848*/
64849string GenLOSCollisionType;
64850/*!
64851@brief What prefix is added to the Line of Sight collision geometry generated. (Not currently enabled)
64852*/
64853string LOSCollisionMeshPrefix;
64854/// @}
64855
64856
64857/*! @name Images
64858@{ */
64859/*!
64860@brief Does this configuration support importing images.
64861*/
64862bool importImages;
64863/*!
64864@brief When importing an image, this indicates if it should automatically add a standard suffix onto the name
64865*/
64866bool AlwaysAddImageSuffix;
64867/*!
64868@brief  If AlwaysAddImageSuffix is on, this is the suffix to be added
64869*/
64870string AddedImageSuffix;
64871/*!
64872@brief What is the default ImageType images are imported as. Options are: N/A, Diffuse, Normal, Metalness, Roughness, AO, ORMConfig, GUI, Cubemap
64873*/
64874string imageType;
64875/*!
64876@brief What type of suffixes are scanned to detect if an importing image is a diffuse map. 
64877
64878 e.g. _Albedo or _Color
64879*/
64880string DiffuseTypeSuffixes;
64881/*!
64882@brief What type of suffixes are scanned to detect if an importing image is a normal map. 
64883
64884 e.g. _Normal or _Norm
64885*/
64886string NormalTypeSuffixes;
64887/*!
64888@brief What type of suffixes are scanned to detect if an importing image is a metalness map. 
64889
64890 e.g. _Metalness or _Metal
64891*/
64892string MetalnessTypeSuffixes;
64893/*!
64894@brief What type of suffixes are scanned to detect if an importing image is a roughness map.
64895
64896 e.g. _roughness or _rough
64897*/
64898string RoughnessTypeSuffixes;
64899/*!
64900@brief What type of suffixes are scanned to detect if an importing image is a smoothness map. 
64901
64902 e.g. _smoothness or _smooth
64903*/
64904string SmoothnessTypeSuffixes;
64905/*!
64906@brief What type of suffixes are scanned to detect if an importing image is a ambient occlusion map. 
64907
64908 e.g. _ambient or _ao
64909*/
64910string AOTypeSuffixes;
64911/*!
64912@brief What type of suffixes are scanned to detect if an importing image is a ORMConfig map.
64913
64914 e.g. _Composite or _PBR
64915*/
64916string PBRTypeSuffixes;
64917/*!
64918@brief Indicates what filter mode images imported with this configuration utilizes. Options are Linear, Bilinear, Trilinear
64919*/
64920string TextureFilteringMode;
64921/*!
64922@brief Indicates if images imported with this configuration utilize mipmaps
64923*/
64924bool UseMips;
64925/*!
64926@brief Indicates if images imported with this configuration are in an HDR format
64927*/
64928bool IsHDR;
64929/*!
64930@brief Indicates what amount of scaling images imported with this configuration use
64931*/
64932float Scaling;
64933/*!
64934@brief Indicates if images imported with this configuration are compressed
64935*/
64936bool ImagesCompressed;
64937/*!
64938@brief Indicates if images imported with this configuration generate a parent material for it as well
64939*/
64940bool GenerateMaterialOnImport;
64941/// @}
64942
64943
64944/*! @name Sounds
64945@{ */
64946/*!
64947@brief Indicates if sounds are imported with this configuration
64948*/
64949bool importSounds;
64950/*!
64951@brief Indicates what amount the volume is adjusted on sounds imported with this configuration
64952*/
64953float VolumeAdjust;
64954/*!
64955@brief Indicates what amount the pitch is adjusted on sounds imported with this configuration
64956*/
64957float PitchAdjust;
64958/*!
64959@brief Indicates if sounds imported with this configuration are compressed
64960*/
64961bool SoundsCompressed;
64962/// @}
64963
64964};
64965
64966/*!
64967@brief Defines properties for an AssetImportObject object.
64968@AssetImportObject is a SimObject derived object intended to act as a stand-in for the to-be imported objects.
64969@It contains important info such as dependencies, if it's been processed, any error/status issues and the originating file
64970@or if it's been programmatically generated as part of the import process.
64971
64972@ingroup Assets
64973
64974*/
64975class AssetImporter : public SimObject {
64976public:
64977/*!
64978@brief Creates a new script asset using the targetFilePath.
64979
64980@return The bool result of calling exec*/
64981void setTargetPath( String path="" );
64982/*!
64983@brief Creates a new script asset using the targetFilePath.
64984
64985@return The bool result of calling exec*/
64986void resetImportSession( bool forceResetSession=false );
64987/*!
64988@brief Creates a new script asset using the targetFilePath.
64989
64990@return The bool result of calling exec*/
64991void dumpActivityLog();
64992/*!
64993@brief Creates a new script asset using the targetFilePath.
64994
64995@return The bool result of calling exec*/
64996int getActivityLogLineCount();
64997/*!
64998@brief Creates a new script asset using the targetFilePath.
64999
65000@return The bool result of calling exec*/
65001String getActivityLogLine( int i=0 );
65002/*!
65003@brief Creates a new script asset using the targetFilePath.
65004
65005@return The bool result of calling exec*/
65006String autoImportFile( String path="" );
65007/*!
65008@brief Creates a new script asset using the targetFilePath.
65009
65010@return The bool result of calling exec*/
65011AssetImportObject addImportingFile( String path="" );
65012/*!
65013@brief Creates a new script asset using the targetFilePath.
65014
65015@return The bool result of calling exec*/
65016void addImportingAssetItem( AssetImportObject assetItem=nullAsType< AssetImportObject*>(), AssetImportObject parentItem=nullAsType< AssetImportObject*>() );
65017/*!
65018@brief Creates a new script asset using the targetFilePath.
65019
65020@return The bool result of calling exec*/
65021void processImportingAssets();
65022/*!
65023@brief Creates a new script asset using the targetFilePath.
65024
65025@return The bool result of calling exec*/
65026bool validateImportingAssets();
65027/*!
65028@brief Creates a new script asset using the targetFilePath.
65029
65030@return The bool result of calling exec*/
65031void resolveAssetItemIssues( AssetImportObject assetItem=nullAsType< AssetImportObject*>() );
65032/*!
65033@brief Creates a new script asset using the targetFilePath.
65034
65035@return The bool result of calling exec*/
65036void importAssets();
65037/*!
65038@brief Creates a new script asset using the targetFilePath.
65039
65040@return The bool result of calling exec*/
65041int getAssetItemCount();
65042/*!
65043@brief Creates a new script asset using the targetFilePath.
65044
65045@return The bool result of calling exec*/
65046AssetImportObject getAssetItem( int index=0 );
65047/*!
65048@brief Creates a new script asset using the targetFilePath.
65049
65050@return The bool result of calling exec*/
65051int getAssetItemChildCount( AssetImportObject assetItem=nullAsType< AssetImportObject*>() );
65052/*!
65053@brief Creates a new script asset using the targetFilePath.
65054
65055@return The bool result of calling exec*/
65056AssetImportObject getAssetItemChild( AssetImportObject assetItem=nullAsType< AssetImportObject*>(), int index=0 );
65057/*!
65058@brief Creates a new script asset using the targetFilePath.
65059
65060@return The bool result of calling exec*/
65061void deleteImportingAsset( AssetImportObject assetItem=nullAsType< AssetImportObject*>() );
65062/*!
65063@brief Creates a new script asset using the targetFilePath.
65064
65065@return The bool result of calling exec*/
65066void setImportConfig( AssetImportConfig importConfig=nullAsType< AssetImportConfig*>() );
65067
65068/*! @name Callbacks
65069@{ */
65070/// @}
65071
65072
65073/*! @name Ungrouped
65074@{ */
65075/// @}
65076
65077
65078/*! @name Object
65079@{ */
65080/// @}
65081
65082
65083/*! @name Editing
65084@{ */
65085/// @}
65086
65087
65088/*! @name Persistence
65089@{ */
65090/// @}
65091
65092/*!
65093@brief The Id of the module the assets are to be imported into
65094*/
65095string targetModuleId;
65096/*!
65097@brief The Id of the module the assets are to be imported into
65098*/
65099string finalImportedAssetPath;
65100/*!
65101@brief The path any imported assets are placed in as their destination
65102*/
65103string targetPath;
65104};
65105
65106/*! UNDOCUMENTED!
65107@ingroup UNDOCUMENTED
65108 */
65109class StateMachineAsset : public AssetBase {
65110public:
65111void notifyAssetChanged();
65112
65113/*! @name Callbacks
65114@{ */
65115/// @}
65116
65117
65118/*! @name Ungrouped
65119@{ */
65120/// @}
65121
65122
65123/*! @name Object
65124@{ */
65125/// @}
65126
65127
65128/*! @name Editing
65129@{ */
65130/// @}
65131
65132
65133/*! @name Persistence
65134@{ */
65135/// @}
65136
65137/*!
65138@brief Path to the state machine file.
65139*/
65140assetLooseFilePath stateMachineFile;
65141};
65142
65143/*! UNDOCUMENTED!
65144@ingroup UNDOCUMENTED
65145 */
65146class Taml : public SimObject {
65147public:
65148/*!
65149@brief Sets the format that Taml should use to read/write.
65150
65151@param format The format to use: 'xml' or 'binary'.
65152@return No return value.*/
65153void setFormat( string formatName );
65154/*!
65155@brief Gets the format that Taml should use to read/write.
65156
65157@return The format that Taml should use to read/write.*/
65158string getFormat();
65159/*!
65160@brief Sets whether the format type is automatically determined by the filename extension or not.
65161
65162@param autoFormat Whether the format type is automatically determined by the filename extension or not.
65163@return No return value.*/
65164void setAutoFormat( bool autoFormat );
65165/*!
65166@brief Gets whether the format type is automatically determined by the filename extension or not.
65167
65168@return Whether the format type is automatically determined by the filename extension or not.*/
65169bool getAutoFormat();
65170/*!
65171@brief Sets whether to write static fields that are at their default or not.
65172
65173@param writeDefaults Whether to write static fields that are at their default or not.
65174@return No return value.*/
65175void setWriteDefaults( bool writeDefaults );
65176/*!
65177@brief Gets whether to write static fields that are at their default or not.
65178
65179@return Whether to write static fields that are at their default or not.*/
65180bool getWriteDefaults();
65181/*!
65182@brief Sets whether to update each type instances file-progenitor or not.
65183
65184If not updating then the progenitor stay as the script that executed the call to Taml.
65185@param progenitorUpdate Whether to update each type instances file-progenitor or not.
65186@return No return value.*/
65187void setProgenitorUpdate( bool progenitorUpdate );
65188/*!
65189@brief Gets whether to update each type instances file-progenitor or not.
65190
65191@return Whether to update each type instances file-progenitor or not.*/
65192bool getProgenitorUpdate();
65193/*!
65194@brief Sets the extension (end of filename) used to detect the XML format.
65195
65196@param extension The extension (end of filename) used to detect the XML format.
65197@return No return value.*/
65198void setAutoFormatXmlExtension( string extension );
65199/*!
65200@brief Gets the extension (end of filename) used to detect the XML format.
65201
65202@return The extension (end of filename) used to detect the XML format.*/
65203string getAutoFormatXmlExtension();
65204/*!
65205@brief Sets the extension (end of filename) used to detect the Binary format.
65206
65207@param extension The extension (end of filename) used to detect the Binary format.
65208@return No return value.*/
65209void setAutoFormatBinaryExtension( string extension );
65210/*!
65211@brief Gets the extension (end of filename) used to detect the Binary format.
65212
65213@return The extension (end of filename) used to detect the Binary format.*/
65214string getAutoFormatBinaryExtension();
65215/*!
65216@brief Sets whether ZIP compression is used on binary formatting or not.
65217
65218@param compressed Whether compression is on or off.
65219@return No return value.*/
65220void setBinaryCompression( bool compressed );
65221/*!
65222@brief Gets whether ZIP compression is used on binary formatting or not.
65223
65224@return Whether ZIP compression is used on binary formatting or not.*/
65225bool getBinaryCompression();
65226/*!
65227@brief Sets whether to write JSON that is strictly compatible with RFC4627 or not.@param jsonStrict Whether to write JSON that is strictly compatible with RFC4627 or not.@return No return value.
65228
65229*/
65230void setJSONStrict( bool strict );
65231/*!
65232@brief Gets whether to write JSON that is strictly compatible with RFC4627 or not.@return whether to write JSON that is strictly compatible with RFC4627 or not.
65233
65234*/
65235bool getJSONStrict();
65236/*!
65237@brief Writes an object to a file using Taml.
65238
65239@param object The object to write.
65240@param filename The filename to write to.
65241@return Whether the write was successful or not.*/
65242bool write( SimObject obj, string filename );
65243/*!
65244@brief Read an object from a file using Taml.
65245
65246@param filename The filename to read from.
65247@return (Object) The object read from the file or an empty string if read failed.*/
65248SimObject read( string filename );
65249
65250/*! @name Callbacks
65251@{ */
65252/// @}
65253
65254
65255/*! @name Ungrouped
65256@{ */
65257/// @}
65258
65259
65260/*! @name Object
65261@{ */
65262/// @}
65263
65264
65265/*! @name Editing
65266@{ */
65267/// @}
65268
65269
65270/*! @name Persistence
65271@{ */
65272/// @}
65273
65274/*!
65275@brief The read/write format that should be used.
65276*/
65277_TamlFormatMode Format;
65278/*!
65279@brief Whether to write JSON that is strictly compatible with RFC4627 or not.
65280
65281
65282*/
65283bool JSONStrict;
65284/*!
65285@brief Whether ZIP compression is used on binary formatting or not.
65286
65287
65288*/
65289bool BinaryCompression;
65290/*!
65291@brief Whether to write static fields that are at their default or not.
65292
65293
65294*/
65295bool WriteDefaults;
65296/*!
65297@brief Whether to update each type instances file-progenitor or not.
65298
65299
65300*/
65301bool ProgenitorUpdate;
65302/*!
65303@brief Whether the format type is automatically determined by the filename extension or not.
65304
65305
65306*/
65307bool AutoFormat;
65308/*!
65309@brief When using auto-format, this is the extension (end of filename) used to detect the XML format.
65310
65311
65312*/
65313string AutoFormatXmlExtension;
65314/*!
65315@brief When using auto-format, this is the extension (end of filename) used to detect the BINARY format.
65316
65317
65318*/
65319string AutoFormatBinaryExtension;
65320/*!
65321@brief When using auto-format, this is the extension (end of filename) used to detect the JSON format.
65322
65323
65324*/
65325string AutoFormatJSONExtension;
65326};
65327
65328/*!
65329@brief A control to playing Theora videos.
65330
65331This control can be used to play videos in the Theora video format.  The videos may include audio in Vorbis format.  The codecs for both formats are integrated with the engine and no codecs must be present on the user's machine.
65332
65333@tsexample
65334%video = new GuiTheoraCtrl()
65335{
65336   theoraFile = "videos/intro.ogv";
65337   playOnWake = false;
65338   stopOnSleep = true;
65339}
65340
65341Canvas.setContent( %video );
65342%video.play();
65343@endtsexample
65344
65345@see http://www.theora.org
65346
65347@ingroup GuiImages
65348*/
65349class GuiTheoraCtrl : public GuiControl {
65350public:
65351/*!
65352@brief Set the video file to play.  If a video is already playing, playback is stopped and the new video file is loaded.
65353
65354
65355@param filename The video file to load.*/
65356void setFile( string filename );
65357/*!
65358@brief Start playing the video.  If the video is already playing, the call is ignored.
65359
65360*/
65361void play();
65362/*!
65363@brief Pause playback of the video.  If the video is not currently playing, the call is ignored.
65364
65365
65366While stopped, the control displays the last frame.*/
65367void pause();
65368/*!
65369@brief Stop playback of the video.  The next call to play() will then start playback from the beginning of the video.
65370
65371
65372While stopped, the control renders empty with just the background color.*/
65373void stop();
65374/*!
65375@brief Get the current playback time.
65376
65377
65378@return The elapsed playback time in seconds.*/
65379float getCurrentTime();
65380/*!
65381@brief Test whether the video has finished playing.
65382
65383
65384@return True if the video has finished playing, false otherwise.*/
65385bool isPlaybackDone();
65386
65387/*! @name Callbacks
65388@{ */
65389/// @}
65390
65391
65392/*! @name Playback
65393@{ */
65394/*!
65395@brief Theora video file to play.
65396*/
65397filename theoraFile;
65398/*!
65399@brief Fill color when video is not playing.
65400*/
65401ColorI backgroundColor;
65402/*!
65403@brief Whether to start playing video when control is woken up.
65404*/
65405bool playOnWake;
65406/*!
65407@brief Loop playback.
65408*/
65409bool Loop;
65410/*!
65411@brief Whether to stop video when control is set to sleep.
65412
65413
65414If this is not set to true, the video will be paused when the control is put to sleep.  This is because there is no support for seeking in the video stream in the player backend and letting the time source used to synchronize video (either audio or a raw timer) get far ahead of frame decoding will cause possibly very long delays when the control is woken up again.
65415*/
65416bool stopOnSleep;
65417/*!
65418@brief Whether to automatically match control extents to the video size.
65419*/
65420bool matchVideoSize;
65421/*!
65422@brief If true, displays an overlay on top of the video with useful debugging information.
65423*/
65424bool renderDebugInfo;
65425/*!
65426@brief The routine to use for Y'CbCr to RGB conversion.
65427*/
65428GuiTheoraTranscoder transcoder;
65429/// @}
65430
65431
65432/*! @name Layout
65433@{ */
65434/// @}
65435
65436
65437/*! @name Control
65438@{ */
65439/// @}
65440
65441
65442/*! @name ToolTip
65443@{ */
65444/// @}
65445
65446
65447/*! @name Editing
65448@{ */
65449/// @}
65450
65451
65452/*! @name Localization
65453@{ */
65454/// @}
65455
65456
65457/*! @name Ungrouped
65458@{ */
65459/// @}
65460
65461
65462/*! @name Object
65463@{ */
65464/// @}
65465
65466
65467/*! @name Editing
65468@{ */
65469/// @}
65470
65471
65472/*! @name Persistence
65473@{ */
65474/// @}
65475
65476};
65477
65478class EditorIconRegistry {
65479public:
65480
65481/*! @name Callbacks
65482@{ */
65483/// @}
65484
65485};
65486
65487/*!
65488@brief A control that plots one or more curves in a chart.
65489
65490Up to 6 individual curves can be plotted in the graph.  Each plotted curve can have its own display style including its own charting style (#plotType) and color (#plotColor).
65491
65492The data points on each curve can be added in one of two ways:
65493
65494- Manually by calling addDatum().  This causes new data points to be added to the left end of the plotting curve.
65495- Automatically by letting the graph plot the values of a variable over time.  This is achieved by calling addAutoPlot and specifying the variable and update frequency.
65496
65497@tsexample
65498// Create a graph that plots a red polyline graph of the FPS counter in a 1 second (1000 milliseconds) interval.
65499new GuiGraphCtrl( FPSGraph )
65500{
65501   plotType[ 0 ] = "PolyLine";
65502   plotColor[ 0 ] = "1 0 0";
65503   plotVariable[ 0 ] = "fps::real";
65504   plotInterval[ 0 ] = 1000;
65505};
65506@endtsexample
65507
65508@note Each curve has a maximum number of 200 data points it can have at any one time.  Adding more data points to a curve will cause older data points to be removed.
65509
65510@ingroup GuiValues
65511*/
65512class GuiGraphCtrl : public GuiControl {
65513public:
65514/*!
65515@brief Add a data point to the plot's curve.
65516
65517
65518@param plotId Index of the plotting curve to which to add the data point.  Must be 0<=plotId<6.
65519@param value Value of the data point to add to the curve.
65520
65521@note Data values are added to the @b left end of the plotting curve.
65522
65523@note A maximum number of 200 data points can be added to any single plotting curve at any one time.  If this limit is exceeded, data points on the right end of the curve are culled.*/
65524void addDatum( int plotId, float value );
65525/*!
65526@brief Get a data point on the given plotting curve.
65527
65528
65529@param plotId Index of the plotting curve from which to fetch the data point.  Must be 0<=plotId<6.
65530@param index Index of the data point on the curve.
65531@return The value of the data point or -1 if @a plotId or @a index are out of range.*/
65532float getDatum( int plotId, int index );
65533/*!
65534@brief Sets up the given plotting curve to automatically plot the value of the @a variable with a frequency of @a updateFrequency.
65535
65536@param plotId Index of the plotting curve.  Must be 0<=plotId<6.
65537@param variable Name of the global variable.
65538@param updateFrequency Frequency with which to add new data points to the plotting curve (in milliseconds).
65539@tsexample
65540// Plot FPS counter at 1 second intervals.
65541%graph.addAutoPlot( 0, "fps::real", 1000 );
65542@endtsexample*/
65543void addAutoPlot( int plotId, string variable, int updateFrequency );
65544/*!
65545@brief Stop automatic variable plotting for the given curve.
65546
65547@param plotId Index of the plotting curve.  Must be 0<=plotId<6.
65548*/
65549void removeAutoPlot( int plotId );
65550/*!
65551@brief Change the charting type of the given plotting curve.
65552
65553@param plotId Index of the plotting curve.  Must be 0<=plotId<6.
65554@param graphType Charting type to use for the curve.
65555@note Instead of calling this method, you can directly assign to #plotType.*/
65556void setGraphType( int plotId, GuiGraphType graphType );
65557/*!
65558@brief Set the scale of all specified plots to the maximum scale among them.
65559
65560
65561@param plotID1 Index of plotting curve.
65562@param plotID2 Index of plotting curve.*/
65563void matchScale( int plotID1, int plotID2, ... );
65564
65565/*! @name Callbacks
65566@{ */
65567/// @}
65568
65569
65570/*! @name Graph
65571@{ */
65572/*!
65573@brief Ratio of where to place the center coordinate of the graph on the Y axis. 0.5=middle height of control.
65574
65575
65576This allows to account for graphs that have only positive or only negative data points, for example.
65577*/
65578float centerY;
65579/*!
65580@brief Color to use for the plotting curves in the graph.
65581*/
65582LinearColorF plotColor[ 6 ];
65583/*!
65584@brief Charting type of the plotting curves.
65585*/
65586GuiGraphType plotType[ 6 ];
65587/*!
65588@brief Name of the variable to automatically plot on the curves.  If empty, auto-plotting is disabled for the respective curve.
65589*/
65590string plotVariable[ 6 ];
65591/*!
65592@brief Interval between auto-plots of #plotVariable for the respective curve (in milliseconds).
65593*/
65594int plotInterval[ 6 ];
65595/// @}
65596
65597
65598/*! @name Layout
65599@{ */
65600/// @}
65601
65602
65603/*! @name Control
65604@{ */
65605/// @}
65606
65607
65608/*! @name ToolTip
65609@{ */
65610/// @}
65611
65612
65613/*! @name Editing
65614@{ */
65615/// @}
65616
65617
65618/*! @name Localization
65619@{ */
65620/// @}
65621
65622
65623/*! @name Ungrouped
65624@{ */
65625/// @}
65626
65627
65628/*! @name Object
65629@{ */
65630/// @}
65631
65632
65633/*! @name Editing
65634@{ */
65635/// @}
65636
65637
65638/*! @name Persistence
65639@{ */
65640/// @}
65641
65642};
65643
65644/*!
65645@brief GUI Control which displays a horizontal bar with individual drop-down menu items. Each menu item may also have submenu items.
65646
65647@tsexample
65648new GuiMenuBar(newMenuBar)
65649{
65650  Padding = "0";
65651  //Properties not specific to this control have been omitted from this example.
65652};
65653
65654// Add a menu to the menu bar
65655newMenuBar.addMenu(0,"New Menu");
65656
65657// Add a menu item to the New Menu
65658newMenuBar.addMenuItem(0,"New Menu Item",0,"n",-1);
65659
65660// Add a submenu item to the New Menu Item
65661newMenuBar.addSubmenuItem(0,1,"New Submenu Item",0,"s",-1);
65662@endtsexample
65663
65664@see GuiTickCtrl
65665
65666@ingroup GuiCore
65667
65668*/
65669class GuiMenuBar : public GuiTickCtrl {
65670public:
65671void attachToCanvas( string canvas, int pos );
65672void removeFromCanvas();
65673int getMenuCount();
65674int getMenu( int index=0 );
65675/*!
65676@brief insert object at position
65677
65678*/
65679void insert( SimObject pObject=nullAsType<SimObject*>(), int pos=-1 );
65680int findMenu( string barTitle="" );
65681
65682/*! @name Callbacks
65683@{ */
65684/*!
65685@brief Called whenever the mouse enters, or persists is in the menu.
65686
65687@param isInMenu True if the mouse has entered the menu, otherwise is false.
65688@note To receive this callback, call setProcessTicks(true) on the menu bar.
65689@tsexample
65690// Mouse enters or persists within the menu, causing the callback to occur.
65691GuiMenuBar::onMouseInMenu(%this,%hasLeftMenu)
65692{
65693  // Code to run when the callback occurs
65694}
65695@endtsexample
65696
65697@see GuiTickCtrl*/
65698void onMouseInMenu( bool isInMenu );
65699/*!
65700@brief Called whenever a menu is selected.
65701
65702@param menuId Index id of the clicked menu
65703@param menuText Text of the clicked menu
65704
65705@tsexample
65706// A menu has been selected, causing the callback to occur.
65707GuiMenuBar::onMenuSelect(%this,%menuId,%menuText)
65708{
65709  // Code to run when the callback occurs
65710}
65711@endtsexample
65712
65713@see GuiTickCtrl*/
65714void onMenuSelect( int menuId, string menuText );
65715/*!
65716@brief Called whenever an item in a menu is selected.
65717
65718@param menuId Index id of the menu which contains the selected menu item
65719@param menuText Text of the menu which contains the selected menu item
65720
65721@param menuItemId Index id of the selected menu item
65722@param menuItemText Text of the selected menu item
65723
65724@tsexample
65725// A menu item has been selected, causing the callback to occur.
65726GuiMenuBar::onMenuItemSelect(%this,%menuId,%menuText,%menuItemId,%menuItemText)
65727{
65728  // Code to run when the callback occurs
65729}
65730@endtsexample
65731
65732@see GuiTickCtrl*/
65733void onMenuItemSelect( int menuId, string menuText, int menuItemId, string menuItemText );
65734/// @}
65735
65736/*!
65737@brief Extra padding to add to the bounds of the control.
65738
65739
65740*/
65741int padding;
65742/*!
65743@brief Sets the height of the menubar when attached to the canvas.
65744
65745
65746*/
65747int menubarHeight;
65748
65749/*! @name Layout
65750@{ */
65751/// @}
65752
65753
65754/*! @name Control
65755@{ */
65756/// @}
65757
65758
65759/*! @name ToolTip
65760@{ */
65761/// @}
65762
65763
65764/*! @name Editing
65765@{ */
65766/// @}
65767
65768
65769/*! @name Localization
65770@{ */
65771/// @}
65772
65773
65774/*! @name Ungrouped
65775@{ */
65776/// @}
65777
65778
65779/*! @name Object
65780@{ */
65781/// @}
65782
65783
65784/*! @name Editing
65785@{ */
65786/// @}
65787
65788
65789/*! @name Persistence
65790@{ */
65791/// @}
65792
65793};
65794
65795/*! UNDOCUMENTED!
65796@ingroup UNDOCUMENTED
65797 */
65798class SDLInputManager {
65799public:
65800/*!
65801@brief Returns the number of currently connected joystick devices.
65802
65803Game Controllers are a sub-set of joysticks and are included in the joystick count. See https://wiki.libsdl.org/SDL_NumJoysticks for more details.
65804@ingroup Input*/
65805static int numJoysticks();
65806/*!
65807@brief Used to determine the current state of the N'th item in the SDL device list.
65808
65809@param sdlIndex The SDL index for this device.
65810@return values:
65811-1 if the device does not exist (invalid sdlIndex passed)
658120 The device is closed
658131 The device is open as a Joystick
658142 The device is open as a Game Controller
65815@ingroup Input*/
65816static int getDeviceOpenState( int sdlIndex=0 );
65817/*!
65818@brief Used to open the device as a Joystick.
65819
65820If the device is currently open as a Game Controller, it will be closed and opened as a Joystick. If it is currently opened as a Joystick with a different T3D instance ID, it will be changed to the requested ID if that ID is available.
65821@param sdlIndex The SDL index for this device.
65822@param  torqueInstId Is the requested T3D device instance ID. If there is already an open Joystick with the requested ID, The first available ID will be assigned.
65823@return The T3D device instance ID assigned, or -1 if the device could not be opened.*/
65824static int openAsJoystick( int sdlIndex=0, int torqueInstId=0 );
65825/*!
65826@brief Used to open the device as a Game Controller.
65827
65828If the device is currently open as a Joystick, it will be closed and opened as a Game Controller. If it is currently opened as a Game Controller with a different T3D instance ID, it will be changed to the requested ID if that ID is available.
65829@param sdlIndex The SDL index for this device.
65830@param  torqueInstId Is the requested T3D device instance ID. If there is already an open Game Controller with the requested ID, The first available ID will be assigned.
65831@return The T3D device instance ID assigned, or -1 if the device could not be opened.*/
65832static int openAsController( int sdlIndex=0, int torqueInstId=0 );
65833/*!
65834@brief Used to close the N'th item in the SDL device list.
65835
65836This will close a Joystick or Game Controller.
65837@param sdlIndex The SDL index for this device.*/
65838static void closeDevice( int sdlIndex=0 );
65839/*!
65840@brief Gets the T3D instance identifier for an open SDL joystick.
65841
65842@param sdlIndex The SDL index for this device.
65843@return Returns the T3D instance ID used for mapping this device or Null if it does not exist.
65844@ingroup Input*/
65845static string getTorqueInstFromDevice( int sdlIndex=0 );
65846/*!
65847@brief Exposes SDL_JoystickNameForIndex() to script.
65848
65849@param sdlIndex The SDL index for this device.
65850@return Returns the name of the selected joystick or Null if it does not exist.
65851@see https://wiki.libsdl.org/SDL_JoystickNameForIndex 
65852@ingroup Input*/
65853static string JoystickNameForIndex( int sdlIndex=0 );
65854/*!
65855@brief Exposes SDL_GameControllerNameForIndex() to script.
65856
65857@param sdlIndex The SDL index for this device.
65858@return Returns the implementation dependent name for the game controller, or NULL if there is no name or the index is invalid.
65859@see https://wiki.libsdl.org/SDL_GameControllerNameForIndex 
65860@ingroup Input*/
65861static string ControllerNameForIndex( int sdlIndex=0 );
65862/*!
65863@brief Exposes SDL_JoystickGetDeviceGUID() to script.
65864
65865@param sdlIndex The SDL index for this device.
65866@return GUID for the indexed device or Null if it does not exist.
65867@see https://wiki.libsdl.org/SDL_JoystickGetDeviceGUID 
65868@ingroup Input*/
65869static string JoystickGetGUID( int sdlIndex=0 );
65870/*!
65871@brief Gets the USB vendor ID of a joystick device, if available.
65872
65873
65874@param sdlIndex The SDL index for this device.
65875@return The USB vendor ID. If the vendor ID isn't available this function returns 0.
65876@see https://wiki.libsdl.org/SDL_JoystickGetDeviceVendor 
65877@see https://wiki.libsdl.org/SDL_JoystickGetVendor 
65878@see https://wiki.libsdl.org/SDL_GameControllerGetVendor 
65879@ingroup Input*/
65880static int GetVendor( int sdlIndex=0 );
65881/*!
65882@brief Gets the USB product ID of a joystick device, if available.
65883
65884
65885@param sdlIndex The SDL index for this device.
65886@return The USB product ID. If the product ID isn't available this function returns 0.
65887@see https://wiki.libsdl.org/SDL_JoystickGetDeviceProduct 
65888@see https://wiki.libsdl.org/SDL_JoystickGetProduct 
65889@see https://wiki.libsdl.org/SDL_GameControllerGetProduct 
65890@ingroup Input*/
65891static int GetProduct( int sdlIndex=0 );
65892/*!
65893@brief Gets the product version of a joystick device, if available.
65894
65895
65896@param sdlIndex The SDL index for this device.
65897@return The product version. If the product version isn't available this function returns 0.
65898@see https://wiki.libsdl.org/SDL_JoystickGetDeviceProductVersion 
65899@see https://wiki.libsdl.org/SDL_JoystickGetProductVersion 
65900@see https://wiki.libsdl.org/SDL_GameControllerGetProductVersion 
65901@ingroup Input*/
65902static int GetProductVersion( int sdlIndex=0 );
65903/*!
65904@brief Exposes SDL_JoystickGetDeviceType() to script.
65905
65906@param sdlIndex The SDL index for this device.
65907@return The type of device connected. Possible return strings are: "Unknown", "Game Controller", "Wheel", "Arcade Stick", "Flight Stick", "Dance Pad", "Guitar", "Drum Kit", "Arcade Pad" and "Throttle"
65908@see https://wiki.libsdl.org/SDL_JoystickGetDeviceType 
65909@ingroup Input*/
65910static SDLJoystickType GetDeviceType( int sdlIndex=0 );
65911/*!
65912@brief Exposes SDL_JoystickNumAxes() to script.
65913
65914@param sdlIndex The SDL index for this device.
65915@return Returns the number of axis controls/number of axes on success or zero on failure.
65916@see https://wiki.libsdl.org/SDL_JoystickNumAxes 
65917@ingroup Input*/
65918static int JoystickNumAxes( int sdlIndex=0 );
65919/*!
65920@brief Exposes SDL_JoystickNumBalls() to script.
65921
65922@param sdlIndex The SDL index for this device.
65923@return Returns the number of trackballs on success or zero on failure.
65924@see https://wiki.libsdl.org/SDL_JoystickNumBalls 
65925@ingroup Input*/
65926static int JoystickNumBalls( int sdlIndex=0 );
65927/*!
65928@brief Exposes SDL_JoystickNumButtons() to script.
65929
65930@param sdlIndex The SDL index for this device.
65931@return Returns the number of buttons on success or zero on failure.
65932@see https://wiki.libsdl.org/SDL_JoystickNumButtons 
65933@ingroup Input*/
65934static int JoystickNumButtons( int sdlIndex=0 );
65935/*!
65936@brief Exposes SDL_JoystickNumHats() to script.
65937
65938@param sdlIndex The SDL index for this device.
65939@return Returns the number of POV hats on success or zero on failure.
65940@see https://wiki.libsdl.org/SDL_JoystickNumHats 
65941@ingroup Input*/
65942static int JoystickNumHats( int sdlIndex=0 );
65943/*!
65944@brief Exposes SDL_IsGameController() to script.
65945
65946@param sdlIndex The SDL index for this device.
65947@return Returns true if the given joystick is supported by the game controller interface, false if it isn't or it's an invalid index.
65948@see https://wiki.libsdl.org/SDL_IsGameController 
65949@ingroup Input*/
65950static bool IsGameController( int sdlIndex=0 );
65951/*!
65952@brief Exposes SDL_JoystickIsHaptic() to script.
65953
65954@param sdlIndex The SDL index for this device.
65955@return Returns true if the joystick is haptic.
65956@see https://wiki.libsdl.org/SDL_JoystickIsHaptic 
65957@ingroup Input*/
65958static bool JoystickIsHaptic( int sdlIndex=0 );
65959/*!
65960@brief Exposes SDL_JoystickCurrentPowerLevel() to script.
65961
65962@param sdlIndex The SDL index for this device.
65963@return Returns the current battery level or "Wired" if it's a connected device.
65964@see https://wiki.libsdl.org/SDL_JoystickCurrentPowerLevel 
65965@ingroup Input*/
65966static SDLPowerEnum JoystickPowerLevel( int sdlIndex=0 );
65967/*!
65968@brief A convenience function to reurn all of the data for a Joystick/Game Controller  packed as fields in a tab separated string.
65969
65970There is overhead involved in querying joystick data, especially if the device is not open. If more than one field is required, it is more efficient to call JoystickGetSpecs() and parse the data out of the return string than to call the console method for each.
65971@param sdlIndex The SDL index for this device.
65972@return A tab separated string that can be parsed from script with getField()/getFields().
65973
65974Field 0: Number of Axes
65975      1: Number of Buttons
65976      2: Number of POV Hats
65977      3: Number of Trackballs
65978      4: SDL_IsGameController() (Boolean)
65979      5: SDL_JoystickIsHaptic() (Boolean)
65980      6: Power Level (String)
65981      7: Device Type (String)
65982@ingroup Input*/
65983static String JoystickGetSpecs( int sdlIndex=0 );
65984/*!
65985@brief Gets the current value for all joystick axes.
65986
65987@param sdlIndex The SDL index for this device.
65988@return A tab separated string that can be parsed from script with getField()/getFields(). Each axis is one field, so a 4 axis device will have 4 fields.
65989
65990@ingroup Input*/
65991static String JoystickGetAxes( int sdlIndex=0 );
65992/*!
65993@brief Gets the current value for all joystick buttons.
65994
65995@param sdlIndex The SDL index for this device.
65996@return A tab separated string that can be parsed from script with getField()/getFields(). Each button is one field. 0 - SDL_JoystickNumButtons() fields.
65997
65998@ingroup Input*/
65999static String JoystickGetButtons( int sdlIndex=0 );
66000/*!
66001@brief Gets the current value for all POV hats.
66002
66003@param sdlIndex The SDL index for this device.
66004@return A tab separated string that can be parsed from script with getField()/getFields(). Each hat is one field. 0 - SDL_JoystickNumHats() fields. The value is a 4 bit bitmask. If no bits are set, the hat is centered. Bit 0 is up, 1 is right, 2 is down and 3 is left.
66005
66006@ingroup Input*/
66007static String JoystickGetHats( int sdlIndex=0 );
66008/*!
66009@brief Gets the current value for all controller axes.
66010
66011@param sdlIndex The SDL index for this device.
66012@return A tab separated string that can be parsed from script with getField()/getFields(). Game controllers always have 6 axes in the following order: 0-LX, 1-LY, 2-RX, 3-RY, 4-LT, 5-RT.
66013
66014@ingroup Input*/
66015static String ControllerGetAxes( int sdlIndex=0 );
66016/*!
66017@brief Gets the current value for all controller buttons.
66018
66019@param sdlIndex The SDL index for this device.
66020@return A tab separated string that can be parsed from script with getField()/getFields(). Game controllers always have 15 buttons in the following order: 0-A, 1-B, 2-X, 3-Y, 4-Back, 5-Guide, 6-Start, 7-Left Stick, 8-Right Stick, 9-Left Shoulder, 10-Right Shoulder, 11-DPad Up, 12-DPad Down, 13-DPad Left, 14-DPad Right.
66021
66022@ingroup Input*/
66023static String ControllerGetButtons( int sdlIndex=0 );
66024/*!
66025@brief Exposes SDL_GameControllerMapping() to script.
66026
66027@param sdlIndex The SDL index for this device.
66028@return Returns a string that has the controller's mapping or NULL if no mapping is available or it does not exist.
66029@see https://wiki.libsdl.org/SDL_JoystickNameForIndex 
66030@ingroup Input*/
66031static String GameControllerMapping( int sdlIndex=0 );
66032/*!
66033@brief Exposes SDL_GameControllerMappingForGUID() to script.
66034
66035@param guidStr The GUID for which a mapping is desired.
66036@return Returns a mapping string or NULL on error.
66037@see https://wiki.libsdl.org/SDL_GameControllerMappingForGUID 
66038@ingroup Input*/
66039static String GameControllerMappingForGUID( string guidStr );
66040/*!
66041@brief Exposes SDL_GameControllerAddMapping() to script.
66042
66043Use this function to add support for controllers that SDL is unaware of or to cause an existing controller to have a different binding.
66044@param mappingString The new mapping string to apply. Full details on the format of this string are available at the linked SDL wiki page.
66045@return Returns 1 if a new mapping is added, 0 if an existing mapping is updated, -1 on error.
66046@see https://wiki.libsdl.org/SDL_GameControllerAddMapping 
66047@ingroup Input*/
66048static int GameControllerAddMapping( string mappingString );
66049/*!
66050@brief Exposes SDL_GameControllerAddMappingsFromFile() to script.
66051
66052Use this function to load a set of Game Controller mappings from a file, filtered by the current SDL_GetPlatform(). A community sourced database of controllers is available at https://raw.githubusercontent.com/gabomdq/SDL_GameControllerDB/master/gamecontrollerdb.txt 
66053@param fileName The file to load mappings from.
66054@return Returns the number of mappings added or -1 on error.
66055@see https://wiki.libsdl.org/SDL_GameControllerAddMappingsFromFile 
66056@ingroup Input*/
66057static int GameControllerAddMappingsFromFile( string fileName );
66058/*!
66059@brief Get the number of mappings installed. Used with GameControllerMappingForIndex to iterate through all installed mappings.
66060
66061
66062@ingroup Input*/
66063static int GameControllerNumMappings();
66064/*!
66065@brief Get the mapping at a particular index.
66066
66067
66068@param mappingIndex The index for which a mapping is desired.
66069@return Returns a mapping string or NULL if the index is out of range.
66070@ingroup Input*/
66071static String GameControllerMappingForIndex( int mappingIndex );
66072
66073/*! @name Callbacks
66074@{ */
66075/// @}
66076
66077};
66078
66079/*!
66080@brief A 3rd person camera object.
66081
66082@ingroup afxMisc
66083@ingroup AFX
66084
66085*/
66086class afxCamera : public ShapeBase {
66087public:
66088/*!
66089@brief Set the camera to orbit around some given object.
66090
66091
66092@param   orbitObject  Object we want to orbit.
66093@param   mat          A set of fields: posX posY posZ aaX aaY aaZ aaTheta
66094@param   minDistance  Minimum distance to keep from object.
66095@param   maxDistance  Maximum distance to keep from object.
66096@param   curDistance  Distance to set initially from object.
66097@param   ownClientObj Are we observing an object owned by us?*/
66098void setOrbitMode(GameBase orbitObject, TransformF mat, float minDistance, float maxDistance, float curDistance, bool ownClientObject);
66099/*!
66100@brief Set the camera to be able to fly freely.*/
66101void setFlyMode();
66102/*!
66103@brief Get the position of the camera.
66104
66105@returns The position of the camera.*/
66106Point3F getPosition();
66107bool setCameraSubject( SceneObject subject );
66108bool setThirdPersonDistance( float distance );
66109float getThirdPersonDistance();
66110bool setThirdPersonAngle( float distance );
66111float getThirdPersonAngle();
66112void setThirdPersonOffset( Point3F offset, Point3F coi_offset=<a href="/scripting/group/group__input/#group__input_1ggac016db8079c24fb317cf8aba8e237346a0fd430d535aa1902074d95d60a93f744">Point3F::Max</a> );
66113Point3F getThirdPersonOffset();
66114Point3F getThirdPersonCOIOffset();
66115void setThirdPersonMode();
66116void setThirdPersonSnap();
66117string getMode();
66118
66119/*! @name Callbacks
66120@{ */
66121/// @}
66122
66123/*!
66124@brief Disables rendering of all instances of this type.
66125
66126
66127@ingroup UNDOCUMENTED
66128*/
66129static bool isRenderable;
66130/*!
66131@brief Disables selection of all instances of this type.
66132
66133
66134@ingroup UNDOCUMENTED
66135*/
66136static bool isSelectable;
66137
66138/*! @name Game
66139@{ */
66140/// @}
66141
66142
66143/*! @name GameObject
66144@{ */
66145/// @}
66146
66147
66148/*! @name Transform
66149@{ */
66150/// @}
66151
66152
66153/*! @name Editing
66154@{ */
66155/// @}
66156
66157
66158/*! @name Mounting
66159@{ */
66160/// @}
66161
66162
66163/*! @name Ungrouped
66164@{ */
66165/// @}
66166
66167
66168/*! @name Object
66169@{ */
66170/// @}
66171
66172
66173/*! @name Editing
66174@{ */
66175/// @}
66176
66177
66178/*! @name Persistence
66179@{ */
66180/// @}
66181
66182};
66183
66184/*!
66185@brief Base class used by choreographers.
66186
66187@ingroup afxChoreographers
66188@ingroup AFX
66189
66190*/
66191class afxChoreographer : public GameBase {
66192public:
66193/*!
66194@brief Set a ranking value (0-255) for the choreographer.
66195
66196*/
66197void setRanking( uint ranking );
66198/*!
66199@brief Set a level-of-detail value (0-255) for the choreographer.
66200
66201*/
66202void setLevelOfDetail( uint lod );
66203/*!
66204@brief Set a bitmask to specifiy the state of exec-conditions.
66205
66206*/
66207void setExecConditions( uint mask );
66208/*!
66209@brief Add a dynamic constraint consistiing of a source and name. The source can be a SceneObject, a 3-valued position, or a 7-valued transform.
66210
66211*/
66212void addConstraint( string source, string name );
66213/*!
66214@brief Add an explicit client.
66215
66216*/
66217void addExplicitClient( NetConnection client );
66218/*!
66219@brief Set a bit of the trigger-mask.
66220
66221*/
66222void setTriggerBit( uint bit_num );
66223/*!
66224@brief Unset a bit of the trigger-mask.
66225
66226*/
66227void clearTriggerBit( uint bit_num );
66228/*!
66229@brief Test state of a trigger-mask bit.
66230
66231*/
66232bool testTriggerBit( uint bit_num );
66233/*!
66234@brief Remap a dynamic constraint to use a new source. The source can be a SceneObject, a 3-valued position, or a 7-valued transform. but must match type of existing source.
66235
66236*/
66237void remapConstraint( string source, string name );
66238
66239/*! @name Callbacks
66240@{ */
66241/// @}
66242
66243/*!
66244@brief Disables rendering of all instances of this type.
66245
66246
66247@ingroup UNDOCUMENTED
66248*/
66249static bool isRenderable;
66250/*!
66251@brief Disables selection of all instances of this type.
66252
66253
66254@ingroup UNDOCUMENTED
66255*/
66256static bool isSelectable;
66257/*!
66258@brief ...
66259*/
66260SimObject extra;
66261/*!
66262@brief ...
66263*/
66264bool postponeActivation;
66265
66266/*! @name Game
66267@{ */
66268/// @}
66269
66270
66271/*! @name GameObject
66272@{ */
66273/// @}
66274
66275
66276/*! @name Transform
66277@{ */
66278/// @}
66279
66280
66281/*! @name Editing
66282@{ */
66283/// @}
66284
66285
66286/*! @name Mounting
66287@{ */
66288/// @}
66289
66290
66291/*! @name Ungrouped
66292@{ */
66293/// @}
66294
66295
66296/*! @name Object
66297@{ */
66298/// @}
66299
66300
66301/*! @name Editing
66302@{ */
66303/// @}
66304
66305
66306/*! @name Persistence
66307@{ */
66308/// @}
66309
66310};
66311
66312/*!
66313@brief A datablock that describes an Effect Group.
66314
66315afxEffectGroupData provides a way for adding several effects to a choreographer as a group and can be used wherever an afxEffectWrapperData is used. Basically, an effect-group is a simple list of effect-wrappers. When an effect-group is added to a choreographer, the end result is almost the same as adding all of the group's effect-wrappers directly to the choreographer. The main difference is that the grouped effects can be turned on and off collectively and created in multiples. Effect-groups can also contain other effect-groups, forming a hierarchy of effects.
66316
66317A great strength of effect-groups is that they have a count setting that multiplies the number of times the effects in the group are added to the owning choreographer and this doesn't happen until the choreographer instance is created and launched. This makes a big difference for certain kinds of effects, such as fireworks, that tend to consist of small groupings of effects that are repeated many times with slight variations. With groups, an effect like this has a very compact representation for transmitting from server to clients, that only expands when actually used.
66318
66319Effect-groups with a count greater than one are extremely useful when some of the effects use field substitutions. When an effect-group is expanded, it essentially runs through a for-loop from 0 to count-1 and creates a new set of effect instances each time through the loop. For each new set of effects, their group-index is set to the index of this for-loop, which in turn replaces the ## token used in any field substitutions in the child effects. In essence, the for-loop index becomes a parameter of the child effects which can be used to vary the effects created in each loop.
66320
66321@see afxEffectBaseData
66322
66323@see afxEffectWrapperData
66324
66325@ingroup afxEffects
66326@ingroup AFX
66327@ingroup Datablocks
66328
66329*/
66330class afxEffectGroupData : public afxEffectBaseData {
66331public:
66332/*!
66333@brief Resets an effect-group datablock during reload.
66334
66335
66336@ingroup AFX*/
66337void reset();
66338/*!
66339@brief Adds an effect (wrapper or group) to an effect-group.
66340
66341
66342@ingroup AFX*/
66343void pushEffect( afxEffectBaseData effect );
66344
66345/*! @name Callbacks
66346@{ */
66347/// @}
66348
66349/*!
66350@brief ...
66351*/
66352bool groupEnabled;
66353/*!
66354@brief ...
66355*/
66356int count;
66357/*!
66358@brief ...
66359*/
66360char indexOffset;
66361/*!
66362@brief ...
66363*/
66364bool assignIndices;
66365/*!
66366@brief ...
66367*/
66368float delay;
66369/*!
66370@brief ...
66371*/
66372float lifetime;
66373/*!
66374@brief ...
66375*/
66376float fadeInTime;
66377/*!
66378@brief ...
66379*/
66380float fadeOutTime;
66381/*!
66382@brief ...
66383*/
66384afxEffectBaseData addEffect;
66385
66386/*! @name Scripting
66387@{ */
66388/// @}
66389
66390
66391/*! @name Ungrouped
66392@{ */
66393/// @}
66394
66395
66396/*! @name Object
66397@{ */
66398/// @}
66399
66400
66401/*! @name Editing
66402@{ */
66403/// @}
66404
66405
66406/*! @name Persistence
66407@{ */
66408/// @}
66409
66410};
66411
66412/*!
66413@brief Defines the properties of an afxEffectron.
66414
66415@ingroup afxChoreographers
66416@ingroup AFX
66417@ingroup Datablocks
66418
66419*/
66420class afxEffectronData : public afxChoreographerData {
66421public:
66422/*!
66423@brief Resets an effectron datablock during reload.
66424
66425
66426@ingroup AFX*/
66427void reset();
66428/*!
66429@brief Adds an effect (wrapper or group) to an effectron's phase.
66430
66431
66432@ingroup AFX*/
66433void pushEffect( afxEffectBaseData effect );
66434
66435/*! @name Callbacks
66436@{ */
66437/// @}
66438
66439/*!
66440@brief ...
66441*/
66442float Duration;
66443/*!
66444@brief ...
66445*/
66446int numLoops;
66447/*!
66448@brief ...
66449*/
66450afxEffectBaseData addEffect;
66451
66452/*! @name Scripting
66453@{ */
66454/// @}
66455
66456
66457/*! @name Ungrouped
66458@{ */
66459/// @}
66460
66461
66462/*! @name Object
66463@{ */
66464/// @}
66465
66466
66467/*! @name Editing
66468@{ */
66469/// @}
66470
66471
66472/*! @name Persistence
66473@{ */
66474/// @}
66475
66476};
66477
66478/*!
66479@brief A basic effects choreographer.
66480
66481@ingroup afxChoreographers
66482@ingroup AFX
66483
66484*/
66485class afxEffectron : public afxChoreographer {
66486public:
66487/*!
66488@brief Sets the time-factor for the effectron.
66489
66490
66491@ingroup AFX*/
66492void setTimeFactor( float factor );
66493/*!
66494@brief Interrupts and deletes a running effectron.
66495
66496
66497@ingroup AFX*/
66498void interrupt();
66499/*!
66500@brief Activates an effectron that was started with postponeActivation=true.
66501
66502
66503@ingroup AFX*/
66504void activate();
66505
66506/*! @name Callbacks
66507@{ */
66508/// @}
66509
66510/*!
66511@brief Disables rendering of all instances of this type.
66512
66513
66514@ingroup UNDOCUMENTED
66515*/
66516static bool isRenderable;
66517/*!
66518@brief Disables selection of all instances of this type.
66519
66520
66521@ingroup UNDOCUMENTED
66522*/
66523static bool isSelectable;
66524
66525/*! @name Game
66526@{ */
66527/// @}
66528
66529
66530/*! @name GameObject
66531@{ */
66532/// @}
66533
66534
66535/*! @name Transform
66536@{ */
66537/// @}
66538
66539
66540/*! @name Editing
66541@{ */
66542/// @}
66543
66544
66545/*! @name Mounting
66546@{ */
66547/// @}
66548
66549
66550/*! @name Ungrouped
66551@{ */
66552/// @}
66553
66554
66555/*! @name Object
66556@{ */
66557/// @}
66558
66559
66560/*! @name Editing
66561@{ */
66562/// @}
66563
66564
66565/*! @name Persistence
66566@{ */
66567/// @}
66568
66569};
66570
66571/*!
66572@brief Magic-missile class used internally by afxMagicSpell. Properties of individual missile types are defined using afxMagicMissileData.
66573@ingroup AFX
66574
66575*/
66576class afxMagicMissile : public GameBase {
66577public:
66578/*!
66579@brief Set the starting velocity-vector for a magic-missile.
66580
66581
66582@ingroup AFX*/
66583void setStartingVelocityVector( Point3F velocityVec );
66584/*!
66585@brief Set the starting velocity for a magic-missile.
66586
66587
66588@ingroup AFX*/
66589void setStartingVelocity( float velocity );
66590
66591/*! @name Callbacks
66592@{ */
66593/// @}
66594
66595/*!
66596@brief Disables rendering of all instances of this type.
66597
66598
66599@ingroup UNDOCUMENTED
66600*/
66601static bool isRenderable;
66602/*!
66603@brief Disables selection of all instances of this type.
66604
66605
66606@ingroup UNDOCUMENTED
66607*/
66608static bool isSelectable;
66609
66610/*! @name Physics
66611@{ */
66612/*!
66613@brief Initial starting position for this missile.
66614*/
66615Point3F initialPosition;
66616/*!
66617@brief Initial starting velocity for this missile.
66618*/
66619Point3F initialVelocity;
66620/// @}
66621
66622
66623/*! @name Game
66624@{ */
66625/// @}
66626
66627
66628/*! @name GameObject
66629@{ */
66630/// @}
66631
66632
66633/*! @name Transform
66634@{ */
66635/// @}
66636
66637
66638/*! @name Editing
66639@{ */
66640/// @}
66641
66642
66643/*! @name Mounting
66644@{ */
66645/// @}
66646
66647
66648/*! @name Ungrouped
66649@{ */
66650/// @}
66651
66652
66653/*! @name Object
66654@{ */
66655/// @}
66656
66657
66658/*! @name Editing
66659@{ */
66660/// @}
66661
66662
66663/*! @name Persistence
66664@{ */
66665/// @}
66666
66667};
66668
66669/*!
66670@brief Defines the properties of an afxMagicSpell.
66671
66672@ingroup afxChoreographers
66673@ingroup AFX
66674@ingroup Datablocks
66675
66676*/
66677class afxMagicSpellData : public afxChoreographerData {
66678public:
66679/*!
66680@brief Resets a spell datablock during reload.
66681
66682
66683@ingroup AFX*/
66684void reset();
66685/*!
66686@brief Adds an effect (wrapper or group) to a spell's casting phase.
66687
66688
66689@ingroup AFX*/
66690void pushCastingEffect( afxEffectBaseData effect );
66691/*!
66692@brief Adds an effect (wrapper or group) to a spell's launch phase.
66693
66694
66695@ingroup AFX*/
66696void pushLaunchEffect( afxEffectBaseData effect );
66697/*!
66698@brief Adds an effect (wrapper or group) to a spell's delivery phase.
66699
66700
66701@ingroup AFX*/
66702void pushDeliveryEffect( afxEffectBaseData effect );
66703/*!
66704@brief Adds an effect (wrapper or group) to a spell's impact phase.
66705
66706
66707@ingroup AFX*/
66708void pushImpactEffect( afxEffectBaseData effect );
66709/*!
66710@brief Adds an effect (wrapper or group) to a spell's linger phase.
66711
66712
66713@ingroup AFX*/
66714void pushLingerEffect( afxEffectBaseData effect );
66715
66716/*! @name Callbacks
66717@{ */
66718/*!
66719@brief Called when the spell deals damage.
66720
66721@param spell the spell object
66722*/
66723void onDamage( afxMagicSpell spell, string label, string flaver, uint target_id, float amount, U8 n, Point3F pos, float ad_amount, float radius, float impulse );
66724/*!
66725@brief Called when the spell ends naturally.
66726
66727@param spell the spell object
66728*/
66729void onDeactivate( afxMagicSpell spell );
66730/*!
66731@brief Called when the spell ends unnaturally due to an interruption.
66732
66733@param spell the spell object
66734*/
66735void onInterrupt( afxMagicSpell spell, ShapeBase caster );
66736/*!
66737@brief Called when the spell's casting stage ends and the delivery stage begins.
66738
66739@param spell the spell object
66740*/
66741void onLaunch( afxMagicSpell spell, ShapeBase caster, SceneObject target, afxMagicMissile missile );
66742/*!
66743@brief Called at the spell's missile impact marking the end of the deliver stage and the start of the linger stage.
66744
66745@param spell the spell object
66746*/
66747void onImpact( afxMagicSpell spell, ShapeBase caster, SceneObject impacted, Point3F pos, Point3F normal );
66748/*!
66749@brief Called during spell casting before spell instance is fully created.
66750
66751*/
66752bool onPreactivate( SimObject param_holder, ShapeBase caster, SceneObject target, SimObject extra );
66753/*!
66754@brief Called when the spell starts.
66755
66756@param spell the spell object
66757*/
66758void onActivate( afxMagicSpell spell, ShapeBase caster, SceneObject target );
66759/// @}
66760
66761
66762/*! @name Casting Stage
66763@{ */
66764/*!
66765@brief ...
66766*/
66767float castingDur;
66768/*!
66769@brief ...
66770*/
66771int numCastingLoops;
66772/*!
66773@brief ...
66774*/
66775float extraCastingTime;
66776/*!
66777@brief ...
66778*/
66779afxEffectBaseData addCastingEffect;
66780/// @}
66781
66782
66783/*! @name Delivery Stage
66784@{ */
66785/*!
66786@brief ...
66787*/
66788float deliveryDur;
66789/*!
66790@brief ...
66791*/
66792int numDeliveryLoops;
66793/*!
66794@brief ...
66795*/
66796float extraDeliveryTime;
66797/*!
66798@brief ...
66799*/
66800afxEffectBaseData addLaunchEffect;
66801/*!
66802@brief ...
66803*/
66804afxEffectBaseData addDeliveryEffect;
66805/// @}
66806
66807
66808/*! @name Linger Stage
66809@{ */
66810/*!
66811@brief ...
66812*/
66813float lingerDur;
66814/*!
66815@brief ...
66816*/
66817int numLingerLoops;
66818/*!
66819@brief ...
66820*/
66821float extraLingerTime;
66822/*!
66823@brief ...
66824*/
66825afxEffectBaseData addImpactEffect;
66826/*!
66827@brief ...
66828*/
66829afxEffectBaseData addLingerEffect;
66830/// @}
66831
66832/*!
66833@brief ...
66834*/
66835bool allowMovementInterrupts;
66836/*!
66837@brief ...
66838*/
66839float movementInterruptSpeed;
66840/*!
66841@brief ...
66842*/
66843afxMagicMissileData missile;
66844/*!
66845@brief ...
66846*/
66847bool launchOnServerSignal;
66848/*!
66849@brief ...
66850*/
66851int primaryTargetTypes;
66852
66853/*! @name Scripting
66854@{ */
66855/// @}
66856
66857
66858/*! @name Ungrouped
66859@{ */
66860/// @}
66861
66862
66863/*! @name Object
66864@{ */
66865/// @}
66866
66867
66868/*! @name Editing
66869@{ */
66870/// @}
66871
66872
66873/*! @name Persistence
66874@{ */
66875/// @}
66876
66877};
66878
66879/*!
66880@brief A magic spell effects choreographer.
66881
66882@ingroup afxChoreographers
66883@ingroup AFX
66884
66885*/
66886class afxMagicSpell : public afxChoreographer {
66887public:
66888/*!
66889@brief Returns ID of the spell's caster object.
66890
66891
66892@ingroup AFX*/
66893int getCaster();
66894/*!
66895@brief Returns ID of the spell's target object.
66896
66897
66898@ingroup AFX*/
66899int getTarget();
66900/*!
66901@brief Returns ID of the spell's magic-missile object.
66902
66903
66904@ingroup AFX*/
66905int getMissile();
66906/*!
66907@brief Returns ID of impacted-object for the spell.
66908
66909
66910@ingroup AFX*/
66911int getImpactedObject();
66912/*!
66913@brief or (string phase, F32 factor)Sets the time-factor for the spell, either overall or for a specific phrase.
66914
66915
66916@ingroup AFX*/
66917void setTimeFactor(F32 factor);
66918/*!
66919@brief Interrupts the current stage of a magic spell causing it to move onto the next one.
66920
66921
66922@ingroup AFX*/
66923void interruptStage();
66924/*!
66925@brief Interrupts and deletes a running magic spell.
66926
66927
66928@ingroup AFX*/
66929void interrupt();
66930/*!
66931@brief Activates a magic spell that was started with postponeActivation=true.
66932
66933
66934@ingroup AFX*/
66935void activate();
66936
66937/*! @name Callbacks
66938@{ */
66939/// @}
66940
66941/*!
66942@brief Disables rendering of all instances of this type.
66943
66944
66945@ingroup UNDOCUMENTED
66946*/
66947static bool isRenderable;
66948/*!
66949@brief Disables selection of all instances of this type.
66950
66951
66952@ingroup UNDOCUMENTED
66953*/
66954static bool isSelectable;
66955/*!
66956@brief ...
66957*/
66958SimObject caster;
66959/*!
66960@brief ...
66961*/
66962SimObject Target;
66963
66964/*! @name Game
66965@{ */
66966/// @}
66967
66968
66969/*! @name GameObject
66970@{ */
66971/// @}
66972
66973
66974/*! @name Transform
66975@{ */
66976/// @}
66977
66978
66979/*! @name Editing
66980@{ */
66981/// @}
66982
66983
66984/*! @name Mounting
66985@{ */
66986/// @}
66987
66988
66989/*! @name Ungrouped
66990@{ */
66991/// @}
66992
66993
66994/*! @name Object
66995@{ */
66996/// @}
66997
66998
66999/*! @name Editing
67000@{ */
67001/// @}
67002
67003
67004/*! @name Persistence
67005@{ */
67006/// @}
67007
67008};
67009
67010/*!
67011@brief Defines the properties of an afxSelectronData.
67012
67013@ingroup afxChoreographers
67014@ingroup AFX
67015@ingroup Datablocks
67016
67017*/
67018class afxSelectronData : public afxChoreographerData {
67019public:
67020/*!
67021@brief Resets a selectron datablock during reload.
67022
67023
67024@ingroup AFX*/
67025void reset();
67026
67027/*! @name Callbacks
67028@{ */
67029/// @}
67030
67031/*!
67032@brief ...
67033*/
67034float mainDur;
67035/*!
67036@brief ...
67037*/
67038float selectDur;
67039/*!
67040@brief ...
67041*/
67042float deselectDur;
67043/*!
67044@brief ...
67045*/
67046int mainRepeats;
67047/*!
67048@brief ...
67049*/
67050int selectRepeats;
67051/*!
67052@brief ...
67053*/
67054int deselectRepeats;
67055/*!
67056@brief ...
67057*/
67058int selectionTypeMask;
67059/*!
67060@brief ...
67061*/
67062char selectionTypeStyle;
67063/*!
67064@brief ...
67065*/
67066afxEffectBaseData addMainEffect;
67067/*!
67068@brief ...
67069*/
67070afxEffectBaseData addSelectEffect;
67071/*!
67072@brief ...
67073*/
67074afxEffectBaseData addDeselectEffect;
67075/*!
67076@brief ...
67077*/
67078int numMainLoops;
67079/*!
67080@brief ...
67081*/
67082int numSelectLoops;
67083/*!
67084@brief ...
67085*/
67086int numDeselectLoops;
67087
67088/*! @name Scripting
67089@{ */
67090/// @}
67091
67092
67093/*! @name Ungrouped
67094@{ */
67095/// @}
67096
67097
67098/*! @name Object
67099@{ */
67100/// @}
67101
67102
67103/*! @name Editing
67104@{ */
67105/// @}
67106
67107
67108/*! @name Persistence
67109@{ */
67110/// @}
67111
67112};
67113
67114/*!
67115@brief A choreographer for selection effects.
67116
67117@ingroup afxChoreographers
67118@ingroup AFX
67119
67120*/
67121class afxSelectron : public afxChoreographer {
67122public:
67123/*!
67124@brief Sets the time factor of the selectron.
67125
67126
67127@ingroup AFX*/
67128void setTimeFactor( float factor=1.0f );
67129/*!
67130@brief Interrupts and deletes a running selectron.
67131
67132
67133@ingroup AFX*/
67134void interrupt();
67135/*!
67136@brief Stops and deletes a running selectron.
67137
67138
67139@ingroup AFX*/
67140void stopSelectron();
67141
67142/*! @name Callbacks
67143@{ */
67144/// @}
67145
67146/*!
67147@brief Disables rendering of all instances of this type.
67148
67149
67150@ingroup UNDOCUMENTED
67151*/
67152static bool isRenderable;
67153/*!
67154@brief Disables selection of all instances of this type.
67155
67156
67157@ingroup UNDOCUMENTED
67158*/
67159static bool isSelectable;
67160
67161/*! @name Game
67162@{ */
67163/// @}
67164
67165
67166/*! @name GameObject
67167@{ */
67168/// @}
67169
67170
67171/*! @name Transform
67172@{ */
67173/// @}
67174
67175
67176/*! @name Editing
67177@{ */
67178/// @}
67179
67180
67181/*! @name Mounting
67182@{ */
67183/// @}
67184
67185
67186/*! @name Ungrouped
67187@{ */
67188/// @}
67189
67190
67191/*! @name Object
67192@{ */
67193/// @}
67194
67195
67196/*! @name Editing
67197@{ */
67198/// @}
67199
67200
67201/*! @name Persistence
67202@{ */
67203/// @}
67204
67205};
67206
67207/*!
67208@brief A spellbook datablock.
67209
67210@ingroup afxMisc
67211@ingroup AFX
67212@ingroup Datablocks
67213
67214*/
67215class afxSpellBookData : public GameBaseData {
67216public:
67217/*!
67218@brief ...
67219
67220
67221@ingroup AFX*/
67222int getPageSlotIndex( Point2I bookSlot );
67223/*!
67224@brief Get the capacity (total number of spell slots) in a spellbook.
67225
67226
67227@ingroup AFX*/
67228int getCapacity();
67229
67230/*! @name Callbacks
67231@{ */
67232/// @}
67233
67234/*!
67235@brief ...
67236*/
67237char spellsPerPage;
67238/*!
67239@brief ...
67240*/
67241char pagesPerBook;
67242/*!
67243@brief ...
67244*/
67245GameBaseData spells[ 144 ];
67246/*!
67247@brief ...
67248*/
67249GameBaseData rpgSpells[ 144 ];
67250
67251/*! @name Scripting
67252@{ */
67253/// @}
67254
67255
67256/*! @name Ungrouped
67257@{ */
67258/// @}
67259
67260
67261/*! @name Object
67262@{ */
67263/// @}
67264
67265
67266/*! @name Editing
67267@{ */
67268/// @}
67269
67270
67271/*! @name Persistence
67272@{ */
67273/// @}
67274
67275};
67276
67277/*!
67278@brief A spellbook object.
67279
67280@ingroup afxMisc
67281@ingroup AFX
67282
67283*/
67284class afxSpellBook : public GameBase {
67285public:
67286/*!
67287@brief ...
67288
67289
67290@ingroup AFX*/
67291int getPageSlotIndex( Point2I bookSlot );
67292/*!
67293@brief Get spell datablock for spell stored at spellbook index, (page, slot).
67294
67295
67296@ingroup AFX*/
67297int getSpellData( Point2I bookSlot );
67298/*!
67299@brief Get spell RPG datablock for spell stored at spellbook index, (page, slot).
67300
67301
67302@ingroup AFX*/
67303int getSpellRPGData( Point2I bookSlot );
67304/*!
67305@brief ...
67306
67307
67308@ingroup AFX*/
67309void startAllSpellCooldown();
67310
67311/*! @name Callbacks
67312@{ */
67313/// @}
67314
67315/*!
67316@brief Disables rendering of all instances of this type.
67317
67318
67319@ingroup UNDOCUMENTED
67320*/
67321static bool isRenderable;
67322/*!
67323@brief Disables selection of all instances of this type.
67324
67325
67326@ingroup UNDOCUMENTED
67327*/
67328static bool isSelectable;
67329
67330/*! @name Game
67331@{ */
67332/// @}
67333
67334
67335/*! @name GameObject
67336@{ */
67337/// @}
67338
67339
67340/*! @name Transform
67341@{ */
67342/// @}
67343
67344
67345/*! @name Editing
67346@{ */
67347/// @}
67348
67349
67350/*! @name Mounting
67351@{ */
67352/// @}
67353
67354
67355/*! @name Ungrouped
67356@{ */
67357/// @}
67358
67359
67360/*! @name Object
67361@{ */
67362/// @}
67363
67364
67365/*! @name Editing
67366@{ */
67367/// @}
67368
67369
67370/*! @name Persistence
67371@{ */
67372/// @}
67373
67374};
67375
67376/*!
67377@brief A datablock that specifies a Phrase Effect, a grouping of other effects.
67378
67379A Phrase Effect is a grouping or phrase of effects that do nothing until certain trigger events occur. It's like having a whole Effectron organized as an individual effect.
67380
67381Phrase effects can respond to a number of different kinds of triggers:
67382  -- Player triggers such as footsteps, jumps, landings, and idle triggers.
67383  -- Arbitrary animation triggers on dts-based scene objects.
67384  -- Arbitrary trigger bits assigned to active choreographer objects.
67385
67386@ingroup afxEffects
67387@ingroup AFX
67388@ingroup Datablocks
67389
67390*/
67391class afxPhraseEffectData : public GameBaseData {
67392public:
67393/*!
67394@brief Add a child effect to a phrase effect datablock. Argument can be an afxEffectWrappperData or an afxEffectGroupData.
67395
67396*/
67397void pushEffect( afxEffectBaseData effectData );
67398
67399/*! @name Callbacks
67400@{ */
67401/// @}
67402
67403/*!
67404@brief Specifies a duration for the phrase-effect. If set to infinity, the phrase-effect needs to have a phraseType of continuous. Set infinite duration using $AFX::INFINITE_TIME.
67405*/
67406float Duration;
67407/*!
67408@brief Specifies the number of times the phrase-effect should loop. If set to infinity, the phrase-effect needs to have a phraseType of continuous. Set infinite looping using $AFX::INFINITE_REPEATS.
67409*/
67410int numLoops;
67411/*!
67412@brief Sets which bits to consider in the current trigger-state which consists of 32 trigger-bits combined from (possibly overlapping) player trigger bits, constraint trigger bits, and choreographer trigger bits.
67413*/
67414int triggerMask;
67415/*!
67416@brief Selects what combination of bits in triggerMask lead to a trigger. When set to 'any', any bit in triggerMask matching the current trigger-state will cause a trigger. If set to 'all', every bit in triggerMask must match the trigger-state. Possible values: any or all.
67417*/
67418afxPhraseEffect_MatchType matchType;
67419/*!
67420@brief Selects which bit-state(s) of bits in the triggerMask to consider when comparing to the current trigger-state. Possible values: on, off, or both.
67421*/
67422afxPhraseEffect_StateType matchState;
67423/*!
67424@brief Selects between triggered and continuous types of phrases. When set to 'triggered', the phrase-effect is triggered when the relevant trigger-bits change state. When set to 'continuous', the phrase-effect will stay active as long as the trigger-bits remain in a matching state. Possible values: triggered or continuous.
67425*/
67426afxPhraseEffect_PhraseType phraseType;
67427/*!
67428@brief When true, trigger-bits on the choreographer will be ignored.
67429*/
67430bool ignoreChoreographerTriggers;
67431/*!
67432@brief When true, animation triggers from dts-based constraint source objects will be ignored.
67433*/
67434bool ignoreConstraintTriggers;
67435/*!
67436@brief When true, Player-specific triggers from Player-derived constraint source objects will be ignored.
67437*/
67438bool ignorePlayerTriggers;
67439/*!
67440@brief Like a field substitution statement without the leading '$$' token, this eval statement will be executed when a trigger occurs. Any '%%' and '##'  tokens will be substituted.
67441*/
67442string onTriggerCommand;
67443/*!
67444@brief A field macro which adds an effect wrapper datablock to a list of effects associated with the phrase-effect's single phrase. Unlike other fields, addEffect follows an unusual syntax. Order is important since the effects will resolve in the order they are added to each list.
67445*/
67446afxEffectBaseData addEffect;
67447
67448/*! @name Scripting
67449@{ */
67450/// @}
67451
67452
67453/*! @name Ungrouped
67454@{ */
67455/// @}
67456
67457
67458/*! @name Object
67459@{ */
67460/// @}
67461
67462
67463/*! @name Editing
67464@{ */
67465/// @}
67466
67467
67468/*! @name Persistence
67469@{ */
67470/// @}
67471
67472};
67473
67474/*!
67475@brief A GUI button with some special features that are useful for casting AFX spells.
67476
67477@ingroup afxGUI
67478@ingroup AFX
67479
67480*/
67481class afxSpellButton : public GuiButtonCtrl {
67482public:
67483/*!
67484@brief Notify an afxSpellButton when its associated spellbook has changed.
67485
67486*/
67487void onSpellbookChange( afxSpellBook spellbook, uint page );
67488/*!
67489@brief Notify an afxSpellButton when the spellbook turns to a new page.
67490
67491*/
67492void onTurnPage( uint page );
67493/*!
67494@brief Get the text description of a spell.
67495
67496*/
67497string getSpellDescription();
67498/*!
67499@brief Get the spell's datablock.
67500
67501*/
67502int getSpellDataBlock();
67503/*!
67504@brief Get the spell's RPG datablock.
67505
67506*/
67507int getSpellRPGDataBlock();
67508/*!
67509@brief Test if spell uses free targeting.
67510
67511*/
67512bool useFreeTargeting();
67513/*!
67514@brief Get the free targeting style used by the spell.
67515
67516*/
67517int getFreeTargetStyle();
67518
67519/*! @name Callbacks
67520@{ */
67521/// @}
67522
67523/*!
67524@brief ...
67525*/
67526filename bitmap;
67527/*!
67528@brief ...
67529*/
67530Point2I book_slot;
67531
67532/*! @name Button
67533@{ */
67534/// @}
67535
67536
67537/*! @name Layout
67538@{ */
67539/// @}
67540
67541
67542/*! @name Control
67543@{ */
67544/// @}
67545
67546
67547/*! @name ToolTip
67548@{ */
67549/// @}
67550
67551
67552/*! @name Editing
67553@{ */
67554/// @}
67555
67556
67557/*! @name Localization
67558@{ */
67559/// @}
67560
67561
67562/*! @name Ungrouped
67563@{ */
67564/// @}
67565
67566
67567/*! @name Object
67568@{ */
67569/// @}
67570
67571
67572/*! @name Editing
67573@{ */
67574/// @}
67575
67576
67577/*! @name Persistence
67578@{ */
67579/// @}
67580
67581};
67582
67583/*!
67584@brief A GUI progress bar useful as a spell casting bar.
67585
67586@ingroup afxGUI
67587@ingroup AFX
67588
67589*/
67590class afxSpellCastBar : public GuiControl {
67591public:
67592/*!
67593@brief Set the progress percentage on the progress-bar.
67594
67595
67596@ingroup AFX*/
67597void setProgress( float percentDone );
67598
67599/*! @name Callbacks
67600@{ */
67601/// @}
67602
67603
67604/*! @name Colors
67605@{ */
67606/*!
67607@brief ...
67608*/
67609LinearColorF backgroundColor;
67610/*!
67611@brief ...
67612*/
67613LinearColorF borderColor;
67614/*!
67615@brief ...
67616*/
67617LinearColorF fillColor;
67618/*!
67619@brief ...
67620*/
67621LinearColorF fillColorFinal;
67622/// @}
67623
67624
67625/*! @name Layout
67626@{ */
67627/// @}
67628
67629
67630/*! @name Control
67631@{ */
67632/// @}
67633
67634
67635/*! @name ToolTip
67636@{ */
67637/// @}
67638
67639
67640/*! @name Editing
67641@{ */
67642/// @}
67643
67644
67645/*! @name Localization
67646@{ */
67647/// @}
67648
67649
67650/*! @name Ungrouped
67651@{ */
67652/// @}
67653
67654
67655/*! @name Object
67656@{ */
67657/// @}
67658
67659
67660/*! @name Editing
67661@{ */
67662/// @}
67663
67664
67665/*! @name Persistence
67666@{ */
67667/// @}
67668
67669};
67670
67671/*!
67672@brief A GUI status bar for tracking and displaying health and energy of ShapeBase objects.
67673
67674@ingroup afxGUI
67675@ingroup AFX
67676
67677*/
67678class afxStatusBar : public GuiControl {
67679public:
67680/*!
67681@brief Set the progress percentage on the status-bar.
67682
67683
67684@ingroup AFX*/
67685void setProgress( float percentDone );
67686/*!
67687@brief Associate a ShapeBase-derived object with the status-bar.
67688
67689
67690@ingroup AFX*/
67691void setShape( ShapeBase shape );
67692/*!
67693@brief Clear out any ShapeBase-derived object associated with the status-bar.
67694
67695
67696@ingroup AFX*/
67697void clearShape();
67698
67699/*! @name Callbacks
67700@{ */
67701/// @}
67702
67703/*!
67704@brief ...
67705*/
67706LinearColorF fillColor;
67707/*!
67708@brief ...
67709*/
67710bool displayEnergy;
67711/*!
67712@brief ...
67713*/
67714bool monitorPlayer;
67715
67716/*! @name Layout
67717@{ */
67718/// @}
67719
67720
67721/*! @name Control
67722@{ */
67723/// @}
67724
67725
67726/*! @name ToolTip
67727@{ */
67728/// @}
67729
67730
67731/*! @name Editing
67732@{ */
67733/// @}
67734
67735
67736/*! @name Localization
67737@{ */
67738/// @}
67739
67740
67741/*! @name Ungrouped
67742@{ */
67743/// @}
67744
67745
67746/*! @name Object
67747@{ */
67748/// @}
67749
67750
67751/*! @name Editing
67752@{ */
67753/// @}
67754
67755
67756/*! @name Persistence
67757@{ */
67758/// @}
67759
67760};
67761
67762/*!
67763@brief A customized variation of GameTSCtrl.
67764
67765@ingroup afxGUI
67766@ingroup AFX
67767
67768*/
67769class afxTSCtrl : public GuiTSCtrl {
67770public:
67771/*!
67772@brief Associate a spellbook with an afxTSCtrl.
67773
67774
67775@ingroup AFX*/
67776void setSpellBook( afxSpellBook spellbook );
67777/*!
67778@brief Push a new targeting-mode onto a statck of modes.
67779
67780
67781@ingroup AFX*/
67782void pushTargetingMode( uint mode=(U32)arcaneFX::TARGETING_OFF, uint checkMethod=(U32)arcaneFX::TARGET_CHECK_POLL );
67783/*!
67784@brief Pop the targeting-mode off a statck of modes.
67785
67786
67787@ingroup AFX*/
67788void popTargetingMode();
67789/*!
67790@brief Get the current targeting-mode.
67791
67792
67793@ingroup AFX*/
67794int getTargetingMode();
67795/*!
67796@brief Get the 3D direction vector for the mouse cursor.
67797
67798
67799@ingroup AFX*/
67800Point3F getMouse3DVec();
67801/*!
67802@brief Get the 3D position of the mouse cursor.
67803
67804
67805@ingroup AFX*/
67806Point3F getMouse3DPos();
67807
67808/*! @name Callbacks
67809@{ */
67810/// @}
67811
67812
67813/*! @name Camera
67814@{ */
67815/// @}
67816
67817
67818/*! @name Rendering
67819@{ */
67820/// @}
67821
67822
67823/*! @name Layout
67824@{ */
67825/// @}
67826
67827
67828/*! @name Layout
67829@{ */
67830/// @}
67831
67832
67833/*! @name Control
67834@{ */
67835/// @}
67836
67837
67838/*! @name ToolTip
67839@{ */
67840/// @}
67841
67842
67843/*! @name Editing
67844@{ */
67845/// @}
67846
67847
67848/*! @name Localization
67849@{ */
67850/// @}
67851
67852
67853/*! @name Ungrouped
67854@{ */
67855/// @}
67856
67857
67858/*! @name Object
67859@{ */
67860/// @}
67861
67862
67863/*! @name Editing
67864@{ */
67865/// @}
67866
67867
67868/*! @name Persistence
67869@{ */
67870/// @}
67871
67872};
67873
67874/*!
67875@brief A type of marker that designates a location AI characters can take cover.
67876
67877
67878@ingroup UNDOCUMENTED
67879
67880*/
67881class CoverPoint : public SceneObject {
67882public:
67883/*!
67884@brief Returns true if someone is already using this cover point.*/
67885bool isOccupied();
67886
67887/*! @name Callbacks
67888@{ */
67889/// @}
67890
67891/*!
67892@brief Disables rendering of all instances of this type.
67893
67894
67895@ingroup UNDOCUMENTED
67896*/
67897static bool isRenderable;
67898/*!
67899@brief Disables selection of all instances of this type.
67900
67901
67902@ingroup UNDOCUMENTED
67903*/
67904static bool isSelectable;
67905
67906/*! @name CoverPoint
67907@{ */
67908/*!
67909@brief The size of this cover point.
67910*/
67911CoverPointSize size;
67912/*!
67913@brief Reliability of this point as solid cover. (0...1)
67914*/
67915float quality;
67916/*!
67917@brief Can characters look left around this cover point?
67918*/
67919bool peekLeft;
67920/*!
67921@brief Can characters look right around this cover point?
67922*/
67923bool peekRight;
67924/*!
67925@brief Can characters look over the top of this cover point?
67926*/
67927bool peekOver;
67928/// @}
67929
67930
67931/*! @name GameObject
67932@{ */
67933/// @}
67934
67935
67936/*! @name Transform
67937@{ */
67938/// @}
67939
67940
67941/*! @name Editing
67942@{ */
67943/// @}
67944
67945
67946/*! @name Mounting
67947@{ */
67948/// @}
67949
67950
67951/*! @name Ungrouped
67952@{ */
67953/// @}
67954
67955
67956/*! @name Object
67957@{ */
67958/// @}
67959
67960
67961/*! @name Editing
67962@{ */
67963/// @}
67964
67965
67966/*! @name Persistence
67967@{ */
67968/// @}
67969
67970};
67971
67972/*! UNDOCUMENTED!
67973@ingroup UNDOCUMENTED
67974 */
67975class NavMesh : public SceneObject {
67976public:
67977/*!
67978@brief Add a link to this NavMesh between two points.
67979
67980
67981*/
67982int addLink( Point3F from, Point3F to, uint flags=0 );
67983/*!
67984@brief Get the off-mesh link closest to a given world point.
67985
67986*/
67987int getLink( Point3F pos );
67988/*!
67989@brief Return the number of links this mesh has.
67990
67991*/
67992int getLinkCount();
67993/*!
67994@brief Get the flags set for a particular off-mesh link.
67995
67996*/
67997int getLinkFlags( uint id );
67998/*!
67999@brief Set the flags of a particular off-mesh link.
68000
68001*/
68002void setLinkFlags( uint id, uint flags );
68003/*!
68004@brief Get the starting point of an off-mesh link.
68005
68006*/
68007Point3F getLinkStart( uint id );
68008/*!
68009@brief Get the ending point of an off-mesh link.
68010
68011*/
68012Point3F getLinkEnd( uint id );
68013/*!
68014@brief Delete a given off-mesh link.
68015
68016*/
68017void deleteLink( uint id );
68018/*!
68019@brief Deletes all off-mesh links on this NavMesh.
68020
68021*/
68022void deleteLinks();
68023/*!
68024@brief Create a Recast nav mesh.*/
68025bool build( bool background=true, bool save=false );
68026/*!
68027@brief Cancel the current NavMesh build.*/
68028void cancelBuild();
68029/*!
68030@brief Rebuild the tiles overlapped by the input box.*/
68031void buildTiles( Box3F box );
68032/*!
68033@brief Build tiles of this mesh where there are unsynchronised links.*/
68034void buildLinks();
68035/*!
68036@brief Remove all cover points for this NavMesh.*/
68037void deleteCoverPoints();
68038/*!
68039@brief Create cover points for this NavMesh.*/
68040bool createCoverPoints();
68041/*!
68042@brief Load this NavMesh from its file.*/
68043bool load();
68044/*!
68045@brief Save this NavMesh to its file.*/
68046void save();
68047
68048/*! @name Callbacks
68049@{ */
68050/// @}
68051
68052/*!
68053@brief Disables rendering of all instances of this type.
68054
68055
68056@ingroup UNDOCUMENTED
68057*/
68058static bool isRenderable;
68059/*!
68060@brief Disables selection of all instances of this type.
68061
68062
68063@ingroup UNDOCUMENTED
68064*/
68065static bool isSelectable;
68066
68067/*! @name NavMesh Options
68068@{ */
68069/*!
68070@brief Name of the data file to store this navmesh in (relative to engine executable).
68071*/
68072string fileName;
68073/*!
68074@brief The method to use to handle water surfaces.
68075*/
68076NavMeshWaterMethod waterMethod;
68077/*!
68078@brief Length/width of a voxel.
68079*/
68080float cellSize;
68081/*!
68082@brief Height of a voxel.
68083*/
68084float cellHeight;
68085/*!
68086@brief The horizontal size of tiles.
68087*/
68088float tileSize;
68089/*!
68090@brief Height of an actor.
68091*/
68092float actorHeight;
68093/*!
68094@brief Maximum climbing height of an actor.
68095*/
68096float actorClimb;
68097/*!
68098@brief Radius of an actor.
68099*/
68100float actorRadius;
68101/*!
68102@brief Maximum walkable slope in degrees.
68103*/
68104float walkableSlope;
68105/*!
68106@brief Is this NavMesh for smaller-than-usual characters?
68107*/
68108bool smallCharacters;
68109/*!
68110@brief Is this NavMesh for regular-sized characters?
68111*/
68112bool regularCharacters;
68113/*!
68114@brief Is this NavMesh for larger-than-usual characters?
68115*/
68116bool largeCharacters;
68117/*!
68118@brief Is this NavMesh for characters driving vehicles?
68119*/
68120bool vehicles;
68121/// @}
68122
68123
68124/*! @name NavMesh Annotations
68125@{ */
68126/*!
68127@brief Name of the SimGroup to store cover points in.
68128*/
68129string coverGroup;
68130/*!
68131@brief Add cover points everywhere, not just on corners?
68132*/
68133bool innerCover;
68134/*!
68135@brief Distance from the edge of the NavMesh to search for cover.
68136*/
68137float coverDist;
68138/*!
68139@brief Distance to the side of each cover point that peeking happens.
68140*/
68141float peekDist;
68142/// @}
68143
68144
68145/*! @name NavMesh Rendering
68146@{ */
68147/*!
68148@brief Display this NavMesh even outside the editor.
68149*/
68150bool alwaysRender;
68151/// @}
68152
68153
68154/*! @name NavMesh Advanced Options
68155@{ */
68156/*!
68157@brief Size of the non-walkable border around the navigation mesh (in voxels).
68158*/
68159int borderSize;
68160/*!
68161@brief Sets the sampling distance to use when generating the detail mesh.
68162*/
68163float detailSampleDist;
68164/*!
68165@brief The maximum distance the detail mesh surface should deviate from heightfield data.
68166*/
68167float detailSampleError;
68168/*!
68169@brief The maximum allowed length for contour edges along the border of the mesh.
68170*/
68171int maxEdgeLen;
68172/*!
68173@brief The maximum distance a simplfied contour's border edges should deviate from the original raw contour.
68174*/
68175float simplificationError;
68176/*!
68177@brief The minimum number of cells allowed to form isolated island areas.
68178*/
68179int minRegionArea;
68180/*!
68181@brief Any regions with a span count smaller than this value will, if possible, be merged with larger regions.
68182*/
68183int mergeRegionArea;
68184/*!
68185@brief The maximum number of polygons allowed in a tile.
68186*/
68187int maxPolysPerTile;
68188/// @}
68189
68190
68191/*! @name GameObject
68192@{ */
68193/// @}
68194
68195
68196/*! @name Transform
68197@{ */
68198/// @}
68199
68200
68201/*! @name Editing
68202@{ */
68203/// @}
68204
68205
68206/*! @name Mounting
68207@{ */
68208/// @}
68209
68210
68211/*! @name Ungrouped
68212@{ */
68213/// @}
68214
68215
68216/*! @name Object
68217@{ */
68218/// @}
68219
68220
68221/*! @name Editing
68222@{ */
68223/// @}
68224
68225
68226/*! @name Persistence
68227@{ */
68228/// @}
68229
68230};
68231
68232/*! UNDOCUMENTED!
68233@ingroup UNDOCUMENTED
68234 */
68235class NavPath : public SceneObject {
68236public:
68237/*!
68238@brief Find a path using the already-specified path properties.*/
68239bool plan();
68240/*!
68241@brief Callback when this path's NavMesh is loaded or rebuilt.*/
68242void onNavMeshUpdate( string data );
68243/*!
68244@brief Callback when a particular area in this path's NavMesh is rebuilt.*/
68245void onNavMeshUpdateBox( string data );
68246/*!
68247@brief Return the number of nodes in this path.*/
68248int size();
68249/*!
68250@brief Get a specified node along the path.*/
68251Point3F getNode( int idx );
68252/*!
68253@brief Get a specified node along the path.*/
68254int getFlags( int idx );
68255/*!
68256@brief Get the length of this path.*/
68257float getLength();
68258
68259/*! @name Callbacks
68260@{ */
68261/// @}
68262
68263/*!
68264@brief Disables rendering of all instances of this type.
68265
68266
68267@ingroup UNDOCUMENTED
68268*/
68269static bool isRenderable;
68270/*!
68271@brief Disables selection of all instances of this type.
68272
68273
68274@ingroup UNDOCUMENTED
68275*/
68276static bool isSelectable;
68277
68278/*! @name NavPath
68279@{ */
68280/*!
68281@brief World location this path starts at.
68282*/
68283Point3F from;
68284/*!
68285@brief World location this path should end at.
68286*/
68287Point3F to;
68288/*!
68289@brief Name of the NavMesh object this path travels within.
68290*/
68291string mesh;
68292/*!
68293@brief Path containing waypoints for this NavPath to visit.
68294*/
68295Path waypoints;
68296/*!
68297@brief Does this path loop?
68298*/
68299bool isLooping;
68300/*!
68301@brief Plan this path over multiple updates instead of all at once.
68302*/
68303bool isSliced;
68304/*!
68305@brief Maximum iterations of path planning this path does per tick.
68306*/
68307int maxIterations;
68308/*!
68309@brief If set, this path will automatically replan when its navigation mesh changes.
68310*/
68311bool autoUpdate;
68312/// @}
68313
68314
68315/*! @name Flags
68316@{ */
68317/*!
68318@brief Allow the path to use dry land.
68319*/
68320bool allowWalk;
68321/*!
68322@brief Allow the path to use jump links.
68323*/
68324bool allowJump;
68325/*!
68326@brief Allow the path to use drop links.
68327*/
68328bool allowDrop;
68329/*!
68330@brief Allow the path to move in water.
68331*/
68332bool allowSwim;
68333/*!
68334@brief Allow the path to jump ledges.
68335*/
68336bool allowLedge;
68337/*!
68338@brief Allow the path to use climb links.
68339*/
68340bool allowClimb;
68341/*!
68342@brief Allow the path to use teleporters.
68343*/
68344bool allowTeleport;
68345/// @}
68346
68347
68348/*! @name NavPath Render
68349@{ */
68350/*!
68351@brief Render this NavPath even when not selected.
68352*/
68353bool alwaysRender;
68354/*!
68355@brief Render this NavPath through other objects.
68356*/
68357bool xray;
68358/*!
68359@brief Render the closed list of this NavPath's search.
68360*/
68361bool renderSearch;
68362/// @}
68363
68364
68365/*! @name GameObject
68366@{ */
68367/// @}
68368
68369
68370/*! @name Transform
68371@{ */
68372/// @}
68373
68374
68375/*! @name Editing
68376@{ */
68377/// @}
68378
68379
68380/*! @name Mounting
68381@{ */
68382/// @}
68383
68384
68385/*! @name Ungrouped
68386@{ */
68387/// @}
68388
68389
68390/*! @name Object
68391@{ */
68392/// @}
68393
68394
68395/*! @name Editing
68396@{ */
68397/// @}
68398
68399
68400/*! @name Persistence
68401@{ */
68402/// @}
68403
68404};
68405
68406/*! UNDOCUMENTED!
68407@ingroup UNDOCUMENTED
68408 */
68409class VController : public SimObject {
68410public:
68411/*!
68412@brief Clears the object and loads the new data from the given filename.
68413
68414@param pFileName The target file to read from.
68415@return Returns true if the read was successful.*/
68416bool readFile( String fileName="" );
68417/*!
68418@brief Detaches and deletes all of the child objects.
68419
68420@return No return value.*/
68421void clear();
68422/*!
68423@brief Reset the Controller's and child object's state.
68424
68425@param pTime The target time to reset to.
68426@return No return value.*/
68427void reset( int time=-1 );
68428/*!
68429@brief Is the sequence currently playing?
68430
68431@return Returns true if the Controller is playing.*/
68432bool isPlaying();
68433/*!
68434@brief Play the sequence. If a value for pTime is specified, the Controller is reset and played from that time.
68435
68436@param pTime The time to start playing the sequence from.
68437@return No return value.*/
68438void play( int time=-1 );
68439/*!
68440@brief Step forward one frame.
68441
68442@return No return value.*/
68443void step();
68444/*!
68445@brief Is the sequence currently paused?
68446
68447@return Returns true if the Controller is paused.*/
68448bool isPaused();
68449/*!
68450@brief Pause the sequence. Playback can resume by calling VController::play().
68451
68452@return No return value.*/
68453void pause();
68454/*!
68455@brief Is the sequence currently stopped?
68456
68457@return Returns true if the Controller is stopped.*/
68458bool isStopped();
68459/*!
68460@brief Stop the sequence and optionally reset it.
68461
68462@param pReset Reset the Controller after stopping.
68463@return No return value.*/
68464void stop( bool reset=true );
68465/*!
68466@brief Get the playback speed. A value > 0.0 will enable the Controller to play forwards, while a value < 0.0 will play backwards.
68467
68468@return Playback Speed.*/
68469float getTimeScale();
68470/*!
68471@brief Set the playback speed. A value > 0.0 will enable the Controller to play forwards, while a value < 0.0 will play backwards. If |pTimeScale| > 1.0, then playback will be faster than normal, while |pTimeScale| < 1.0 will be slower.
68472
68473@param pTimeScale Playback speed.
68474@return No return value.*/
68475void setTimeScale( float timeScale=1 );
68476/*!
68477@brief Is the field a member of the Data Table?
68478
68479@param pFieldName The name of the dynamic field you wish to check.
68480@return Returns true if the field is a member of the Data Table.*/
68481bool isDataField( String fieldName="" );
68482/*!
68483@brief Get the number of data elements in the Data Table.
68484
68485@return Returns the size of the Data Table.*/
68486int getDataFieldCount();
68487/*!
68488@brief Get the name of the field given by the passed index.
68489
68490@param pIndex The index of the data field you wish to check.
68491@return Returns the name of the field corresponding to the given index.*/
68492string getDataFieldName( int index=0 );
68493/*!
68494@brief Get the evaluated data from the data field.
68495
68496@param pFieldName The name of the field you wish to evaluate.
68497@return Returns the evaluated data from the field.*/
68498string getDataFieldValue( String fieldName="" );
68499/*!
68500@brief Get the type of data for the given field.
68501
68502@param pFieldName The name of the field you wish to check.
68503@return Returns the data type.*/
68504string getDataFieldType( String fieldName="" );
68505/*!
68506@brief Save to a given filename.
68507
68508@param pFileName The target file to write to.
68509@return Returns true if the write was successful.*/
68510bool writeFile( String fileName="" );
68511/*!
68512@brief Load data from given filename.
68513
68514@param pFileName The target file to read from.
68515@return Returns true if the read was successful.*/
68516bool readTemplate( String fileName="" );
68517/*!
68518@brief Get the number of child objects.
68519
68520@return Returns the number of child objects.*/
68521int getCount();
68522/*!
68523@brief Get the object corresponding to the given index.
68524
68525@param pIndex The index of the object you wish to retrieve.
68526@return Returns the SimObjectID for the object.*/
68527int getObject( int index=0 );
68528/*!
68529@brief Add a child object to this node.
68530
68531@param pObject The SimObjectID of the object to be added to this node.
68532@return No return value.*/
68533void addObject( SimObject simObj=nullAsType<SimObject*>() );
68534/*!
68535@brief Remove the target object from this node.
68536
68537@param pObject The SimObjectID of the object to be removed from this node.
68538@return No return value.*/
68539void removeObject( SimObject simObj=nullAsType<SimObject*>() );
68540/*!
68541@brief Sort Groups by their Labels.
68542
68543@return No return value.*/
68544void sortGroups();
68545/*!
68546@brief Sort Tracks by their Labels.
68547
68548@return No return value.*/
68549void sortTracks();
68550/*!
68551@brief Add a new data entry to the Data Table.
68552
68553@param pFieldType The method of evaluating the field's data.
68554@param pFieldName The name of the field to be added to the Data Table.
68555@return No return value.*/
68556void addDataField( String fieldType="", String fieldName="" );
68557/*!
68558@brief Remove a data entry from the Data Table.
68559
68560@param pFieldName The name of the field to be removed from the Data Table.
68561@return No return value.*/
68562void removeDataField( String fieldName="" );
68563
68564/*! @name Callbacks
68565@{ */
68566/// @}
68567
68568
68569/*! @name Controller
68570@{ */
68571/*!
68572@brief Current position of the Controller (in milliseconds).
68573*/
68574int Time;
68575/*!
68576@brief Total length of the sequence (in milliseconds).
68577*/
68578int Duration;
68579/*!
68580@brief Speed of playback. A value > 0.0 will enable the Controller to play forwards, while a value < 0.0 will play backwards. If |TimeScale| > 1.0, then playback will be faster than normal, while |TimeScale| < 1.0 will be slower.
68581*/
68582float TimeScale;
68583/*!
68584@brief Instead of stopping once playback is complete, the Controller will reset and resume play.
68585*/
68586bool Loop;
68587/*!
68588@brief When the sequence loops, reverse the direction of play.
68589*/
68590bool LoopBackwards;
68591/*!
68592@brief The number of times the sequence loops before stopping. -1 will cause the sequence to loop indefinitely.
68593*/
68594int LoopCount;
68595/*!
68596@brief When the sequence loops, delay playback by this value (in milliseconds).
68597*/
68598int LoopDelay;
68599/*!
68600@brief When the sequence is completed, reset the state of the Controller.
68601*/
68602bool ResetOnCompletion;
68603/// @}
68604
68605
68606/*! @name Ungrouped
68607@{ */
68608/// @}
68609
68610
68611/*! @name Object
68612@{ */
68613/// @}
68614
68615
68616/*! @name Editing
68617@{ */
68618/// @}
68619
68620
68621/*! @name Persistence
68622@{ */
68623/// @}
68624
68625};
68626
68627/*! UNDOCUMENTED!
68628@ingroup UNDOCUMENTED
68629 */
68630class VShapeAnimationTrack : public VSceneObjectTrack {
68631public:
68632/*!
68633@brief Update the Track.
68634
68635@return No return value.*/
68636void updateTrack();
68637
68638/*! @name Callbacks
68639@{ */
68640/// @}
68641
68642/*!
68643@brief The index of the Animation Thread to play.
68644*/
68645int ThreadIndex;
68646};
68647
68648/*! UNDOCUMENTED!
68649@ingroup UNDOCUMENTED
68650 */
68651class VDirectorTrack : public VTrack {
68652public:
68653/*!
68654@brief Update the Track.
68655
68656@return No return value.*/
68657void updateTrack();
68658
68659/*! @name Callbacks
68660@{ */
68661/// @}
68662
68663};
68664
68665/*! UNDOCUMENTED!
68666@ingroup UNDOCUMENTED
68667 */
68668class VMotionTrack : public VSceneObjectTrack {
68669public:
68670/*!
68671@brief Get the path object this track references.
68672
68673@return Returns the SimObjectID for the object.*/
68674int getPath();
68675
68676/*! @name Callbacks
68677@{ */
68678/// @}
68679
68680/*!
68681@brief The name of the data field referencing the object to be attached to the path.
68682*/
68683string Reference;
68684/*!
68685@brief The orientation mode of the object attached to the path.
68686*/
68687string OrientationMode;
68688/*!
68689@brief The name of the data field holding the orientation data (used for Orientation Modes, ToObject & ToPoint).
68690*/
68691string OrientationData;
68692/*!
68693@brief Attach the object with an offset based on its initial position.
68694*/
68695bool Relative;
68696};
68697
68698/*! UNDOCUMENTED!
68699@ingroup UNDOCUMENTED
68700 */
68701class VEditorButton : public GuiBitmapButtonTextCtrl {
68702public:
68703bool getState();
68704
68705/*! @name Callbacks
68706@{ */
68707/// @}
68708
68709
68710/*! @name Bitmap
68711@{ */
68712/// @}
68713
68714
68715/*! @name Button
68716@{ */
68717/// @}
68718
68719
68720/*! @name Layout
68721@{ */
68722/// @}
68723
68724
68725/*! @name Control
68726@{ */
68727/// @}
68728
68729
68730/*! @name ToolTip
68731@{ */
68732/// @}
68733
68734
68735/*! @name Editing
68736@{ */
68737/// @}
68738
68739
68740/*! @name Localization
68741@{ */
68742/// @}
68743
68744
68745/*! @name Ungrouped
68746@{ */
68747/// @}
68748
68749
68750/*! @name Object
68751@{ */
68752/// @}
68753
68754
68755/*! @name Editing
68756@{ */
68757/// @}
68758
68759
68760/*! @name Persistence
68761@{ */
68762/// @}
68763
68764/*!
68765*/
68766bool IsDraggable;
68767};
68768
68769/*! UNDOCUMENTED!
68770@ingroup UNDOCUMENTED
68771 */
68772class VEditorWindow : public GuiCanvas {
68773public:
68774void resetCursor();
68775/*!
68776@brief Change the video mode of this canvas. This method has the side effect of setting the $pref::Video::mode to the new values.
68777
68778
68779\param width The screen width to set.
68780\param height The screen height to set.
68781\param fullscreen Specify true to run fullscreen or false to run in a window
68782\param bitDepth [optional] The desired bit-depth. Defaults to the current setting. This parameter is ignored if you are running in a window.
68783\param refreshRate [optional] The desired refresh rate. Defaults to the current setting. This parameter is ignored if you are running in a window\param antialiasLevel [optional] The level of anti-aliasing to apply 0 = none*/
68784void setVideoMode( int width=800, int height=600, bool fullscreen=false, int bitDepth=32, int refreshRate=60, int antiAliasLevel=0 );
68785
68786/*! @name Callbacks
68787@{ */
68788/// @}
68789
68790
68791/*! @name Mouse Handling
68792@{ */
68793/// @}
68794
68795
68796/*! @name Canvas Rendering
68797@{ */
68798/// @}
68799
68800
68801/*! @name Layout
68802@{ */
68803/// @}
68804
68805
68806/*! @name Control
68807@{ */
68808/// @}
68809
68810
68811/*! @name ToolTip
68812@{ */
68813/// @}
68814
68815
68816/*! @name Editing
68817@{ */
68818/// @}
68819
68820
68821/*! @name Localization
68822@{ */
68823/// @}
68824
68825
68826/*! @name Ungrouped
68827@{ */
68828/// @}
68829
68830
68831/*! @name Object
68832@{ */
68833/// @}
68834
68835
68836/*! @name Editing
68837@{ */
68838/// @}
68839
68840
68841/*! @name Persistence
68842@{ */
68843/// @}
68844
68845};
68846
68847/*! UNDOCUMENTED!
68848@ingroup UNDOCUMENTED
68849 */
68850class VTimeLineControl : public GuiControl {
68851public:
68852int toPoint( int time=0 );
68853int toTime( int point=0 );
68854string getSelection();
68855void setSelection( bool active=true, int time=-1, int duration=1 );
68856void updateDuration();
68857
68858/*! @name Callbacks
68859@{ */
68860/// @}
68861
68862
68863/*! @name Layout
68864@{ */
68865/// @}
68866
68867
68868/*! @name Control
68869@{ */
68870/// @}
68871
68872
68873/*! @name ToolTip
68874@{ */
68875/// @}
68876
68877
68878/*! @name Editing
68879@{ */
68880/// @}
68881
68882
68883/*! @name Localization
68884@{ */
68885/// @}
68886
68887
68888/*! @name Ungrouped
68889@{ */
68890/// @}
68891
68892
68893/*! @name Object
68894@{ */
68895/// @}
68896
68897
68898/*! @name Editing
68899@{ */
68900/// @}
68901
68902
68903/*! @name Persistence
68904@{ */
68905/// @}
68906
68907/*!
68908*/
68909bool IsController;
68910/*!
68911*/
68912VController Controller;
68913/*!
68914*/
68915int DurationOffset;
68916};
68917
68918/*! UNDOCUMENTED!
68919@ingroup UNDOCUMENTED
68920 */
68921class VPath : public SceneObject {
68922public:
68923/*!
68924@brief The path type dictates how attached objects move between nodes. There are currently two supported path types, "BEZIER" and "LINEAR".
68925
68926@return No return value.*/
68927void setPathType( String pathType="LINEAR" );
68928/*!
68929@brief Add a node with the given properties. Nodes represent physical points that attached objects move towards or between, but the PathType determines "how" they move between them.
68930
68931@param pTransform The position and rotation of the new node.
68932@param pWeight The weight of the new node.
68933@param pLocation The index of the new node.
68934@return No return value.*/
68935void addNode( TransformF transform=MatrixF::Identity, float weight=1.0, int location=-1 );
68936/*!
68937@brief Delete the node with the given index. If you delete a node that an attached object is moving to, or from then the object's movement will adjust so that it has a valid path.
68938
68939@param pNodeIndex The index of the node to be deleted.
68940@return No return value.*/
68941void deleteNode( int nodeIndex=0 );
68942/*!
68943@brief Is the object attached to this path?
68944
68945@param pObject The SimObjectID of the object you wish to check.
68946@return Returns true if the object is attached to this path.*/
68947bool isObjectAttached( SceneObject sceneObject=nullAsType<SceneObject*>() );
68948/*!
68949@brief Attach an object to this path with the given properties. If the object is already attached to a path, then a warning will be displayed and the object will *not* be attached to this path.
68950
68951@param pObject The SimObjectID of the object to be attached.
68952@param pForward Should the object be moving forward?
68953@param pSpeed The speed that the object will travel around the path.
68954@param pRelative Offset the object based on the difference between the start node and its current position.
68955@param pStartNode The index of the node this object starts pathing from.
68956@param pEndNode The index of the node this object will stop pathing at.@return No return value.*/
68957void attachObject( SimObject pObject, bool pForward, float pSpeed, bool pRelative, int pStartNode, [int pEndNode] );
68958/*!
68959@brief Detach the object from this path in place.
68960
68961@param pObject The SimObjectID of the object to be detached.
68962@return No return value.*/
68963void detachObject( SceneObject  sceneObject=nullAsType<SceneObject*>() );
68964/*!
68965@brief Get the transform of the path at the interp point between two nodes.
68966
68967@param pSrcNodeIndex The first node.
68968@param pDstNodeIndex The second node.
68969@param pTimeInterp The time to interp between the two nodes. Value is between 0.0 and 1.0.
68970@return Returns the transform of the interp time between the two given nodes.*/
68971string getPathTransform( int srcNodeIndex=0, int dstNodeIndex=0, float timeInterp=1.0 );
68972/*!
68973@brief Get the world position of the path at the interp point between two nodes.
68974
68975@param pSrcNodeIndex The first node.
68976@param pDstNodeIndex The second node.
68977@param pTimeInterp The time to interp between the two nodes. Value is between 0.0 and 1.0.
68978@return Returns the world position of the interp time between the two given nodes.*/
68979string getPathPosition( int srcNodeIndex=0, int dstNodeIndex=0, float timeInterp=1.0 );
68980/*!
68981@brief Get the number of nodes in this path.
68982
68983@return Returns the number of nodes.*/
68984int getNodeCount();
68985/*!
68986@brief Get the local transform (local position and rotation) of the given node.
68987
68988@param pNodeIndex The index of the node.
68989@return Returns the transform of the given node.*/
68990string getNodeLocalTransform( int nodeIndex=0 );
68991/*!
68992@brief Get the position of the given node.
68993
68994@param pNodeIndex The index of the node.
68995    @return Returns the Local Position of the given node.*/
68996Point3F getNodeLocalPosition( int nodeIndex=0 );
68997/*!
68998@brief Get the Local Rotation of the given node.
68999
69000@param pNodeIndex The index of the node.
69001@return Returns the Local Rotation of the given node.*/
69002AngAxisF getNodeLocalRotation( int nodeIndex=0 );
69003/*!
69004@brief Get the World Transform (position and rotation) of the given node.
69005
69006@param pNodeIndex The index of the node.
69007@return Returns the transform of the given node.*/
69008TransformF getNodeWorldTransform( int nodeIndex=0 );
69009/*!
69010@brief Get the position of the given node.
69011
69012@param pNodeIndex The index of the node.
69013@return Returns the World Position of the given node.*/
69014Point3F getNodeWorldPosition( int nodeIndex=0 );
69015/*!
69016@brief Get the World Rotation of the given node.
69017
69018@param pNodeIndex The index of the node.
69019@return Returns the World Rotation of the given node.*/
69020AngAxisF getNodeWorldRotation( int nodeIndex=0 );
69021/*!
69022@brief Get the weight of the given node.
69023
69024@param pNodeIndex The index of the node.
69025@return Returns the weight of the given node.*/
69026float getNodeWeight( int nodeIndex=0 );
69027/*!
69028@brief Get the length of the given node.
69029
69030@param pNodeIndex The index of the node.
69031@return Returns the length of the given node.*/
69032float getNodeLength( int nodeIndex=0 );
69033/*!
69034@brief Set the transform of the given node.
69035
69036@param pNodeIndex The index of the node.
69037@param pTransform The new transform to be applied to the node.
69038@return No return value.*/
69039void setNodeTransform( int nodeIndex=0, TransformF transform=MatrixF::Identity );
69040/*!
69041@brief Set the position of the given node.
69042
69043@param pNodeIndex The index of the node.
69044@param pPosition The new position to be applied to the node.
69045@return No return value.*/
69046void setNodePosition( int nodeIndex=0, Point3F position=Point3F::Zero );
69047/*!
69048@brief Set the rotation of the given node.
69049
69050@param pNodeIndex The index of the node.
69051@param pRotation The new rotation to be applied to the node.
69052@return No return value.*/
69053void setNodeRotation( int nodeIndex=0, AngAxisF aa=AngAxisF() );
69054/*!
69055@brief Set the weight of the given node.
69056
69057@param pNodeIndex The index of the node.
69058@param pWeight The new weight to be applied to the node.
69059@return No return value.*/
69060void setNodeWeight( int nodeIndex=0, float nodeWeight=1.0 );
69061/*!
69062@brief Gets the current orientation mode of the node.
69063
69064@param pNodeIndex The index of the node.
69065@return Returns a string indicating the orientation mode and its properties.*/
69066string getNodeOrientationMode( int nodeIndex=0 );
69067/*!
69068@brief Set the orientation mode of the node.
69069
69070@param pNodeIndex The index of the node.
69071@param pOrientationType The new orientation type of the object.
69072@param pPoint If the orientation type is set to POINT, this parameter must be a vector.
69073@return No return value.*/
69074void setNodeOrientationMode( int pNodeIndex, string pOrientationType, [vector pPoint] );
69075/*!
69076@brief Is the object actively traveling around this path?
69077
69078@param pObject The SimObjectID of the object being observed.
69079@return Returns true of the object is active.*/
69080bool isPathObjectActive( SceneObject  sceneObject=nullAsType<SceneObject*>() );
69081/*!
69082@brief Enable or disable the object from traveling around this path. Inactive objects are still attached to the path, but are not updated.
69083
69084@param pObject The SimObjectID of the object being altered.
69085@param pActive The new status of the object.
69086@return No return value.*/
69087void setPathObjectActive( SceneObject  sceneObject=nullAsType<SceneObject*>(), bool isActive=true );
69088/*!
69089@brief Get the current interp position of the path object.
69090
69091@param pObject The SimObjectID of the object being observed.
69092@return Returns the current interp position.*/
69093float getPathObjectInterp( SceneObject  sceneObject=nullAsType<SceneObject*>() );
69094/*!
69095@brief Set the interp position of the object between its current nodes.
69096
69097@param pObject The SimObjectID of the object being altered.
69098@param pTimeInterp The new interp position of the object.
69099@return No return value.*/
69100void setPathObjectInterp( SceneObject  sceneObject=nullAsType<SceneObject*>(), float timeInterp=1.0 );
69101/*!
69102@brief Get the position offset assigned to this object.
69103
69104@param pObject The SimObjectID of the object being observed.
69105@return Returns the position offset.*/
69106string getPathObjectOffset( SceneObject  sceneObject=nullAsType<SceneObject*>() );
69107/*!
69108@brief Set the position offset of the object. As the object is moving along the path, its position is offset by this value. Setting the "Relative" parameter while attaching an object will automatically apply an offset value.
69109
69110@param pObject The SimObjectID of the object being altered.
69111@param pOffset The new position offset of the object.
69112@return No return value.*/
69113void setPathObjectOffset( SceneObject  sceneObject=nullAsType<SceneObject*>(), Point3F offset=Point3F::Zero );
69114/*!
69115@brief Get the speed this object is traveling along the path at.
69116
69117@param pObject The SimObjectID of the object being observed.
69118@return Returns the speed of the object.*/
69119float getPathObjectSpeed( SceneObject  sceneObject=nullAsType<SceneObject*>() );
69120/*!
69121@brief Set the speed of the object.
69122
69123@param pObject The SimObjectID of the object being altered.
69124@param pSpeed The new speed of the object.
69125@return No return value.*/
69126void setPathObjectSpeed( SceneObject  sceneObject=nullAsType<SceneObject*>(), float speed=1.0 );
69127/*!
69128@brief Gets the current orientation mode of the object.
69129
69130@param pObject The SimObjectID of the object being observed.
69131@return Returns a string indicating the orientation mode and its properties.*/
69132string getPathObjectOrientationMode( SceneObject  sceneObject=nullAsType<SceneObject*>() );
69133/*!
69134@brief Set the orientation mode of the object. This property affects the rotation of the object. If you wish to ignore the object's rotation altogether, set the mode to "FREE".
69135
69136@param pObject The SimObjectID of the object being altered.
69137@param pOrientationType The new orientation type of the object.
69138@param pObject If the orientation type is set to OBJECT, this parameter must be the SimObjectID of a scene object.
69139@param pPoint If the orientation type is set to POINT, this parameter must be a vector.
69140@return No return value.*/
69141void setPathObjectOrientationMode( SimObject pObject, string pOrientationType, [SimObject pObject / vector pPoint] );
69142/*!
69143@brief Get if this object is traveling forwards along the path.
69144
69145@param pObject The SimObjectID of the object being observed.
69146@return Returns true if the object is traveling forwards.*/
69147bool isPathObjectForward( SceneObject  sceneObject=nullAsType<SceneObject*>() );
69148/*!
69149@brief Set the travel direction of the object.
69150
69151@param pObject The SimObjectID of the object being altered.
69152@param pForward The direction of the object.
69153@return No return value.*/
69154void setPathObjectForward( SceneObject  sceneObject=nullAsType<SceneObject*>(), bool forward=true );
69155/*!
69156@brief Gets the last node of the object.
69157
69158@param pObject The SimObjectID of the object being observed.
69159@return Returns the node index.*/
69160int getPathObjectNode( SceneObject  sceneObject=nullAsType<SceneObject*>() );
69161/*!
69162@brief Move the object to the node's position. You may also want to observe the "setPathObjectInterp" method.
69163
69164@param pObject The SimObjectID of the object being altered.
69165@param pNodeIndex The index of the node that the object will reposition to.
69166@return No return value.*/
69167void setPathObjectNode( SceneObject  sceneObject=nullAsType<SceneObject*>(), int nodeIndex=0 );
69168/*!
69169@brief Get the index of the node this object is meant to stop upon reaching.
69170
69171@param pObject The SimObjectID of the object being observed.
69172@return Returns the node index.*/
69173int getPathObjectEndNode( SceneObject  sceneObject=nullAsType<SceneObject*>() );
69174/*!
69175@brief Set end node of the path object. If a value of "-1" is applied, the object will path indefinitely.
69176
69177@param pObject The SimObjectID of the object being altered.
69178@param pNodeIndex The index of the node that the object will cease pathing upon reaching.
69179@return No return value.*/
69180void setPathObjectEndNode( SceneObject  sceneObject=nullAsType<SceneObject*>(), int nodeIndex=0 );
69181
69182/*! @name Callbacks
69183@{ */
69184/// @}
69185
69186/*!
69187@brief Disables rendering of all instances of this type.
69188
69189
69190@ingroup UNDOCUMENTED
69191*/
69192static bool isRenderable;
69193/*!
69194@brief Disables selection of all instances of this type.
69195
69196
69197@ingroup UNDOCUMENTED
69198*/
69199static bool isSelectable;
69200
69201/*! @name GameObject
69202@{ */
69203/// @}
69204
69205
69206/*! @name Transform
69207@{ */
69208/// @}
69209
69210
69211/*! @name Editing
69212@{ */
69213/// @}
69214
69215
69216/*! @name Mounting
69217@{ */
69218/// @}
69219
69220
69221/*! @name Ungrouped
69222@{ */
69223/// @}
69224
69225
69226/*! @name Object
69227@{ */
69228/// @}
69229
69230
69231/*! @name Editing
69232@{ */
69233/// @}
69234
69235
69236/*! @name Persistence
69237@{ */
69238/// @}
69239
69240/*!
69241@brief The type of path this is.
69242*/
69243VPathType PathType;
69244};
69245
69246/*! UNDOCUMENTED!
69247@ingroup UNDOCUMENTED
69248 */
69249class VPathEditor : public EditTSCtrl {
69250public:
69251void clearSelection();
69252void setSelection( SceneObject sceneObject=nullAsType<SceneObject*>(), int nodeIndex=-1 );
69253bool isValidSelection();
69254int getSelectedPath();
69255int getSelectedNode();
69256void deleteSelection();
69257void setNodePosition( Point3F position=Point3F::Zero );
69258void setNodeRotation( AngAxisF aa=AngAxisF( Point3F( 0, 0, 1 ), 0) );
69259void setNodeWeight( float weight=1 );
69260void setNodeOrientationMode( String orientationType="", Point3F lookAtPoint=Point3F::One );
69261
69262/*! @name Callbacks
69263@{ */
69264/// @}
69265
69266/*!
69267*/
69268bool isDirty;
69269/*!
69270*/
69271VPathEditorMode EditMode;
69272
69273/*! @name Grid
69274@{ */
69275/// @}
69276
69277
69278/*! @name Mission Area
69279@{ */
69280/// @}
69281
69282
69283/*! @name BorderMovement
69284@{ */
69285/// @}
69286
69287
69288/*! @name Misc
69289@{ */
69290/// @}
69291
69292
69293/*! @name Camera
69294@{ */
69295/// @}
69296
69297
69298/*! @name Rendering
69299@{ */
69300/// @}
69301
69302
69303/*! @name Layout
69304@{ */
69305/// @}
69306
69307
69308/*! @name Layout
69309@{ */
69310/// @}
69311
69312
69313/*! @name Control
69314@{ */
69315/// @}
69316
69317
69318/*! @name ToolTip
69319@{ */
69320/// @}
69321
69322
69323/*! @name Editing
69324@{ */
69325/// @}
69326
69327
69328/*! @name Localization
69329@{ */
69330/// @}
69331
69332
69333/*! @name Ungrouped
69334@{ */
69335/// @}
69336
69337
69338/*! @name Object
69339@{ */
69340/// @}
69341
69342
69343/*! @name Editing
69344@{ */
69345/// @}
69346
69347
69348/*! @name Persistence
69349@{ */
69350/// @}
69351
69352};
69353
69354/*! @addtogroup Atmosphere */
69355
69356/*! @addtogroup gameObjects */
69357
69358/*! @addtogroup Shaders */
69359
69360/*! @addtogroup Logging */
69361
69362/*! @addtogroup GuiValues */
69363
69364/*! @addtogroup @section */
69365
69366/*! @addtogroup AFX */
69367
69368/*! @addtogroup SFX */
69369
69370/*! @addtogroup Assets */
69371
69372/*! @addtogroup Lighting */
69373
69374/*! @addtogroup Scripting */
69375
69376/*! @addtogroup Font */
69377
69378/*! @addtogroup GFX */
69379
69380/*! @addtogroup Localization */
69381
69382/*! @addtogroup FileSearches */
69383
69384/*! @addtogroup Messaging */
69385
69386/*! @addtogroup GuiUtil */
69387
69388/*! @addtogroup CameraSystem */
69389
69390/*! @addtogroup Random */
69391
69392/*! @addtogroup Networking */
69393
69394/*! @addtogroup afxUtil */
69395
69396/*! @addtogroup Examples */
69397
69398/*! @addtogroup GuiControls */
69399
69400/*! @addtogroup enviroMisc */
69401
69402/*! @addtogroup Utilities */
69403
69404/*! @addtogroup Terrain */
69405
69406/*! @addtogroup Matrices */
69407
69408/*! @addtogroup Gui3D */
69409
69410/*! @addtogroup Vehicles */
69411
69412/*! @addtogroup Input */
69413
69414/*! @addtogroup FieldManip */
69415
69416/*! @addtogroup FX */
69417
69418/*! @addtogroup Rendering */
69419
69420/*! @addtogroup Forest */
69421
69422/*! @addtogroup Math */
69423
69424/*! @addtogroup afxChoreographers */
69425
69426/*! @addtogroup afxEffects */
69427
69428/*! @addtogroup Packages */
69429
69430/*! @addtogroup Platform */
69431
69432/*! @addtogroup BaseCamera */
69433
69434/*! @addtogroup Debugging */
69435
69436/*! @addtogroup Foliage */
69437
69438/*! @addtogroup GuiGame */
69439
69440/*! @addtogroup FileSystem */
69441
69442/*! @addtogroup Game */
69443
69444/*! @addtogroup UNDOCUMENTED */
69445
69446/*! @addtogroup Decals */
69447
69448/*! @addtogroup afxMisc */
69449
69450/*! @addtogroup Vectors */
69451
69452/*! @addtogroup PathCameras */
69453
69454/*! @addtogroup Materials */
69455
69456/*! @addtogroup Physics */
69457
69458/*! @addtogroup GuiCore */
69459
69460/*! @addtogroup AI */
69461
69462/*! @addtogroup RenderBin */
69463
69464/*! @addtogroup afxExperimental */
69465
69466/*! @addtogroup GuiButtons */
69467
69468/*! @addtogroup Strings */
69469
69470/*! @addtogroup GuiImages */
69471
69472/*! @addtogroup GuiContainers */
69473
69474/*! @addtogroup afxXMods */
69475
69476/*! @addtogroup afxGUI */
69477
69478/*! @addtogroup Water */
69479
69480/*! @addtogroup Console */
69481
69482