WickedEngine/Documentation/ScriptingAPI-Documentation.md

# Wicked Engine Scripting API Documentation
This is a collection and explanation of scripting features in Wicked Engine.
The documentation completion is still pending....

## Contents
1. Introduction and usage
2. Common Tools
3. Engine manipulation
	1. BackLog (Console)
	2. Renderer
4. Utility Tools
	1. Font
	2. Sprite
		1. ImageEffects
		2. SpriteAnim
		3. MovingTexAnim
		4. DrawRecAnim
	3. Texture
	4. Sound
		1. SoundEffect
		2. Music
	5. Vector
	6. Matrix
	7. Scene
		1. Node
		2. Transform
		3. Cullable
		4. Object
		5. Armature
		6. Ray
		7. AABB
		8. Emitter
		9. Decal
		10. Material
		11. Camera
	8. MainComponent
	9. RenderableComponent
		1. Renderable2DComponent
		2. Renderable3DComponent
			1. ForwardRenderableComponent
			2. DeferredRenderableComponent
		4. LoadingScreenComponent
	10. Network
		1. Server
		2. Client
	11. Input Handling
	12. ResourceManager
		
## Introduction and usage
Scripting in Wicked Engine is powered by Lua, meaning that the user can make use of the 
syntax and features of the widely used Lua language, accompanied by its fast interpreter.
Apart from the common features, certain engine features are also available to use.
You can load lua script files and execute them, or the engine scripting console (also known as the BackLog)
can also be used to execute single line scripts (or you can execute file scripts by the dofile command here).
Upon startup, the engine will try to load a startup script file named startup.lua in the root directory of 
the application. If not found, an error message will be thrown follwed by the normal execution by the program.
In the startup file, you can specify any startup logic, for example loading content or anything.

The setting up and usage of the BackLog is the responsibility of the target application, but the recommended way to set it up
is included in all of the demo projects. It is mapped to te HOME button by default.

## Common Tools
This section describes the common tools for scripting which are not necessarily engine features.
- signal(string name)
- waitSignal(string name)
- runProcess(function func)
- waitSeconds(float seconds)
- getprops(table object)
- len(table object)
- backlog_post_list(table list)
- fixedupdate()
- update()
- render()
- math.lerp(float a,b,t)
- math.clamp(float x,min,max)
- math.saturate(float x)
- math.round(float x)

## Engine manipulation
The scripting API provides functions for the developer to manipulate engine behaviour or query it for information.

### BackLog
The scripting console of the engine. Input text with the keyboard, run the input with the RETURN key. The script errors
are also displayed here.
The scripting API provides some functions which manipulate the BackLog. These functions are in he global scope:
- backlog_clear()
- backlog_post(string params,,,)
- backlog_fontsize(int size)
- backlog_isactive() : boolean result
- backlog_fontrowspacing(int spacing)

### Renderer
This is the graphics renderer, which is also responsible for managing the scene graph which consists of keeping track of
parent-child relationships between the scene hierarchy, updating the world, animating armatures.
You can use the Renderer with the following functions, all of which are in the global scope:
- GetTransforms() : string result
- GetTransform(String name) : Transform? result
- GetArmatures() : string result
- GetArmature(String name) : Armature? result
- GetObjects() : string result
- GetObject(String name) : Object? result
- GetEmitters() : string result
- GetEmitter(string name) : Emitter? result1,result2,...
- GetMeshes() : string result
- GetLights() : string result
- GetMaterials() : string result
- GetGameSpeed() : float result
- SetResolutionScale(float scale)
- SetGamma(float gamma)
- SetGameSpeed(float speed)
- GetScreenWidth() : float result
- GetScreenHeight() : float result
- GetRenderWidth() : float result
- GetRenderHeight(): float result
- GetCamera() : Camera? result
- LoadModel(string directory, string name, opt string identifier, opt Matrix transform) : Model? result
- LoadWorldInfo(string directory, string name)
- FinishLoading()
- SetEnvironmentMap(Texture cubemap)
- SetColorGrading(Texture texture2D)
- HairParticleSettings(opt int lod0, opt int lod1, opt int lod2)
- SetShadowProps2D(int resolution, int count, int softShadowQuality)
- SetShadowPropsCube(int resolution, int count)
- SetDebugPartitionTreeEnabled(bool enabled)
- SetDebugBonesEnabled(bool enabled)
- SetDebugEittersEnabled(bool enabled)
- SetDebugForceFieldsEnabled(bool enabled)
- SetVSyncEnabled(opt bool enabled)
- SetOcclusionCullingEnabled(bool enabled)
- SetPhysicsParams(opt bool rigidBodyPhysicsEnabled, opt bool softBodyPhysicsEnabled, opt int softBodyIterationCount)
- Pick(Ray ray, opt PICKTYPE pickType, opt string id="", opt string disableID="") : Object? object, Vector position,normal, float distance
- DrawLine(Vector origin,end, opt Vector color)
- PutWaterRipple(String imagename, Vector position)
- PutDecal(Decal decal)
- PutEnvProbe(Vector pos, opt int resolution = 256)
- ClearWorld()
- ReloadShaders(opt string path)

## Utility Tools
The scripting API provides certain engine features to be used in development.
- Tip: You can inspect any object's functionality by calling 
getprops(YourObject) on them (where YourObject is the object which is to be inspected). The result will be displayed on the BackLog.

- Tags:
	- [constructor]				: The method is a constructor for the same type of object.
	- [void-constructor]		: The method is a constructor for the same type of object, but the object it creates is empty, so cannot be used.
	- [outer]					: The method or value is in the global scope, so not a method of any objects.

### Font
Gives you the ability to render text with a custom font.
- [constructor]Font(opt string text)
- SetStyle(string fontstyle)
- SetText(opt string text)
- SetSize(int size)
- SetPos(Vector pos)
- SetSpacing(Vector spacing)
- SetAlign(WIFALIGN Halign, opt WIFALIGN Valign)
	- [outer]WIFALIGN_LEFT : int
	- [outer]WIFALIGN_CENTER : int
	- [outer]WIFALIGN_MID : int
	- [outer]WIFALIGN_RIGHT : int
	- [outer]WIFALIGN_TOP : int
	- [outer]WIFALIGN_BOTTOM : int
- GetText() : string result
- GetSize() : int result
- GetPos() : Vector result
- GetSpacing() : Vector result
- GetAlign() : WIFALIGN halign,valign
- Destroy()

### Sprite
Render images on the screen.
- [constructor]Sprite(opt string texture, opt string maskTexture, opt string normalMapTexture)
- SetEffects(ImageEffects effects)
- GetEffects() : ImageEffects result
- SetAnim(SpriteAnim anim)
- GetAnim() : SpriteAnim result
- Destroy()

#### ImageEffects
Specify Sprite properties, like position, size, etc.
- [constructor]ImageEffects(opt float width, opt float height)
- [constructor]ImageEffects(float posX, float posY, float width, opt float height)
- GetPos() : Vector result
- GetSize() : Vector result
- GetOpacity() : float result
- GetFade() : float result
- GetRotation() : float result
- GetMipLevel() : float result
- SetPos(Vector pos)
- SetSize(Vector size)
- SetOpacity(float opacity)
- SetFade(float fade)
- SetRotation(float rotation)
- SetMipLevel(float mipLevel)

#### SpriteAnim
Animate Sprites easily with this helper.
- [constructor]SpriteAnim()
- SetRot(float val)
- SetRotation(float val)
- SetOpacity(float val)
- SetFade(float val)
- SetRepeatable(boolean val)
- SetVelocity(Vector val)
- SetScaleX(float val)
- SetScaleY(float val)
- SetMovingTexAnim(MovingTexAnim val)
- SetDrawRecAnim(DrawRecAnim val)
- GetRot() : float result
- GetRotation() : float result
- GetOpacity() : float result
- GetFade() : float result
- GetRepeatable() : boolean result
- GetVelocity() : Vector result
- GetScaleX() : float result
- GetScaleY() : float result
- GetMovingTexAnim() : GetMovingTexAnim result
- GetDrawRecAnim() : GetDrawRecAnim result

#### MovingTexAnim
Move texture continuously along the sprite.
- [constructor]MovingTexAnim(opt float speedX,speedY)
- SetSpeedX(float val)
- SetSpeedY(float val)
- GetSpeedX() : float result
- GetSpeedY() : float result

#### DrawRecAnim
Animate sprite frame by frame.
- [constructor]DrawRecAnim()
- SetOnFrameChangeWait(float val)
- SetFrameCount(float val)
- SetJumpX(float val)
- SetJumpY(float val)
- SetSizX(float val)
- SetSizY(float val)
- GetOnFrameChangeWait() : float result
- GetFrameCount() : float result
- GetJumpX() : float result
- GetJumpY() : float result
- GetSizX() : float result
- GetSizY() : float result

### Texture
Just holds texture information in VRAM.
- [void-constructor]Texture()

### Sound
Load a Sound file, either sound effect or music.
- [outer]SoundVolume(opt float volume)
- [outer]MusicVolume(opt float volume)
- [void-constructor]Sound()
- Play(opt int delay)
- Stop()

#### SoundEffect
Sound Effects are for playing a sound file once. Inherits the methods from Sound.
- [constructor]SoundEffect(string soundFile)

#### Music
Music is for playing sound files in the background, along with sound effects. Inherits the methods from Sound.
- [constructor]Music(string soundFile)

### Vector
A four component floating point vector. Provides efficient calculations with SIMD support.
- [outer]vector
- [constructor]Vector(opt float x, opt float y, opt float z, opt float w)
- GetX() : float result
- GetY() : float result
- GetZ() : float result
- GetW() : float result
- SetX(float value)
- SetY(float value)
- SetZ(float value)
- SetW(float value)
- Transform(Matrix matrix)
- Length() : float result
- Normalize() : Vector result
- QuaternionNormalize() : Vector result
- Add(Vector v1,v2) : Vector result
- Subtract(Vector v1,v2) : Vector result
- Multiply(Vector v1,v2) : Vector result
- Dot(Vector v1,v2) : Vector result
- Cross(Vector v1,v2) : Vector result
- Lerp(Vector v1,v2, float t) : Vector result
- QuaternionMultiply(Vector v1,v2) : Vector result
- QuaternionFromRollPitchYaw(Vector rotXYZ) : Vector result
- QuaternionSlerp(Vector v1,v2, float t) : Vector result

### Matrix
A four by four matrix, efficient calculations with SIMD support.
- [outer]matrix
- [constructor]Matrix(opt float m00,m01,m02,m03,m10,m11,m12,m13,m20,m21,m22,m23,m30,m31,m32,m33)
- Translation(opt Vector vector) : Matrix result
- Rotation(opt Vector rollPitchYaw) : Matrix result
- RotationX(opt float angleInRadians) : Matrix result
- RotationY(opt float angleInRadians) : Matrix result
- RotationZ(opt float angleInRadians) : Matrix result
- RotationQuaternion(opt Vector quaternion) : Matrix result
- Scale(opt Vector scaleXYZ) : Matrix result
- LookTo(Vector eye,direction, opt Vector up) : Matrix result
- LookAt(Vector eye,focusPos, opt Vector up) : Matrix result
- Multiply(Matrix m1,m2) : Matrix result
- Add(Matrix m1,m2) : Matrix result
- Transpose(Matrix m) : Matrix result
- Inverse(Matrix m) : Matrix result, float determinant

### Scene
Manipulate the 3D scene with these objects. 

#### Node
The basic entity in the scene. It has a name.
- [constructor]Node()
- GetName() : string
- SetName(string name)

#### Transform
Everything in the scene is a transform. It defines a point in the space by location, size, and rotation.
It provides several key features of parenting. 
It inherits functions from Node.
- [constructor]Transform()
- AttachTo(Transform parent, opt boolean translation,rotation,scale)
- Detach()
- Scale(Vector vector)
- Rotate(Vector vectorRollPitchYaw)
- Translate(Vector vector)
- MatrixTransform(Matrix matrix)
- GetMatrix() : Matrix result
- ClearTransform()
- SetTransform(Transform t)
- GetPosition() : Vector result
- GetRotation() : Vector resultQuaternion
- GetScale() : Vector resultXYZ

#### Cullable
Can be tested againt the view frustum, AABBs, rays, space partitioning trees. 
It inherits functions from Transform.
- [constructor]Cullable()
- Intersects(Cullable cullable) : boolean result
- Intersects(Ray cullable) : boolean result
- Intersects(Vector cullable) : boolean result
- GetAABB() : AABB result
- SetAABB(AABB aabb)

#### Object
It is a renderable entity (optionally), which contains a Mesh.
It inherits functions from Cullable.
- [void-constructor]Object()
- EmitTrail(Vector color, opt float fadeSpeed=0.06)
- SetTrailTex(Texture tex)
- SetTrailDistortTex(Texture tex)
- SetTransparency(float value)
- GetTransparency() : float? result
- SetColor(Vector rgb)
- GetColor() : Vector? rgb
- IsValid() : boolean result

#### Armature
It animates meshes.
It inherits functions from Transform.
- [void-constructor]Armature()
- GetAction(opt string animLayer = "") : string? result
- GetActions() : string? result
- GetBones() : string? result
- GetBone(string name) : Transform? result
- GetFrame(opt string animLayer = "") : float? result
- GetFrameCount(opt string animLayer = "") : float? result
- IsValid() : boolean result
- ChangeAction(opt string name = "", opt float blendFrames = 0, opt string animLayer = "", opt float weight = 1.0)
- StopAction(opt string animLayer = "")
- PauseAction(opt string animLayer = "")
- PlayAction(opt string animLayer = "")
- ResetAction(opt string animLayer = "")
- AddAnimLayer(string animLayer)
- DeleteAnimLayer(string animLayer)
- SetAnimLayerWeight(float weight, opt string animLayer="")
- SetAnimLayerLooped(float weight, opt string animLayer="")

#### Ray
Can intersect with AABBs, Cullables.
- [constructor]Ray(opt Vector origin, direction)
- GetOrigin() : Vector result
- GetDirection() : Vector result

#### AABB
Axis Aligned Bounding Box. Can be intersected with any shape, or ray.
- [constructor]AABB(opt Vector min,max)
- Intersects(AABB aabb)
- Transform(Matrix mat)
- GetMin() : Vector result
- GetMax() : Vector result

#### Emitter
Emitter particlesystem.
- [void-constructor]Emitter()
- GetName() : string? name
- SetName(string name)
- GetMotionBlur() : float? amount
- SetMotionBlur(float amount)
- Burst(float amount)
- IsValid() : bool value

#### Decal
Decal is a texture sticker placeable onto any surface. It is a Transform and a Cullable.
- [constructor]Decal(opt Vector tra=Vector(0,0,0), sca=Vector(1,1,1), rotQuaternion=Vector(0,0,0,1), opt string tex="", nor="")
- SetTexture(string tex)
- SetNormal(string tex)
- SetLife(float life)
- GetLife() : float result
- SetFadeStart(float start)
- GetFadeStart() : float result

#### Material
- [constructor]Material(opt string name="")
- GetName() : string name
- SetName(string value)

#### Camera
Main camera looking at the scene. It is a Transform.
- [constructor]Camera()
- SetFarPlane(float val)
- SetNearPlane(float val)
- GetFarPlane() : float result
- GetNearPlane() : float result

#### Model
Collection of Objects, Armatures, Lights, Decals. Also a transform by itself
- [constructor]Model()

### MainComponent
The main component which holds information and manages the running of the current program.
- [outer]main : MainComponent
- [void-constructor]MainComponent()
- GetContent() : Resource? result
- GetActiveComponent() : RenderableComponent? result
- SetActiveComponent(RenderableComponent component, opt int fadeFrames,fadeColorR,fadeColorG,fadeColorB)
- SetFrameSkip(bool enabled)
- SetInfoDisplay(bool active)
- SetWatermarkDisplay(bool active)
- SetFPSDisplay(bool active)
- SetCPUDisplay(bool active)
- SetColorGradePaletteDisplay(bool active)
- [outer]SetProfilerEnabled(bool enabled)

### RenderableComponent
A RenderableComponent describes a scene wich can render itself.
- [constructor]RenderableComponent()
- GetContent() : Resource result
- Initialize()
- Load()
- Unload()
- Start()
- Stop()
- FixedUpdate()
- Update(opt float dt = 0)
- Render()
- Compose()
- OnStart(string task)
- OnStop(string task)

#### Renderable2DComponent
It can hold Sprites and Fonts and can sort them by layers, update and render them.
- [constructor]Renderable2DComponent()
- AddSprite(Sprite sprite, opt string layer)
- AddFont(Font font, opt string layer)
- RemoveFont(Font font)
- ClearSprites()
- ClearFonts()
- GetSpriteOrder(Sprite sprite) : int? result
- GetFontOrder(Font font) : int? result
- AddLayer(string name)
- GetLayers() : string? result
- SetLayerOrder(string name, int order)
- SetSpriteOrder(Sprite sprite, int order)
- SetFontOrder(Font font, int order)

#### Renderable3DComponent
A 3D scene can either be rendered by a Forward or Deferred render path. 
It inherits functions from Renderable2DComponent, so it can render a 2D overlay.
- [void-constructor]Renderable3DComponent()
- SetSSAOEnabled(bool value)
- SetSSREnabled(bool value)
- SetShadowsEnabled(bool value)
- SetReflectionsEnabled(bool value)
- SetFXAAEnabled(bool value)
- SetBloomEnabled(bool value)
- SetColorGradingEnabled(bool value)
- SetEmitterParticlesEnabled(bool value)
- SetHairParticlesEnabled(bool value)
- SetHairParticlesReflectionEnabled(bool value)
- SetVolumeLightsEnabled(bool value)
- SetLightShaftsEnabled(bool value)
- SetLensFlareEnabled(bool value)
- SetMotionBlurEnabled(bool value)
- SetSSSEnabled(bool value)
- SetDepthOfFieldEnabled(bool value)
- SetDepthOfFieldFocus(float value)
- SetDepthOfFieldStrength(float value)
- SetPreferredThreadingCount(int value)
- SetTessellationEnabled(bool value)
- SetMSAASampleCount(int count)
- SetHairParticleAlphaCompositionEnabled(bool value)
- SetStereogramEnabled(bool value)
- SetSharpenFilterEnabled(bool value)
- SetSharpenFilterAmount(bool value)

##### ForwardRenderableComponent
It renders the scene contained by the Renderer in a forward render path. The component does not hold the scene information, 
only the effects to render the scene. The scene is managed and ultimately rendered by the Renderer.
It inherits functions from Renderable3DComponent.
- [constructor]ForwardRenderableComponent()

##### TiledForwardRenderableComponent
It renders the scene contained by the Renderer in a tiled forward render path. The component does not hold the scene information, 
only the effects to render the scene. The scene is managed and ultimately rendered by the Renderer.
It inherits functions from ForwardRenderable3DComponent.
- [constructor]TiledForwardRenderableComponent()

##### DeferredRenderableComponent
It renders the scene contained by the Renderer in a deferred render path. The component does not hold the scene information, 
only the effects to render the scene. The scene is managed and ultimately rendered by the Renderer.
It inherits functions from Renderable3DComponent.
- [constructor]DeferredRenderableComponent()

#### LoadingScreenComponent
It is a Renderable2DComponent but one that internally manages resource loading and can display information about the process.
It inherits functions from Renderable2DComponent.
- [constructor]LoadingScreenComponent()
- AddLoadingTask(string taskScript)
- OnFinished(string taskScript)

### Network
Here are the network communication features.
- TODO

#### Server
A TCP host to which clients can connect and communicate with each other or the server.
- TODO

#### Client
A TCP client which provides features to communicate with other clients over the internet or local area network connection.
- TODO

### Input Handling
These provide functions to check the state of the input devices.

#### InputManager
Query input devices
- [outer]input : InputManager
- [void-constructor]InputManager()
- Down(int code, opt int type = KEYBOARD)
- Press(int code, opt int type = KEYBOARD)
- Hold(int code, opt int duration = 30, opt boolean continuous = false, opt int type = KEYBOARD)
- GetPointer() : Vector result
- SetPointer(Vector pos)
- HidePointer(bool visible)
- GetTouches() : Touch result[]

#### Touch
Describes a touch contact point
- [constructor]Touch()
- GetState() : TOUCHSTATE result
- GetPos() : Vector result

#### TOUCHSTATE
- [outer]TOUCHSTATE_PRESSED : int
- [outer]TOUCHSTATE_RELEASED : int
- [outer]TOUCHSTATE_MOVED : int

#### Input types
- [outer]DIRECTINPUT_JOYPAD : int
- [outer]XINPUT_JOYPAD : int
- [outer]KEYBOARD : int

#### Keyboard Key codes
- [outer]VK_UP : int
- [outer]VK_DOWN : int
- [outer]VK_LEFT : int
- [outer]VK_RIGHT : int
- [outer]VK_SPACE : int
- [outer]VK_RETURN : int
- [outer]VK_RSHIFT : int
- [outer]VK_LSHIFT : int
- [outer]VK_F1 : int
- [outer]VK_F2 : int
- [outer]VK_F3 : int
- [outer]VK_F4 : int
- [outer]VK_F5 : int
- [outer]VK_F6 : int
- [outer]VK_F7 : int
- [outer]VK_F8 : int
- [outer]VK_F9 : int
- [outer]VK_F10 : int
- [outer]VK_F11 : int
- [outer]VK_F12 : int
- You can also generate a key code by calling string.byte(char uppercaseLetter) where the parameter represents the desired key of the keyboard

#### Mouse Key Codes
- [outer]VK_LBUTTON : int
- [outer]VK_MBUTTON : int
- [outer]VK_RBUTTON : int

### ResourceManager
Stores and manages resources such as textures, sounds and shaders.
- [outer]globalResources : Resource
- [void-constructor]Resource()
- Get(string name)
- Add(string name)
- Del(string name)
- List() : string result