Create Lua_Docs.md

Created a basic Documentation of currently implemented lua functions.
This commit is contained in:
NPO 2024-10-22 10:48:24 -04:00
parent d92fb25ecb
commit f16fe763a3
1 changed files with 185 additions and 0 deletions

View File

@ -0,0 +1,185 @@
# Lua Script Overview
### Note
Lua scripting support is still a work in progress, lua features and functions are subject to change.
## Hello World Eample
Example of a Lua script that, when run, will display "Hello World", and a frame counter on the top screen.
```Lua
screenID = 0 -- TopScreen = 0, BottomScreen = 1, OSD = 2
canvas = MakeCanvas(0,0,100,100,screenID)
SetCanvas(canvas)
frameCount = 0
-- '_Update()' gets called once every frame
function _Update()
frameCount = frameCount+1
ClearOverlay()
Text(0,10,"Hello World: "..frameCount,0xffffff) --White text
Flip()
end
```
## Types and Notation
`uReturnedVal FunctionName(uArg1,uArg2,[uOptionalArg1 = defaultVal],[uOptionalArg2 = defaultVal],...)`
- `FunctionName` the name of the function
- `uArg` Non optional argument expected of type "u" (lua types are n="number",s="string",b="boolean", t="table")
- `[uOptionalArg = defaultVal]` optional argument expected of type "u" if not provided defaults to `defaultVal`
- `uReturnedVal` Value returned by function (usually `nil`)
## Function List
`nil MelonPrint(sPrintText)`
- Print `sPrintText` to the lua consol
- for now use this instead of `print()`
`nil MelonClear()`
- Clearse the lua consol
`n_u8Value Readu8(nAddress)`
- Read Data unisigned one Byte from u32 address `nAddress`
`n_u16Value Readu16(nAddress)`
- Read Data unisigned two Bytes from u32 address `nAddress`
`n_u32Value Readu32(nAddress)`
- Read Data unisigned four Bytes from u32 address `nAddress`
`n_s8Value Readu8(nAddress)`
- Read Data signed one Byte from u32 address `nAddress`
`n_s16Value Readu16(nAddress)`
- Read Data signed two Bytes from u32 address `nAddress`
`n_s32Value Readu32(nAddress)`
- Read Data signed four Bytes from u32 address `nAddress`
`nil NDSTapDown(nX,nY)`
- Push down on the bottom touchscreen at pixel position X,Y.
- touchscreen dimensions are 256x192.
`nil NDSTapUp()`
- Releases the touch screen.
`nil StateSave(sFileName)`
- Creates a savestate and saves it as `sFileName`.
`nil StateLoad(sFileName)`
- Attempts to load a savestate with the filename `sFileName`.
`tMouseState GetMouse()`
- Returns a lua table of the mouse X/Y coordinates and button states.
- Table keys are: `X, Y, Left, Middle, Right, XButton1, XButton2`
- Example
```Lua
if GetMouse().Left == true then
MelonPrint("Click at:"..GetMouse().X..','..GetMouse().Y)
end
```
`tJoyState GetJoy()`
- Returns a lua table of the Joypad button states.
- Table keys are: `A,B,Select,Start,Right,Left,Up,Down,R,L,X,Y`
- Example
```Lua
function JoyText()
joys = GetJoy()
str = ""
for k,v in pairs(joys) do
if v then
str = str..k
end
end
return "Joy:"..str
end
```
`tKeyMask KeyboardMask()`
- Returns a lua table of 256 bool values representing the current state of the keyboard.
- Most Keys are ascii
- TODO: Improve support for non-US Keyboards
- Example
```Lua
--Print id of key being pressed
for k,v in pairs(KeyboardMask()) do
if v then
MelonPrint("KeyPressed:"..k)
end
end
--Check if the "Q" key is currently pressed
if KeyboardMask()[string.byte("Q")] then
MelonPrint("\"Q\" Pressed!")
end
```
`tKeyStrokes Keys()`
- Returns a lua table of all keys pressed since the last time `Keys()` was called...
- DIFFERENT from `KeyboardMask()`
- Mostly used for detecting special non-US Keyboard keys, or for faster typing/higher poll rate
- Example
```Lua
typed = ""
keys = {}
function KeysText()
keys = Keys()
str = ""
for _,i in pairs(keys) do
if pcall(string.char,i) then
str = str..string.char(i)
else
MelonPrint("NonAscii:"..i)
typed = ""
end
end
typed = typed..str
return "Keys:"..typed
end
```
`nCanvasID MakeCanvas(nX, nY,nWidth,nHeight,[nScreenTarget = 2],[bIsActive = true])`
- Creates a new canvas and returns it's ID.
- You must set a canvas using `SetCanvas` before drawing anything to the screen.
- `nScreenTarget` options are 0 = TopScreen, 1 = BottomScreen, 2 = OSD / non-screen target (default)
- `bIsActive` must be true for the canvas to be drawn to the screen (true by default)
- `nCanvasID` is the ID of the newly created Canvas.
`nil SetCanvas(nCanvasID)`
- Sets the current canvas to `nCanvasID`
- All future drawing functions will draw to the *currently set canvas*.
`nil ClearOverlay()`
- Clears the *currently set canvas* by setting all pixels to `0x00000000` transparent black
`nil Flip()`
- Tells MelonDS that the *currently set canvas* has been updated and must be redrawn.
- This may be handled automatically in the future...
`nil Text(nX,nY,sMessage, [nColor = 0x000000],[nFontSize = 9],[sFontFamily = 'Helvetica'])`
- Draws `sMessage` to the *currently set canvas* given the color and font specified.
- Qt will attempt to match `sFontFamily` to the closest font it can find available...
`nil Line(nX1,nY1,nX2,nY2,nColor)`
- Draws a line on the *currently set canvas* fom (x1,y1) to (x2,y2) of the specified color.
`nil Rect(nX,nY,nWidth,nHeight,ncolor)`
- Draws a 1p width Rectangle on the *currently set canvas* of the given size position and color.
`nil FillRect(nX,nY,nWidth,nHeight,ncolor)`
- Draws a filled in Rectangle on the *currently set canvas* of the given size position and color.
`nil Ellipse(nX,nY,nWidth,nHeight,ncolor)`
- Draws a 1p width Ellipse on the *currently set canvas* of the given size position and color.
`nil DrawImage(sImagePath,nX,nY,[nSourceX = 0],[nSourceY = 0],[nSourceWidth = -1],[nSourceHeight = -1])`
- Draws the image saved at `sImagePath` to the *currently set canvas* at the given position.
- By default copies the entire image to the canvas.
- optional arguments Source-(X,Y,Width,Height) determain where in the source image to copy from.
`nil ClearImageHash()`
- Clears the interal hash of all images drawn using DrawImage
- Only needed if RAM is being filled up with lots of different Image files.