ParaScripting::ParaScene Class Reference
[ParaScene]

List of all members.

---

Detailed Description

ParaScene namespace contains a list of HAPI functions to create and modify scene objects in paraworld.

The following are basic steps to create scene object:

• Use Create*() functions to create scene object. The created object is return as a ParaObject instance.
• Use the ParaObject instance to modify the position and orientation of the object.
• Use Attach method to insert the scene object to the scene.

Please note: if an object is created without attaching to the scene, it may result in memory leak. although, we may automatically clear unattached scene object, when the application quit.

Static Public Member Functions
static ParaAttributeObject	GetAttributeObject ()
	get the attribute object associated with the global scene.
static void	GetAttributeObject_ (ParaAttributeObject &output)
	used for API exportation.
static ParaAttributeObject	GetAttributeObjectSky ()
	get the attribute object associated with the current sky object.
static void	GetAttributeObjectSky_ (ParaAttributeObject &output)
	used for API exportation.
static ParaAttributeObject	GetAttributeObjectPlayer ()
	get the attribute object associated with the current player.
static void	GetAttributeObjectPlayer_ (ParaAttributeObject &output)
	used for API exportation.
static ParaAttributeObject	GetAttributeObjectOcean ()
	get the attribute object associated with the global ocean manager.
static void	GetAttributeObjectOcean_ (ParaAttributeObject &output)
	used for API exportation.
static ParaObject	GetObject (const char *strObjName)
	get the scene object by name.
static ParaObject	GetObject3 (float x, float y, float z)
	get the first local object,whose position is very close to vPos.
static ParaObject	GetObject4 (float x, float y, float z, float fEpsilon)
	get the first object that matches the position within fEpsilon, which is usually 0.01f
static void	GetObject_ (ParaObject *pOut, const char *strObjName)
	this function shall never be called from the scripting interface.
static ParaObject	GetPlayer ()
	Get the current player.
static void	GetPlayer_ (ParaObject *pOut)
	this function shall never be called from the scripting interface.
static ParaObject	GetNextObject (ParaObject &obj)
	get the next scene object.
static void	CreateWorld (const char *sWorldName, float fWorldSize, const char *sConfigFile)
	Create a new parallel world of a given size.
static void	Reset ()
	reset the scene to blank.
static ParaObject	CreateManagedLoader (const char *sLoaderName)
	Create a managed loader for dynamic scene object loading and unloading.
static void	CreateGlobalTerrain (float fRadius, int nDepth, const char *sHeightmapfile, float fTerrainSize, float fElevscale, int bSwapvertical, const char *sMainTextureFile, const char *sCommonTextureFile, int nMaxBlockSize, float fDetailThreshold)
	Create and set the global terrain from height map and texture files.
static void	Attach (ParaObject &pObj)
	Attach the object to the current root scene according to its type and position.
static void	Delete (ParaObject &pObj)
	delete the object.
static void	Detach (ParaObject &pObj)
	detach the object.
static void	FireMissile (int nMissileID, float fSpeed, float fromX, float fromY, float fromZ, float toX, float toY, float toZ)
	fire a missile from (fromX, fromY, fromZ) to (toX, toY, toZ) using the specified missile object and speed.
static void	FireMissile1 (const char *assetname, float fSpeed, float fromX, float fromY, float fromZ, float toX, float toY, float toZ)
static void	FireMissile2 (ParaAssetObject &asset, float fSpeed, float fromX, float fromY, float fromZ, float toX, float toY, float toZ)
static void	SetModified (bool bModified)
	set whether scene is modified
static bool	IsModified ()
	Get whether scene is modified.
static bool	IsScenePaused ()
	when a scene is paused, all animation will be frozen.
static void	PauseScene (bool bEnable)
	pause the scene
static bool	IsSceneEnabled ()
	whether 3D scene is enabled or not.
static void	EnableScene (bool bEnable)
	enable the scene
static ParaObject	CreateMeshObject (const char *strObjectName, const char *strMeshAssetName, float fOBB_X, float fOBB_Y, float fOBB_Z, float fFacing, bool bSolid, const char *localMatrix)
	create a simple and static mesh object in the scene.
static ParaObject	CreateMeshObject (const char *strObjectName, ParaAssetObject &asset, float fOBB_X, float fOBB_Y, float fOBB_Z, float fFacing, bool bSolid, const char *localMatrix)
static ParaObject	CreateZone (const char *sZoneName, const char *sBoundingVolumes, float width, float height, float depth, float facing)
	create a portal zone object for portal rendering.
static ParaObject	CreatePortal (const char *sPortalName, const char *sHomeZone, const char *sTargetZone, const char *sQuadVertices, float width, float height, float depth, float facing)
	create a portal object for portal rendering
static ParaObject	CreateVoxelMesh (const char *strObjectName, const char *sGridFileName, const char *sTextureFileName)
	create a voxel mesh object.
static bool	CreateSkyBox (const char *strObjectName, const char *strMeshAssetName, float fScaleX, float fScaleY, float fScaleZ, float fHeightOffset)
	create a sky box and add it to the current list.
static bool	CreateSkyBox_ (const char *strObjectName, ParaAssetObject &asset, float fScaleX, float fScaleY, float fScaleZ, float fHeightOffset)
static void	DeleteSkyBox (const char *strObjectName)
	delete a name sky box.
static ParaObject	CreateFloor (const char *strObjectName, const char *strSpriteAssetName, const char *strTextureAssetName, float fWidth, float fDepth, float fFacing)
	Create animated floor: a plane.
static ParaObject	CreateMeshPhysicsObject (const char *strObjectName, const char *strMeshAssetName, float fOBB_X, float fOBB_Y, float fOBB_Z, bool bApplyPhysics, const char *localMatrix)
	Create static triangle mesh based actor for novodex physics engine.
static ParaObject	CreateMeshPhysicsObject (const char *strObjectName, ParaAssetObject &asset, float fOBB_X, float fOBB_Y, float fOBB_Z, bool bApplyPhysics, const char *localMatrix)
static void	CreateMeshPhysicsObject__ (ParaObject *pOut, const char *strObjectName, ParaAssetObject &asset, float fOBB_X, float fOBB_Y, float fOBB_Z, bool bApplyPhysics, const char *localMatrix)
	this function shall never be called from the scripting interface.
static ParaObject	CreateLightObject (const char *strObjectName, float fPosX, float fPosY, float fPosZ, const char *sLightParams, const char *localMatrix)
	Create a new light object.
static ParaObject	CreateDynamicPhysicsObject (const char *strObjectName, const char *strMeshAssetName, float fOBB_X, float fOBB_Y, float fOBB_Z, bool bRenderMesh)
	Create dynamic physics actor for novodex physics engine.
static ParaObject	CreateCharacter (const char *strObjectName, const char *strMultiAnimationAssetName, const char *strScript, bool bIsGlobal, float fRadius, float fFacing, float fScaling)
	Create Character.
static ParaObject	CreateCharacter (const char *strObjectName, ParaAssetObject &asset, const char *strScript, bool bIsGlobal, float fRadius, float fFacing, float fScaling)
static void	CreateCharacter__ (ParaObject *pOut, const char *strObjectName, ParaAssetObject &asset, const char *strScript, bool bIsGlobal, float fRadius, float fFacing, float fScaling)
	this function shall never be called from the scripting interface.
static void	Play3DSound (const char *strSoundAssetName, float fX, float fY, float fZ)
	play a 3D sound at world location (fx, fy, fz).
static void	SetGlobalWater (bool bEnable, float fWaterLevel)
	Set the global water drawing attribute.
static float	GetGlobalWaterLevel ()
	get the current global water level in meters.
static bool	IsGlobalWaterEnabled ()
	return true if global ocean water is enabled.
static void	UpdateOcean ()
	call this function, when the ocean has changed or the environment has changed.
static void	AddWaterRipple (float x, float y, float z)
	add water ripple to the ocean surface.
static void	Execute (const char *strCmd)
	execute the scene command string.
static ParaObject	MousePick (float fMaxDistance, const char *sFilterFunc)
	Pick scene object at the current mouse cursor position.
static int	SelectObject (int nGroupIndex, float x, float y, float z, float radius, const char *sFilterFunc)
	select select objects within a given region into a given group.
static int	SelectObject1 (int nGroupIndex, float x1, float y1, float z1, float x2, float y2, float z2, float fRotY, const char *sFilterFunc)
	Parameters: x1,y1,z1,x2,y2,z2,fRotY,:  a bounding box: two diagonal points in world space and rotation around Y.
static void	RegisterEvent (const char *sID, const char *sScript)
	register a mouse or key event handler
static void	RegisterEvent1 (DWORD nEventType, const char *sID, const char *sScript)
	same as above RegisterEvent(), except that it allows caller to explicitly specify the event type, instead of deriving it from the event name.
static void	UnregisterEvent (const char *sID)
	unregister a mouse or key event handler
static void	UnregisterAllEvent ()
	unregister all mouse or key event handler
static void	EnableMouseClick (bool bEnable)
	whether the game engine will automatically generate mouse events for Game Objects.If true, The OnClick callback will be automatically called whenever there is a mouse click.
static ParaObject	GetCurrentActor ()
	get the actor that is being processed by the AI module or a script call back.
static void	SetCurrentActor (ParaObject pActor)
	Set the actor that is being processed by the AI module or a script call back.
static ParaObject	TogglePlayer ()
	It changes the current player to the next player in the scene.
static ParaObject	GetObjectByViewBox (const object &viewbox)
	get an object(usually a static mesh object) by a given view box.
static int	GetActionMeshesBySphere (const object &inout, float x, float y, float z, float radius)
	get the action meshes within or intersect a sphere.
static int	GetObjectsBySphere (const object &inout, float x, float y, float z, float radius, const char *sFilterFunc)
	Parameters: inout,:  input and output, it should be an empty table.
static int	GetObjectsByScreenRect (const object &inout, int left, int top, int right, int bottom, const char *sFilterFunc, float fMaxDistance)
	Get objects inside or intersect with a screen rect.
static void	OnTerrainChanged (float x, float y, float fRadius)
	This function is called manually to update characters in a square region.
static int	SaveAllCharacters ()
	save all local characters in the scene to the current NPC database regardless of whether they are modified or not this function is usually called manually in some very rare cases.
static void	ShowHeadOnDisplay (bool bShow)
	show or hide all scene's objects' head on display
static bool	IsHeadOnDisplayShown ()
	whether all scene's objects' head on display
static void	SetTimeOfDay (float time)
	set time of day in seconds.
static void	SetTimeOfDaySTD (float time)
	set standard time.
static float	GetTimeOfDay ()
	get the current time of day in seconds.
static float	GetTimeOfDaySTD ()
	get standard time.
static void	SetMaximumAngle (float fMaxAngle)
	set the maximum sun angle with the Y (up) axis.
static float	AdvanceTimeOfDay (float timeDelta)
	advance time is in seconds, this will also change the light direction, sun color and sun ambient color.
static void	SetDayLength (float fMinutes)
	set how many minutes are there in a day, this is used in time simulation.
static float	GetDayLength ()
	return how many minutes are there in a day in minutes
static void	SetShadowMethod (int nMethod)
	the current shadow method:both shadow volume and shadow mapping could be set.
static int	GetShadowMethod ()
static void	EnableLighting (bool bEnable)
	Enable both global and local lighting.
static bool	IsLightingEnabled ()
static void	SetFog (bool bRenderFog, const char *strFogColor, float fFogStart, float fFogEnd, float fFogDensity)
	set the global fog effect
static Para3DCanvas	Get3DCanvas (int nIndex)
	get the 3D canvas object at the specified index.
static void	Get3DCanvas__ (Para3DCanvas *pCanvas, int nIndex)
	this is solely used for API exporting.
static void	Enable3DCanvas (int nIndex, bool bEnabled)
	enable a canvas at the given index.
static int	GetTotalCanvasNum ()
	get the total number of enabled and/or disabled 3d canvas in the scene.
static ParaMiniSceneGraph	GetMiniSceneGraph (const char *name)
	If the mini scene graph does not exist, it will be created.
static int	DeleteMiniSceneGraph (const char *name)
	Delete mini scene graphs by name.
static void	EnableMiniSceneGraph (bool bEnable)
	enable to render all mini scene graphs
static bool	IsMiniSceneGraphEnabled ()
	enable to render all mini scene graphs
static ParaMiniSceneGraph	GetPostProcessingScene ()
	get the post processing mini scene graph.
static void	EnablePostProcessing (bool bEnable, const char *sCallbackScript)
	set whether post processing is enabled.
static bool	IsPostProcessingEnabled ()
	get whether post processing is enabled.

---

Member Function Documentation

ParaAttributeObject ParaScripting::ParaScene::GetAttributeObject

(

)

[static]

get the attribute object associated with the global scene.

void ParaScripting::ParaScene::GetAttributeObject_

(

ParaAttributeObject &

output

)

[static]

used for API exportation.

ParaAttributeObject ParaScripting::ParaScene::GetAttributeObjectSky

(

)

[static]

get the attribute object associated with the current sky object.

void ParaScripting::ParaScene::GetAttributeObjectSky_

(

ParaAttributeObject &

output

)

[static]

used for API exportation.

ParaAttributeObject ParaScripting::ParaScene::GetAttributeObjectPlayer

(

)

[static]

get the attribute object associated with the current player.

void ParaScripting::ParaScene::GetAttributeObjectPlayer_

(

ParaAttributeObject &

output

)

[static]

used for API exportation.

ParaAttributeObject ParaScripting::ParaScene::GetAttributeObjectOcean

(

)

[static]

get the attribute object associated with the global ocean manager.

void ParaScripting::ParaScene::GetAttributeObjectOcean_

(

ParaAttributeObject &

output

)

[static]

used for API exportation.

ParaObject ParaScripting::ParaScene::GetObject

(

const char *

strObjName

)

[static]

get the scene object by name.

currently, the object must be global, in order to be found by its name.

Remarks:

: if local mesh's name begins with "g_", it can also be retrieved by calling this function. however, if a global object has the same name, the global object is always returned instead of the local mesh.

Parameters:

strObjName,:

the format of the name is as below: strObjName := [<_type>]string _type := managed_loader | OPC | NPC | player | zone | portal e.g. strObjName = "creatures1" or "<managed_loader>sceneloader1" or "<player>".

extract the type information from the name.

search for each type

ParaObject ParaScripting::ParaScene::GetObject3	(	float	x,
		float	y,
		float	z
	)			[static]

get the first local object,whose position is very close to vPos.

This function will search for the first (local mesh) object throughout the hierachy of the scene. this function is kind of slow, please do not call on a per frame basis. Use GetObjectByViewBox() to get an object faster.

Parameters:

	vPos,:	world position of the local mesh object
	fEpsilon,:	if a mesh is close enough to vPos within this value.

Returns:

: NULL if not found

void ParaScripting::ParaScene::GetObject_	(	ParaObject *	pOut,
		const char *	strObjName
	)			[static]

this function shall never be called from the scripting interface.

this is solely for exporting API. and should not be used from the scripting interface.

ParaObject ParaScripting::ParaScene::GetPlayer

(

)

[static]

Get the current player.

same as ParaScene.GetObject("<player>").

void ParaScripting::ParaScene::GetPlayer_

(

ParaObject *

pOut

)

[static]

this function shall never be called from the scripting interface.

this is solely for exporting API. and should not be used from the scripting interface.

ParaObject ParaScripting::ParaScene::GetNextObject

(

ParaObject &

obj

)

[static]

get the next scene object.

Parameters:

obj,:

the object whose next object is retrieved.

Returns:

: return the next object. the returned object is invalid if there is only one object left.

void ParaScripting::ParaScene::CreateWorld	(	const char *	sWorldName,
		float	fWorldSize,
		const char *	sConfigFile
	)			[static]

Create a new parallel world of a given size.

When this function is called, it will replace previously created world of the same name. Currently only a single world can be created at any given time. In future, we will support hosting several world simultaneously.

Parameters:

	sWorldName,:	name of the world to be created.
	fWorldSize,:	the size of the world in meters.
	sConfigFile,:	the file name of the configuration file. Currently it is the same as the terrain configuration file

the quad tree depth is automatically calculated. The smallest quad tree tile is of size 128 meters.

void ParaScripting::ParaScene::Reset

(

)

[static]

reset the scene to blank.

this function is NOT automatically called when a new isolated world is created. so one need to call Reset() when it wants to change the world, otherwise the new world will be merged into the previous world.

See also:

CreateWorld()

ParaObject ParaScripting::ParaScene::CreateManagedLoader

(

const char *

sLoaderName

)

[static]

Create a managed loader for dynamic scene object loading and unloading.

The behavior of a managed loader is below:

• The child objects of a managed loader will be automatically loaded and unloaded as a single entity.
• Generally only static objects are attached to a managed loader.
• Different managed loaders in a ParaScene must have different names.
• if one create a manager loader with the same name several times, the same managed loader will be returned.
• the bounding box of a managed loader will be automatically calculated as new child objects are attached to it.
• The current loader algorithm will linearly transverse all managed loaders in the scene to decide which scene objects to load or unload. Although the routine is executed when the CPU is free, it is good practice to keep the total number of managed loaders in a single scene low. I think a couple of thousand loaders will be fine for current hardware.
• it is good practice to use managed loaders to group all static scene objects that appears in a scene. Because, it will keep the scene graph to a moderate size automatically and accelerate physics calculation, etc.

The following NPL code shows typical usage of the managed loader. Generally a managed loader and its children are written in a single script file. Then, any other script can call dofile() or NPL.ActivateCopy() to run the script as many times as they like. The code however will ensure that objects managed by the loader will only be created and attached once in the game engine.There may be a setting in ParaEngine to do automatic garbage collection with managed loaders, so one may need to call the following script file often enough for the managed objects to stay active in the game scene.

local sceneLoader = ParaScene.GetObject("<managed_loader>scene2");
if (sceneLoader:IsValid() == true) then
-- if the scene loader already exists, just attach it to the scene.
ParaScene.Attach(sceneLoader);
else
-- if the scene loader is not created before, we will create it now
sceneLoader = ParaScene.CreateManagedLoader("scene2");
ParaAsset.LoadMultiAnimation("tiny", "Units/Human/Peasant/peasant.mdx");

-- create scene objects and add them to managed loader object
local player;
player = ParaScene.CreateCharacter ("LiXizhi2", "tiny", "", false, 0.5, 0, 1.0);
player:SetPosition(21758, 0, 16221);
player:SnapToTerrainSurface(0);
sceneLoader:AddChild(player);

-- attach all objects in the loader to the scene graph
ParaScene.Attach(sceneLoader);
end

Parameters:

sLoaderName,:

the name of the loader.

See also:

CManagedLoaderObject in ParaEngine reference.

void ParaScripting::ParaScene::CreateGlobalTerrain	(	float	fRadius,
		int	nDepth,
		const char *	sHeightmapfile,
		float	fTerrainSize,
		float	fElevscale,
		int	bSwapvertical,
		const char *	sMainTextureFile,
		const char *	sCommonTextureFile,
		int	nMaxBlockSize,
		float	fDetailThreshold
	)			[static]

Create and set the global terrain from height map and texture files.

this function can be called multiple times, in which cases previously loaded terrain will be discarded example: ParaScene.CreateGlobalTerrain(2048, 7, "LlanoElev.png", 5.0, 15.0, 1, "LlanoTex.jpg", "dirt2.jpg", 64, 10.0");

Parameters:

	fRadius,:	entire terrain size, this has doing to do with the actual terrain map size, it just prevent mobile characters from walking outside it.
	nDepth,:	depth of the quad tree terrain hierarchy. objects created on the terrain will be organized in a quad tree. This is the depth of the quad tree. It should not be too big. usually 7 is enough. the rest of the parameters specify the data to render the terrain.
	sHeightmapfile,:	the height map used to create the terrain. It must be sized to 2*2*...*2 pixels for both height and width. so usually it is 1024*1024, 2048*2048, etc.
	fTerrainSize,:	the actual terrain size in the game
	bSwapvertical,:	if one want to swap the height map data vertically.
	sMainTextureFile,:	texture to be mapped to entire terrain
	sCommonTextureFile,:	texture to be tiles to the entire terrain to add some details.
	nMaxBlockSize,:	When doing LOD with the height map, the max block size must be smaller than this one. This will be (nMaxBlockSize*nMaxBlockSize) sized region on the height map.
	fDetailThreshold,:	we will use a LOD block to approximate the terrain at its location, if the block is smaller than fDetailThreshold pixels when projected to the 2D screen.

void ParaScripting::ParaScene::Attach

(

ParaObject &

pObj

)

[static]

Attach the object to the current root scene according to its type and position.

some further initialization might be performed after an object is inserted to the scene. please refer to individual object type for details. the attachment location is:

• global bipeds are attached to the root scene object.
• static objects are attached to some location in the quad tree terrain tiles. If the object has already been attached to the scene, this function takes no effect. however, if the object is a static scene object and has been moved between two Attach() functions. then the second call to Attach() function will detach the object from the scene, and re-attach it to the scene according to the new position.

void ParaScripting::ParaScene::Delete

(

ParaObject &

pObj

)

[static]

delete the object.

If the object is root scene object, then the entire scene is deleted.

void ParaScripting::ParaScene::Detach

(

ParaObject &

pObj

)

[static]

detach the object.

Be sure that the object is properly deleted after it is detached from the scene, because the scene graph is not responsible to manage it any more. The only exception is the managed loader object.

See also:

CreateManagedLoader(const char * sLoaderName)

void ParaScripting::ParaScene::FireMissile	(	int	nMissileID,
		float	fSpeed,
		float	fromX,
		float	fromY,
		float	fromZ,
		float	toX,
		float	toY,
		float	toZ
	)			[static]

fire a missile from (fromX, fromY, fromZ) to (toX, toY, toZ) using the specified missile object and speed.

bool ParaScripting::ParaScene::IsScenePaused

(

)

[static]

when a scene is paused, all animation will be frozen.

bool ParaScripting::ParaScene::IsSceneEnabled

(

)

[static]

whether 3D scene is enabled or not.

a disabled scene is not visible no matter what. This function must be called at least once whenever a new scene is loaded, or 3D scene will not be displayed. A scene is automatically disabled when cleaned up.

ParaObject ParaScripting::ParaScene::CreateMeshObject	(	const char *	strObjectName,
		const char *	strMeshAssetName,
		float	fOBB_X,
		float	fOBB_Y,
		float	fOBB_Z,
		float	fFacing,
		bool	bSolid,
		const char *	localMatrix
	)			[static]

create a simple and static mesh object in the scene.

Solid mesh will collide with mobile characters. Simple mesh does not implement clipping optimization, hence should not be very large. It is good to use it

Parameters:

	strMeshAssetName,:	for small houses, trees, stones, small hills, etc. when naming mesh file, one can combine "_a"(no physics), "_b"(billboard), "_t"(transparent), "_d"(dim or no lighting), "_r"(receive shadow) in the file name in any order, such as "xxx_b_t_d.x". all such special file endings are listed below "_a": no physics, it will have no physics, even bApplyPhysics is true. For example. "grass_a.x". "_b": billboarded and no physics "_r": mesh is shadow receiver "_t": mesh contains majority transparent objects. Please note that this is different from alpha testing. Transparency throguh alpha testing is not transparent. "_p": mesh is picture or particles. They are rendered with billboarding and Force No Light flag on. "_d": mesh is dim and is rendered with force no light on. "_v": mesh is rendered with vegetation shader. the static model like palm trees, grasses, bamboos can be animated by this shader.
	fOBB_X,:	object bounding box.x
	fOBB_Y,:	object bounding box.y
	fOBB_Z,:	object bounding box.z
	fFacing,:	rotation of the bounding box around the y axis.
	bSolid,:	1, if it is a solid mesh, otherwise it is passable.
	localMatrix,:	the local transformation matrix of the mesh. It is a string of 4*3 number of float values separated by comma (see below): "mat._11, mat._12, mat._13, mat._21, mat._22, mat._23,mat._31, mat._32, mat._33,mat._41, mat._42, mat._43" If a blank string("") is specified, the local matrix is set to identity matrix.

ParaScripting::ParaObject ParaScripting::ParaScene::CreateZone	(	const char *	sZoneName,
		const char *	sBoundingVolumes,
		float	width,
		float	height,
		float	depth,
		float	facing
	)			[static]

create a portal zone object for portal rendering.

Parameters:

	sZoneName,:	it must be unique.
	fRadius,:	the zone sphere radius is an approximation of the bounding volume. we will only further check if an object is inside a zone, if it is first inside this sphere.
	sBoundingVolumes,:	if this is "", the zone will not be able to automatically determine which mobile objects are in it. or it can be "x1,y1,z1;x2,y2,z2;x3,y3,z3;" each three value is a point in local space denoting a plane of the bounding volume. because the convex bounding volume in local space always contains the origin, three values is enough to represent a plane in the bounding volume.
	width,height,depth,facing,:	the bounding shape of the portal.

ParaScripting::ParaObject ParaScripting::ParaScene::CreatePortal	(	const char *	sPortalName,
		const char *	sHomeZone,
		const char *	sTargetZone,
		const char *	sQuadVertices,
		float	width,
		float	height,
		float	depth,
		float	facing
	)			[static]

create a portal object for portal rendering

Parameters:

	sPortalName,:	it must be a unique name.
	sHomeZone,:	a zone name that this portal connects. this can be "", if a portal is not connected to any zone.
	sTargetZone,:	another zone name that this portal connects. this can be "", if the portal is connected to outer space.
	sQuadVertices,:	it is coordinates of the 4 quad vertices, "x1,y1,z1;x2,y2,z2;x3,y3,z3;x4,y4,z4;" the order of the first three vertices decides the direction of the quad plane. direction of quad plane is only useful when the portal's sTargetZone is empty(outer space), and it should always point from home zone to outer space.
	width,height,depth,facing,:	the bounding size of the portal.

ParaScripting::ParaObject ParaScripting::ParaScene::CreateVoxelMesh	(	const char *	strObjectName,
		const char *	sGridFileName,
		const char *	sTextureFileName
	)			[static]

create a voxel mesh object.

A voxel mesh is a 32*32*32 grid which can be editable at runtime, and rendered using the matching cube algorithm.

Parameters:

	strObjectName,:
	sGridFileName,:	the file name from which to load.This can be "", where an empty one is created.
	sTextureFileName,:	the texture to use, one can later change this by calling SetReplaceableTexture.

bool ParaScripting::ParaScene::CreateSkyBox	(	const char *	strObjectName,
		const char *	strMeshAssetName,
		float	fScaleX,
		float	fScaleY,
		float	fScaleZ,
		float	fHeightOffset
	)			[static]

create a sky box and add it to the current list.

sky box with the same name will not be recreated,but will be selected as the current sky box. It may be a sky box/dome/plane or whatever. The associated mesh will be scaled by the specified amount along x,y,z axis and then translate up or down along the y axis. in many cases, the mesh data in the mesh asset is of unit size.

Parameters:

	strObjectName,:	sky name
	strMeshAssetName,:	mesh asset name. this is not the file name.
	fScaleX,:	the static mesh local transform scale along the x axis
	fScaleY,:	the static mesh local transform scale along the y axis
	fScaleZ,:	the static mesh local transform scale along the z axis
	fHeightOffset,:	the translation along the y axis.

void ParaScripting::ParaScene::DeleteSkyBox

(

const char *

strObjectName

)

[static]

delete a name sky box.

Parameters:

strObjectName,:

if this is "", all sky boxes will be deleted.

ParaObject ParaScripting::ParaScene::CreateFloor	(	const char *	strObjectName,
		const char *	strSpriteAssetName,
		const char *	strTextureAssetName,
		float	fWidth,
		float	fDepth,
		float	fFacing
	)			[static]

Create animated floor: a plane.

Parameters:

	fWidth,:	width of the floor
	fDepth,:	depth(or height) of the floor
	fFacing,:	rotation around the y axis

-- create the "sprite" plane object

-- query asset resources, if none, create it

-- create the object

ParaObject ParaScripting::ParaScene::CreateMeshPhysicsObject	(	const char *	strObjectName,
		const char *	strMeshAssetName,
		float	fOBB_X,
		float	fOBB_Y,
		float	fOBB_Z,
		bool	bApplyPhysics,
		const char *	localMatrix
	)			[static]

Create static triangle mesh based actor for novodex physics engine.

Some notes about meshes:

• Be sure that you define face normals as facing in the direction you intend. Collision detection will only work correctly between shapes approaching the mesh from the ¡°outside¡±, i.e. from the direction in which the face normals point.
• Do not duplicate identical vertices! If you have two triangles sharing a vertex, this vertex should only occur once in the vertex list, and both triangles should index it in the index list. If you create two copies of the vertex, the collision detection code won¡¯t know that it is actually the same vertex, which leads to a decreased performance and unreliable results.
• Also avoid t-joints and non-manifold edges for the same reason. (A t-joint is a vertex of one triangle that is placed right on top of an edge of another triangle, but this second triangle is not split into two triangles at the vertex, as it should. A non-manifold edge is an edge (a pair of vertices) that is referenced by more than two triangles.)

  Parameters:

  strMeshAssetName,:

  the mesh asset name which contains the triangular mesh. when naming mesh file, one can combine "_a"(no physics), "_b"(billboard), "_t"(transparent), "_d"(dim or no lighting), "_r"(receive shadow) in the file name in any order, such as "xxx_b_t_d.x". all such special file endings are listed below

"_a": no physics, it will have no physics, even bApplyPhysics is true. For example. "grass_a.x".

• "_b": billboarded and no physics
• "_r": mesh is shadow receiver
• "_t": mesh contains majorily transparent objects. Please note that this is diferent from alpha testing. Transparency throguh alpha testing is not transparent.
• "_p": mesh is picture or particles. They are rendered with billboarding and Force No Light flag on.
• "_d": mesh is dim and is rendered with force no light on.
• "_v": mesh is rendered with vegetation shader. the static model like palm trees, grasses, bamboos can be animated by this shader.

  Parameters:

  	fOBB_X,:	object bounding box.x
  	fOBB_Y,:	object bounding box.y
  	fOBB_Z,:	object bounding box.z
  	bApplyPhysics,:	whether to turn on the physics of the mesh
  	localMatrix,:	the local transformation matrix of the mesh. It is a string of 4*3 number of float values separated by comma (see below): "mat._11, mat._12, mat._13, mat._21, mat._22, mat._23,mat._31, mat._32, mat._33,mat._41, mat._42, mat._43" If a blank string("") is specified, the local matrix is set to identity matrix.

void ParaScripting::ParaScene::CreateMeshPhysicsObject__	(	ParaObject *	pOut,
		const char *	strObjectName,
		ParaAssetObject &	asset,
		float	fOBB_X,
		float	fOBB_Y,
		float	fOBB_Z,
		bool	bApplyPhysics,
		const char *	localMatrix
	)			[static]

this function shall never be called from the scripting interface.

this is solely for exporting API. and should not be used from the scripting interface.

ParaObject ParaScripting::ParaScene::CreateLightObject	(	const char *	strObjectName,
		float	fPosX,
		float	fPosY,
		float	fPosZ,
		const char *	sLightParams,
		const char *	localMatrix
	)			[static]

Create a new light object.

Parameters:

	strObjectName	Light Object's name
	fPosX	world position X
	fPosY	world position Y
	fPosZ	world position Z
	sLightParams	if this is "" a default light will be created. otherwise it is in the following format. format is "Type Range (r g b a) att0 att1 att2" D3DLIGHTTYPE Type; Type of light source D3DLIGHT_POINT = 1, D3DLIGHT_SPOT = 2, D3DLIGHT_DIRECTIONAL = 3, float Range; Cutoff range D3DCOLORVALUE Diffuse; Diffuse color of light float Attenuation0; Constant attenuation float Attenuation1; Linear attenuation float Attenuation2; Quadratic attenuation e.g. "1 7.0 (1 1 0 1) 0.3 0.1 1" light intensity is calculated as 1/(Attenuation0+d*Attenuation1+d*d*Attenuation2), where d is the distance from the light to object center.

This is used to make light objects persistent.

Parameters:

localMatrix,:

the local transformation matrix of the mesh. It is a string of 4*3 number of float values separated by comma (see below): "mat._11, mat._12, mat._13, mat._21, mat._22, mat._23,mat._31, mat._32, mat._33,mat._41, mat._42, mat._43" If a blank string("") is specified, the local matrix is set to identity matrix.

Returns:

light object is created and returned. One need to attach it to scene.

ParaObject ParaScripting::ParaScene::CreateDynamicPhysicsObject	(	const char *	strObjectName,
		const char *	strMeshAssetName,
		float	fOBB_X,
		float	fOBB_Y,
		float	fOBB_Z,
		bool	bRenderMesh
	)			[static]

Create dynamic physics actor for novodex physics engine.

dynamic objects are considered global object and is loaded to the physics engine immediately currently, only Box and sphere shaped objects are supported.

ParaObject ParaScripting::ParaScene::CreateCharacter	(	const char *	strObjectName,
		const char *	strMultiAnimationAssetName,
		const char *	strScript,
		bool	bIsGlobal,
		float	fRadius,
		float	fFacing,
		float	fScaling
	)			[static]

Create Character.

Parameters:

	strObjectName,:	the name short cut for this object. If the character with the same name exists, it will be renamed to a random name. So that the character is always created.
	strMultiAnimationAssetName,:	the asset name of the base model. It can be nil, in which one must specified it in other means. if the asset file name ends with "_s", it will always be static and local , even IsGlobal is true. For example. "windmill_s.x". Some other special file endings are listed below "_s": force static, solid and local.
	strScript,:	The script file to be loaded when the object is loaded for the first time
	bIsGlobal,:	a global character is not attached to the quad tree terrain, thus can move around the entire scene a non-global character is attached to the quad tree terrain, and is generally considered immobile. although it is OK for non-global character to move only in very small region.
	fRadius,:	radius of the character used in collision detection. if radius is 0, then the object is regarded as passable (not solid).
	fFacing,:	rotation around the y axis
	fScaling,:	typically this should be 1, however, one can scale the mesh and animation to render the character in a different size.

get the model asset.

void ParaScripting::ParaScene::CreateCharacter__	(	ParaObject *	pOut,
		const char *	strObjectName,
		ParaAssetObject &	asset,
		const char *	strScript,
		bool	bIsGlobal,
		float	fRadius,
		float	fFacing,
		float	fScaling
	)			[static]

this function shall never be called from the scripting interface.

this is solely for exporting API. and should not be used from the scripting interface.

void ParaScripting::ParaScene::Play3DSound	(	const char *	strSoundAssetName,
		float	fX,
		float	fY,
		float	fZ
	)			[static]

play a 3D sound at world location (fx, fy, fz).

Currently, the sound is played until it stopped(no looping). And the sound range is internally defined. Please use the ParaUI.PlaySound() to play an ordinary sound or music with or without looping.

void ParaScripting::ParaScene::SetGlobalWater	(	bool	bEnable,
		float	fWaterLevel
	)			[static]

Set the global water drawing attribute.

the global water level is just a water surface at a given height, which is always drawn at current camera location to fill the entire screen. Water surface will be drawn after terrain

Parameters:

	bEnable,:	whether to draw global water
	fWaterLevel,:	water level in meters. Default value is 0.0f;

float ParaScripting::ParaScene::GetGlobalWaterLevel

(

)

[static]

get the current global water level in meters.

This function will return valid value even if the water is disabled.

bool ParaScripting::ParaScene::IsGlobalWaterEnabled

(

)

[static]

return true if global ocean water is enabled.

void ParaScripting::ParaScene::UpdateOcean

(

)

[static]

call this function, when the ocean has changed or the environment has changed.

This will cause the reflection map of the ocean surface to redraw regardless of whether the camera moves or not.

void ParaScripting::ParaScene::AddWaterRipple	(	float	x,
		float	y,
		float	z
	)			[static]

add water ripple to the ocean surface.

Parameters:

	x	position of the ripple
	y	this is usually set to the current water level.

See also:

GetGlobalWaterLevel()

Parameters:

z

position of the ripple

void ParaScripting::ParaScene::Execute

(

const char *

strCmd

)

[static]

execute the scene command string.

Most commands are for debugging purposes. The list of command is given below:

• "show OBB" display every scene object's bounding box
• "hide OBB" hide every scene object's bounding box
• "show report" display the per frame report, such as number of mesh drawn, number of terrain triangles, etc,..
• "hide report" hide the per frame report, such as number of mesh drawn, number of terrain triangles, etc,.. strCmd: the string command passed

ParaObject ParaScripting::ParaScene::MousePick	(	float	fMaxDistance,
		const char *	sFilterFunc
	)			[static]

Pick scene object at the current mouse cursor position.

pick the smallest intersected object which is un-occluded by any objects. Object A is considered occluded by object B only if (1) both A and B intersect with the hit ray. (2) both A and B do not intersect with each other. (3) B is in front of A, with regard to the ray origin.

this function will ray-pick any loaded scene object(biped & mesh, but excluding the terrain) using their oriented bounding box. a filter function may be provided to further filter selected object. this function will transform all objects to near-camera coordinate system. This will remove some floating point inaccuracy near the camera position.Hence this function is most suitable for testing object near the camera eye position. This function does not rely on the physics engine to perform ray-picking. fMaxDistance: the longest distance from the ray origin to check for collision. If the value is 0 or negative, the view culling radius is used as the fMaxDistance.

Parameters:

sFnctFilter,:

it can be any of the following string or a number string "mesh": mesh any mesh object in the scene. Usually for selection during scene editing. "cmesh": mesh object that is clickable (associated with scripts). Usually for game playing. "notplayer": any object in the scene except for the current player. Usually for selection during scene editing. "": any object in the scene except. Usually for selection during scene editing. "light": only pick light objects "biped": any character objects :local or global. "anyobject": any objects, including mesh and characters. but not including helper objects, such as light. "global": all global objects, such as global character and mesh. This is usually for game mode. "point": the returned object is invalid if there no collision with any physics faces. otherwise, one can use GetPosition function of the returned object to retrieve the intersection point. "actionmesh": mesh with action script. number: if it is a number, it is treated as a 32 bitwise DWORD filter code. see SetPickingFilter() for more example.

Returns:

:the scene object. if the object is invalid, it means that the ray has hit nothing.

int ParaScripting::ParaScene::SelectObject	(	int	nGroupIndex,
		float	x,
		float	y,
		float	z,
		float	radius,
		const char *	sFilterFunc
	)			[static]

select select objects within a given region into a given group.

Parameters:

	nGroupIndex,:	which group to select to. One can get the result from ParaSelection. In most cases, select to group 1; since group 0 is reserved for current selection.
	x,y,z,radius,:	a sphere in world space.
	sFnctFilter,:	it can be any of the following string. "mesh": mesh any mesh object in the scene. Usually for selection during scene editing. "cmesh": mesh object that is clickable (associated with scripts). Usually for game playing. "notplayer": any object in the scene except for the current player. Usually for selection during scene editing. "": any object in the scene except. Usually for selection during scene editing. "light": only pick light objects "biped": any character objects :local or global. "anyobject": any objects, including mesh and characters. but not including helper objects, such as light. "global": all global objects, such as global character and mesh. This is usually for game mode.

Returns:

: the total number of selected objects is returned.

void ParaScripting::ParaScene::RegisterEvent	(	const char *	sID,
		const char *	sScript
	)			[static]

register a mouse or key event handler

Parameters:

	sID,:	a string identifier of the event handler. if sID begins with "_m" it is treated as a mouse click event, except that if sID begins with "_mm" it is treated as a mouse move event. if sID begins with "_md" it is treated as a mouse down event. if sID begins with "_mu" it is treated as a mouse up event. if sID begins with "_k" it is treated as a key down event. if sID begins with "_ku" it is treated as a key up event. if sID begins with "_n" it is treated as a network event handler. Note: mouse click is rarely used, since it can be produced in NPL via mouse down move and up. However, lazy NPL programmer can still use it if they do not like to write other mouse handlers in NPL.
	sScript,:	the script to be executed when the event is triggered.This is usually a function call in NPL. sScript should be in the following format "{NPL filename};{sCode};". this is the same format in the UI event handler

void ParaScripting::ParaScene::RegisterEvent1	(	DWORD	nEventType,
		const char *	sID,
		const char *	sScript
	)			[static]

same as above RegisterEvent(), except that it allows caller to explicitly specify the event type, instead of deriving it from the event name.

Parameters:

	nEventType	any bit combination of CEventHandler::EventHandler_type
	sID	any unique string identifier
	sScript	the NPL script.

void ParaScripting::ParaScene::EnableMouseClick

(

bool

bEnable

)

[static]

whether the game engine will automatically generate mouse events for Game Objects.If true, The OnClick callback will be automatically called whenever there is a mouse click.

ParaObject ParaScripting::ParaScene::GetCurrentActor

(

)

[static]

get the actor that is being processed by the AI module or a script call back.

The validity of the pointer is not guaranteed.

void ParaScripting::ParaScene::SetCurrentActor

(

ParaObject

pActor

)

[static]

Set the actor that is being processed by the AI module or a script call back.

The pointer can be NULL.

ParaObject ParaScripting::ParaScene::TogglePlayer

(

)

[static]

It changes the current player to the next player in the scene.

this function is mostly for testing and game purpose. if the object has a reference object, the reference object will become the current object. return : the new current player is returned.

ParaObject ParaScripting::ParaScene::GetObjectByViewBox

(

const object &

viewbox

)

[static]

get an object(usually a static mesh object) by a given view box.

Parameters:

viewbox,:

One can get the view box by calling ParaObject:GetViewBox(). Or one can construct it using a table with the following field:{pos_x, pos_y,pos_z,obb_x,obb_y,obb_z,} pos_x, pos_y,pos_z: is the point at the bottom center of the box. obb_x,obb_y,obb_z: is the size of the box.

Returns:

: return the object with the closest match with the bounding box.

int ParaScripting::ParaScene::GetActionMeshesBySphere	(	const object &	inout,
		float	x,
		float	y,
		float	z,
		float	radius
	)			[static]

get the action meshes within or intersect a sphere.

same as GetObjectsBySphere(..., "actionmesh")

int ParaScripting::ParaScene::GetObjectsBySphere	(	const object &	inout,
		float	x,
		float	y,
		float	z,
		float	radius,
		const char *	sFilterFunc
	)			[static]

Parameters:

inout,:

input and output, it should be an empty table.

Parameters:

	x,:	sphere center x
	y,:	sphere center y
	z,:	sphere center z
	radius,:	sphere radius
	sFnctFilter,:	it can be any of the following string. "mesh": mesh any mesh object in the scene. Usually for selection during scene editing. "cmesh": mesh object that is clickable (associated with scripts). Usually for game playing. "notplayer": any object in the scene except for the current player. Usually for selection during scene editing. "": any object in the scene except. Usually for selection during scene editing. "light": only pick light objects "biped": any character objects :local or global. "anyobject": any objects, including mesh and characters. but not including helper objects, such as light. "actionmesh": mesh with action script. "global": all global objects, such as global character and mesh. This is usually for game mode.

int ParaScripting::ParaScene::GetObjectsByScreenRect	(	const object &	inout,
		int	left,
		int	top,
		int	right,
		int	bottom,
		const char *	sFilterFunc,
		float	fMaxDistance
	)			[static]

Get objects inside or intersect with a screen rect.

screen rect is translated to a 3d cone from the camera eye position to a plane fMaxDistance away. This function is usually used for finding other static mesh objects near a certain character. please note that: objects must be completely inside the near and far planes in order to pass the test.

Parameters:

	output,:	list to get the result
	left,top,right,bottom,:	the rect in screen space coordinates
	sFnctFilter,:	it can be any of the following string. "mesh": mesh any mesh object in the scene. Usually for selection during scene editing. "cmesh": mesh object that is clickable (associated with scripts). Usually for game playing. "notplayer": any object in the scene except for the current player. Usually for selection during scene editing. "": any object in the scene except. Usually for selection during scene editing. "light": only pick light objects "biped": any character objects :local or global. "anyobject": any objects, including mesh and characters. but not including helper objects, such as light. "actionmesh": mesh with action script. "global": all global objects, such as global character and mesh. This is usually for game mode.
	fMaxDistance,:	the world unit distance inside which we will test possible candidates. if negative, it will get all visible ones.

Returns:

: return the number of objects in sphere.

void ParaScripting::ParaScene::OnTerrainChanged	(	float	x,
		float	y,
		float	fRadius
	)			[static]

This function is called manually to update characters in a square region.

So that when the terrain heightfield is changed, the characters within the region will act accordingly, either falling down or snap to terrain surface.

Parameters:

	x,:	center of the terrain region being modified.
	y,:	center of the terrain region being modified.
	fRadius	: radius of the terrain region being modified.

int ParaScripting::ParaScene::SaveAllCharacters

(

)

[static]

save all local characters in the scene to the current NPC database regardless of whether they are modified or not this function is usually called manually in some very rare cases.

In most cases, call SaveLocalCharacters() instead.

Returns:

the number of saved characters are returned.

void ParaScripting::ParaScene::SetTimeOfDay

(

float

time

)

[static]

set time of day in seconds.

Use SetDayLength() to set the total number of minutes in a day.

Parameters:

time,:

time in seconds. This can be any non-negative value. (timeday_length) will be used in case time is longer than a day.

void ParaScripting::ParaScene::SetTimeOfDaySTD

(

float

time

)

[static]

set standard time.

see SetTimeOfDay()

Parameters:

time,:

always in the range [-1,1], 0 means at noon, -1 is morning. 1 is night.

float ParaScripting::ParaScene::GetTimeOfDay

(

)

[static]

get the current time of day in seconds.

float ParaScripting::ParaScene::GetTimeOfDaySTD

(

)

[static]

get standard time.

see GetTimeOfDay()

Returns:

: always in the range [-1,1], 0 means at noon, -1 is morning. 1 is night.

void ParaScripting::ParaScene::SetMaximumAngle

(

float

fMaxAngle

)

[static]

set the maximum sun angle with the Y (up) axis.

float ParaScripting::ParaScene::AdvanceTimeOfDay

(

float

timeDelta

)

[static]

advance time is in seconds, this will also change the light direction, sun color and sun ambient color.

this function is automatically called by the environment simulator

void ParaScripting::ParaScene::SetDayLength

(

float

fMinutes

)

[static]

set how many minutes are there in a day, this is used in time simulation.

default value is 300.

void ParaScripting::ParaScene::SetShadowMethod

(

int

nMethod

)

[static]

the current shadow method:both shadow volume and shadow mapping could be set.

Parameters:

nMethod,:

0: turn off all shadow rendering: this will greatly improve performance 1: turn on shadow using shadow volume 2: turn on shadow mapping 3: turn on both shadow volume and shadow mapping

void ParaScripting::ParaScene::EnableLighting

(

bool

bEnable

)

[static]

Enable both global and local lighting.

Turn off lighting will greatly improve performance, such as on slower computers

void ParaScripting::ParaScene::SetFog	(	bool	bRenderFog,
		const char *	strFogColor,
		float	fFogStart,
		float	fFogEnd,
		float	fFogDensity
	)			[static]

set the global fog effect

Parameters:

	bRenderFog,:	1 to enable fog.
	strFogColor,:	a string of RGB value in the format "%f %f %f", such as "1.0 1.0 1.0", value must be in the range [0, 1.0].
	fFogDensity,:	between (0,1)
	fFogStart,:	unit in meters.
	fFogEnd,:	unit in meters.

Para3DCanvas ParaScripting::ParaScene::Get3DCanvas

(

int

nIndex

)

[static]

get the 3D canvas object at the specified index.

Before getting an 3D canvas, one must first enable it with Enable3DCanvas();

Parameters:

nIndex

index, such as 0,1,2

Returns:

the returned canvas may be invalid.

void ParaScripting::ParaScene::Get3DCanvas__	(	Para3DCanvas *	pCanvas,
		int	nIndex
	)			[static]

this is solely used for API exporting.

void ParaScripting::ParaScene::Enable3DCanvas	(	int	nIndex,
		bool	bEnabled
	)			[static]

enable a canvas at the given index.

It is not advised to use many canvas objects. Typically a game may only have 1 or several canvas.

Parameters:

	nIndex	index, such as 0,1,2, please note that a newly created canvas at index i will by default be bind to selection group i.
	bEnabled	true if enabled.

int ParaScripting::ParaScene::GetTotalCanvasNum

(

)

[static]

get the total number of enabled and/or disabled 3d canvas in the scene.

Returns:

Canvas number

int ParaScripting::ParaScene::DeleteMiniSceneGraph

(

const char *

name

)

[static]

Delete mini scene graphs by name.

if name is "" or "*", all mini scene graphs will be deleted.

Returns:

: the number of graphs deleted is returned.

ParaScripting::ParaMiniSceneGraph ParaScripting::ParaScene::GetPostProcessingScene

(

)

[static]

get the post processing mini scene graph.

Returns:

: this is same as GetMiniSceneGraph("_ps")

void ParaScripting::ParaScene::EnablePostProcessing	(	bool	bEnable,
		const char *	sCallbackScript
	)			[static]

set whether post processing is enabled.

Parameters:

	bEnable,:	bool
	sCallbackScript,:	if bEnabled is true, this is a callback script to be called per frame at which one can process scene after the main 3d scene is rendered. if this is NULL, the old callback script is used.

bool ParaScripting::ParaScene::IsPostProcessingEnabled

(

)

[static]

get whether post processing is enabled.

---