Forest2D/Manual.adoc

Forest2D user manual
====================

Forest2D is a 2d tile-based cross platform game engine
written primarily in Lua using the Lua-SDL2 binding.
It is intended for simple 2d tile-based games providing
graphics, audio, collision detection, sprites,
tilemaps, gui, animation and more.

Global variables.
~~~~~~~~~~~~~~~~~

[source,lua]
----
Forest2D.WINDOW_WIDTH -- default value 640
Forest2D.WINDOW_HEIGHT -- default value 480

Forest2D.TextureList -- default value {}

----

Functions.
~~~~~~~~~~

[source,lua]
----
Forest2D:Init()
----

Used to initialize engine.

Arguments
~~~~~~~~~
None.

Returns
~~~~~~~
*true* on success, *nil* on failure.

[source,lua]
----
Forest2D.TextureList:Load(Renderer, Directory)
----

Used to load textures from a given directory into the Forest2D.TextureList table

Arguments
~~~~~~~~~
- *Renderer* an SDL https://github.com/Tangent128/luasdl2/wiki/Sdl-RendererObject[Renderer] object.
- *Directory* the path of the desired directory repersented as a string

Returns
~~~~~~~
*nil*.

[source,lua]
----
Forest2D.TextureList:Push(Texture)
----

Used to push a texture onto the Forest2D.TextureList table

Arguments
~~~~~~~~~
*Texture* an SDL2 Texture

Returns
~~~~~~~
*nil*.

[source,lua]
----
Forest2D.TextureList:Pop()
----

Used to pop a texture off the Forest2D.TextureList table

Arguments
~~~~~~~~~
None.

Returns
~~~~~~~
*nil*.

[source,lua]
----
Forest2D:CreateSDLWindow(Title, Icon)
----

You must set the variables Forest2D.WINDOW_WIDTH and Forest2D.WINDOW_HEIGHT before calling this function otherwise the default values of 640x480 will be used.

Arguments
~~~~~~~~~
- *Title* the window title
- *Icon* the location of a .bmp file used for the window icon

Returns
~~~~~~~
An SDL https://github.com/Tangent128/luasdl2/wiki/Sdl-WindowObject[Window] object or *nil*

[source,lua]
----
Forest2D:CreateSDLRenderer(window)
----
Arguments
~~~~~~~~~
- *window* an SDL window

Returns
~~~~~~~
An SDL https://github.com/Tangent128/luasdl2/wiki/Sdl-RendererObject[Renderer] object or *nil*

[source,lua]
----
Forest2D:Quit()
----

Quits Forest2D.

Arguments
~~~~~~~~~
None.

Returns
~~~~~~~
*nil*.

[source,lua]
----
Forest2D.EventHandler.New(Delay)
----

Arguments
~~~~~~~~~
- *Delay* the delay in ms between checking for events.

Returns
~~~~~~~
A Forest2D *EventHandler* object.

[source,lua]
----
EventHandler.DisableEvent(EventID, Time)
----

Arguments
~~~~~~~~~
- *EventID* the event to be disabled.
- *Time* the time in ms for the event to be disabled.

Returns
~~~~~~~
*nil*.

[source,lua]
----
EventHandler.Reset()
----

Resets the status of all events.

Arguments
~~~~~~~~~
None.

Returns
~~~~~~~
*nil*.

[source,lua]
----
GetCurrentMouseTile(Ycord, Xcord, Camera)
----

Takes the mouse coordinates and translates them into tile coordinates.

Arguments
~~~~~~~~~
- *Ycord* the y mouse position
- *Xcord* the x mouse position
- *CameraY* the Y position of the camera
- *CameraX* the X position of the camera

Returns
~~~~~~~
A table containing the mouse tile coordinates like so {MTileY, MTileX}.

[source,lua]
----
Forest2D.Audio.New(Audiofile, Channel, SampleRate, NumberOfChannels)
----

Arguments
~~~~~~~~~
- *Audiofile* the file of which to play.
- *Channel* the channel of which to play.
- *SampleRate* the sample rate.
- *NumberOfChannels* the number of audio channels to open.

Returns
~~~~~~~
A Forest2D *Audio* object.

[source,lua]
----
Audio:Play()
----
Plays the *Audio* object if the channel is free.

Arguments
~~~~~~~~~
None.

Returns
~~~~~~~
*nil*.

[source,lua]
----
Forest2D.TileAnimation.New(Renderer, AnimationFile)
----
Creates a new Forest2D *TileAnimation* object.

Arguments
~~~~~~~~~
- *Renderer* an SDL https://github.com/Tangent128/luasdl2/wiki/Sdl-RendererObject[Renderer] object.
- *TileAnimationFile* can be the location of a tile animation file or an SDL https://github.com/Tangent128/luasdl2/wiki/Sdl-TextureObject[Texture] object.

Returns
~~~~~~~
A Forest2D *TileAnimation* object.

[source,lua]
----
TileAnimation.Play(Renderer, DestRect, Speed, RunAsLoop, Camera)
----
Plays the tile animation.

Arguments
~~~~~~~~~
- *Renderer* an SDL https://github.com/Tangent128/luasdl2/wiki/Sdl-RendererObject[Renderer] object.
- *DestRect* an SDL https://github.com/Tangent128/luasdl2/wiki/Sdl-Rect[Rect] object.
- *Speed* the time in ms it takes to increment a frame.
- *RunAsLoop* a boolean value self explanatory.

Returns
~~~~~~~
*nil*.

[source,lua]
----
TileAnimation.PlayTile(Renderer, x, y, Speed, RunAsLoop, Camera)
----
Plays the tile animation at a specific tile.
A Forest2D *World* object must exist for this function to be used

Arguments
~~~~~~~~~
- *Renderer* an SDL https://github.com/Tangent128/luasdl2/wiki/Sdl-RendererObject[Renderer] object.
- *x* the x tile coordinate on the tilemap
- *y* the y tile coordinate on the tilemap
- *Speed* the time in ms it takes to increment a frame.
- *RunAsLoop* a boolean value self explanatory.
- *Camera* an optional Forest2D camera object used if the frame needs to be rendered relative to the camera

Returns
~~~~~~~
*nil*.

[source,lua]
----
TileAnimation.PlayFrame(Renderer, DestRect, Frame, Camera)
----
Plays a specific frame of the TileAnimation object.

Arguments
~~~~~~~~~
- *Renderer* an SDL https://github.com/Tangent128/luasdl2/wiki/Sdl-RendererObject[Renderer] object.
- *DestRect* an SDL https://github.com/Tangent128/luasdl2/wiki/Sdl-Rect[Rect] object.
- *Frame* the frame of which to display.
- *Camera* an optional Forest2D camera object used if the frame needs to be rendered relative to the camera.

Returns
~~~~~~~
*nil*.

[source,lua]
----
Forest2D.World.TileAnimationset.New(Renderer, TileAnimationsetFile, TileAnimationsetCfgFile)
----
Creates a new Forest2D *TileAnimationset* object.

Arguments
~~~~~~~~~
- *Renderer* an SDL https://github.com/Tangent128/luasdl2/wiki/Sdl-RendererObject[Renderer] object.
- *TileAnimationsetFile* the location of the TileAnimationset file.
- *TileAnimationsetCfgFile* the location of the TileAnimationset configuration file.

Returns
~~~~~~~
A Forest2D *TileAnimationset* object.

[source,lua]
----
Forest2D.World.Tileset.New(Renderer, TilesetFile)
----
Creates a new Forest2D *Tileset* object.

Arguments
~~~~~~~~~
- *Renderer* an SDL https://github.com/Tangent128/luasdl2/wiki/Sdl-RendererObject[Renderer] object.
- *TilesetFile* the location of the Tileset file.

Returns
~~~~~~~
A Forest2D *Tileset* object.

[source,lua]
----
Forest2D.World.New(Renderer, Tileset, TileAnimationset, TileSize, SizeW, SizeZ, SizeY, SizeX)
----
Creates a new Forest2D *World* object. +
Note that *World* is a special object, only one *World* object should exist at once and the *World* must be freed when done with.

Arguments
~~~~~~~~~
- *Renderer* an SDL https://github.com/Tangent128/luasdl2/wiki/Sdl-RendererObject[Renderer] object.
- *Tileset* a *Tileset* object that will contain all tiles to be used on the tilemap.
- *TileAnimationset* a *TileAnimationset* object that will contain all animations to be used on the tilemap.
- *TileSize* the tile size.
- *SizeW* the maximum w coordinate (the 4th dimension).
- *SizeZ* the maximum z coordinate.
- *SizeY* the maximum y coordinate.
- *SizeX* the maximum x coordinate.

Returns
~~~~~~~
A Forest2D *World* object.

[source,lua]
----
World:Free()
----
Free's the *World* from memory.

Arguments
~~~~~~~~~
None.

Returns
~~~~~~~
*nil*.

[source,lua]
----
World.SpriteList.Push(Sprite)
----
Push an item onto the SpriteList.

Arguments
~~~~~~~~~
Sprite a Forest2D *Sprite* object.

Returns
~~~~~~~
*nil*.

[source,lua]
----
World.SpriteList.Pop()
----
Pop an item from the SpriteList.

Arguments
~~~~~~~~~
None.

Returns
~~~~~~~
*nil*.

[source,lua]
----
World:Load(Worldfile, SpriteListFile)
----
Loads a .world and SpriteList file.

Arguments
~~~~~~~~~
- *Worldfile* the location of the .world file.
- *SpriteListFile* the location of the SpriteList file.

Returns
~~~~~~~
*nil*.

[source,lua]
----
World:Save(Worldfile, SpriteListFile)
----
Saves a .world and SpriteList file.

Arguments
~~~~~~~~~
- *Worldfile* the location of the .world file.
- *SpriteListFile* the location of the SpriteList file.

Returns
~~~~~~~
*nil*.

[source,lua]
----
World:Render(Z)
----
Renders a layer of the *World*

Arguments
~~~~~~~~~
- *Z* the layer of which to render

Returns
~~~~~~~
*nil*.

[source,lua]
----
World:GetTile(W, Z, Y, X, Member)
----

Arguments
~~~~~~~~~
- *Z* the z coordinate.
- *Y* the y coordinate.
- *X* the x coordinate.
- *W* the W coordinate the 4th dimension.
- *Member* the member to access at the given coordinates.

Returns
~~~~~~~
The value of the Member at the given coordinates.

[source,lua]
----
World:SetTile(W, Z, Y, X, Value, Member)
----

Arguments
~~~~~~~~~
- *Z* the z coordinate.
- *Y* the y coordinate.
- *X* the x coordinate.
- *W* the W coordinate the 4th dimension.
- *Value* the value to set.
- *Member* the member to set the value of.

Returns
~~~~~~~
*nil*.

[source,lua]
----
Sprite.New(Y, X, W, H, TextureID, AnimationTable)
----
Creates a new *Sprite* object

Arguments
~~~~~~~~~
- *Y* the y coordinate.
- *X* the x coordinate.
- *W* the sprites width
- *H* the sprites height
- *TextureID* the index used to determine the sprites texture from the Forest2D.TextureList table.
- *AnimationTable* an optional table parameter specifying how the sprite will be animated +
   and with which textures from the Forest2D.TextureList table using the attributes: +
   AnimationTable.LoopStatus, AnimationTable.Speed, AnimationTable.Indicies, +
   example: AnimationTable.LoopStatus = false, AnimationTable.Speed = 500, +
   AnimationTable.Indicies = {4, 5, 6, 7, 8} the Indicies table is used to specificy the textures +
   in Forest2D.TextureList to be used in the animation in the given order.

Returns
~~~~~~~
A *Sprite* object.

[source,lua]
----
GUI.NewWindow(Renderer, Rect, ColorRGB, Alpha, TitleBar)
----

Arguments
~~~~~~~~~
- *Renderer* an SDL https://github.com/Tangent128/luasdl2/wiki/Sdl-RendererObject[Renderer] object.
- *Rect* an SDL https://github.com/Tangent128/luasdl2/wiki/Sdl-Rect[Rect] object to set the width, height, x position and y position of the window.
- *ColorRGB* a hexadecimal number between 0x000000 and 0xFFFFFF to set the color of the window.
- *Alpha* a number between 0 and 255 to set the transparency of the window.
- *TitleBar* a table that is defined like so:

[source,lua]
local TitleBar = {color = 0xAA55FF, alpha = 210, text = "MyWindow", textcolor = 0xFFFFFF, selectable = true, uncloseable = false}

Returns
~~~~~~~
A Forest2D *Window* object.

[source,lua]
----
GUI.NewLabel(Window, Renderer, Rect, TTFfile, FontRes, Text, ColorRGB)
----

Arguments
~~~~~~~~~
- *Window* a Forest2D *Window* object (optional)
- *Renderer* an SDL https://github.com/Tangent128/luasdl2/wiki/Sdl-RendererObject[Renderer] object.
- *Rect* an SDL https://github.com/Tangent128/luasdl2/wiki/Sdl-Rect[Rect] object to set the width, height, x position and y position of the *Label* inside of the window.
- *TTFfile* an optional custom True Type Font file to be applied to the *Label*.
- *FontRest* the font resolution.
- *Text* the string of text for the label to contain.
- *TextColor* a hexadecimal number between 0x000000 and 0xFFFFFF to set the color of the *Label*.

Returns
~~~~~~~
A Forest2D *Label* object.

[source,lua]
----
GUI.NewButton(Window, Renderer, Rect, Text, TextColor, BackgroundColor)
----

Arguments
~~~~~~~~~
- *Window* a Forest2D *Window* object (optional)
- *Renderer* an SDL https://github.com/Tangent128/luasdl2/wiki/Sdl-RendererObject[Renderer] object.
- *Rect* an SDL https://github.com/Tangent128/luasdl2/wiki/Sdl-Rect[Rect] object to set the width, height, x position and y position of the *Button* inside of the window.
- *Text* the string of text for the button to contain.
- *TextColor* a hexadecimal number between 0x000000 and 0xFFFFFF to set the color of the *Button*.
- *BackgroundColor* a hexadecimal number between 0x000000 and 0xFFFFFF to set the background color of the *Button*.

Returns
~~~~~~~
A Forest2D *Button* object.


[source,lua]
----
GUI.NewMenu(Renderer, Buttons, Rect, Title, Txtcolor, BGcolor, BGalpha)
----

Arguments
~~~~~~~~~
- *Renderer* an SDL https://github.com/Tangent128/luasdl2/wiki/Sdl-RendererObject[Renderer] object.
- *Buttons* a table containing 1 or more Forest2D *Buttons* which can be declaired using this format +
[source,lua]
----
local Item1 = Forest2D.GUI.NewButton(nil, Renderer, nil, "item1", 0x000000, 0xFFFFFF)
----
- *Rect* an SDL https://github.com/Tangent128/luasdl2/wiki/Sdl-Rect[Rect] object
- *Title* a string to be the title of the menu
- *TxtColor* a hexadecimal number between 0x000000 and 0xFFFFFF to be the text color
- *BGcolor* a hexadecimal number between 0x000000 and 0xFFFFFF to be the background color
- BGalpha a number between 0 and 255 to set the transparency of the background

[source,lua]
----
Window:Add(Object)
----
Adds a GUI object to a *Window*.

Arguments
~~~~~~~~~
- *Object* the GUI object to add to the window.

Returns
~~~~~~~
*nil*.

[source,lua]
----
Window:Render(EventHandler)
----
Displays the *Window* and all objects contained in said *Window*.

Arguments
~~~~~~~~~
A Forest2D EventHandler object (needed to keep track of mouse input)

Returns
~~~~~~~
*nil*.

[source,lua]
----
Window:Move(x,y)
----
Moves the *Window*.

Arguments
~~~~~~~~~
- *x* the change to apply to the x coordinate
- *y* the change to apply to the y coordinate

Returns
~~~~~~~
*nil*.

[source,lua]
----
Window:Scale(w,h)
----
Scales the *Window* and its objects.

Arguments
~~~~~~~~~
- *w* the change to apply to the windows width.
- *h* the change to apply to the windows height.

Returns
~~~~~~~
*nil*.