sm64coopdx/docs/lua/lua.md

# Lua Reference

The Lua scripting API is in early development.

Expect many more things to be supported in the future.

<br />

## How to install Lua mods
Lua scripts you make can be placed either the `mods` folder in the base directory, or in `<SAVE FILE LOCATION>/mods`

Save file locations:
- Windows: `%appdata%/sm64ex-coop`
- Linux: `~/.local/share/sm64ex-coop`
- MacOS: `~/Library/Application Support/sm64ex-coop`

<br />

## Tips
- When developing Lua mods, run the game from a console. Lua errors and logs will appear there.
- You can use the `print()` command when debugging. Your logs will show up in the console.
- You can create a folder within the mods folder containing multiple lua scripts as long as one script is called `main.lua`. Dynos actors can be placed inside this mod folder under `<your mod folder>/actors/`.
<br />

## Sections
- [Globals](globals.md)
- [Constants](constants.md)
- [Functions](functions.md)
- [Structs](structs.md)

### Guides
- [Setting up Visual Studio Code](guides/vs-code-setup.md) 
- [Hooks](guides/hooks.md)
- [gMarioStates](guides/mario-state.md)
- [Behavior Object Lists](guides/object-lists.md)

## Important notes on player indices

Something important to realize is that the `localIndex` for each player is different (unfortunately).

So the order of `gMarioStates[]`, `gNetworkPlayers[]`, and `gPlayerSyncTable[]` is different for each player.

Luckily `gPlayerSyncTable[]` will automatically translate the player indices, so setting `gPlayerSyncTable[0].example = 1` will set it for the correct player for everyone.

The `globalIndex` of each player is consistent among everyone connected. So if you absolutely need to sort things in order you will have to grab it from `gNetworkPlayers[<LOCAL INDEX HERE>].globalIndex`.

All of this is a holdover from when there were only two players. It was a reasonable idea back then.

<br />

## Example Lua mods (small)
- [Low Gravity](examples/low-gravity.lua)
- [Faster Swimming](../../mods/faster-swimming.lua)
- [Mario Run](examples/Mario-Run.lua)
- [HUD Rendering](examples/hud.lua)
- [Object Spawning](examples/spawn-stuff.lua)
- [Custom Ball Behavior](examples/behavior-ball.lua)
- [Replace Goomba Behavior](examples/behavior-replace-goomba.lua)
- [Add to Goomba Behavior](examples/behavior-add-to-goomba.lua)
- [Behavior with Surface Collisions](examples/behavior-surface-collisions.lua)
- [Custom Surface Collisions](examples/big-paddle)
- [Custom Box Model](examples/custom-box-model)
- [Custom Player Model](examples/koopa-player-model)
- [Moonjump](examples/Moonjump.lua)
- [Instant Clip](examples/instant-clip.lua)
- [Water Height Changer](examples/water-level.lua)
- [Custom Level](examples/custom-level)
- [Custom HUD Texture](examples/custom-hud-texture)
- [Custom Audio Test](examples/audio-test)
- [Custom Texture Overriding](examples/texture-override)

## Example Lua mods (large)
- [Hide and Seek Gamemode](../../mods/hide-and-seek.lua)
Autogenerated Lua documentation 2022-01-30 06:47:22 +00:00			`# Lua Reference`

			`The Lua scripting API is in early development.`

			`Expect many more things to be supported in the future.`

			`<br />`

			`## How to install Lua mods`
Reformat platform save file locations 2022-09-13 03:04:37 +00:00			Lua scripts you make can be placed either the `mods` folder in the base directory, or in `<SAVE FILE LOCATION>/mods`

			`Save file locations:`
			- Windows: `%appdata%/sm64ex-coop`
			- Linux: `~/.local/share/sm64ex-coop`
			- MacOS: `~/Library/Application Support/sm64ex-coop`
Autogenerated Lua documentation 2022-01-30 06:47:22 +00:00
			`<br />`

Added a bunch of functions to Lua wrapper 2022-02-05 03:13:15 +00:00			`## Tips`
			`- When developing Lua mods, run the game from a console. Lua errors and logs will appear there.`
			- You can use the `print()` command when debugging. Your logs will show up in the console.
Add custom box model example 2022-03-17 05:55:16 +00:00			- You can create a folder within the mods folder containing multiple lua scripts as long as one script is called `main.lua`. Dynos actors can be placed inside this mod folder under `<your mod folder>/actors/`.
Added a bunch of functions to Lua wrapper 2022-02-05 03:13:15 +00:00			`<br />`

Added Sync Tables to lua documentation 2022-02-02 02:52:26 +00:00			`## Sections`
			`- [Globals](globals.md)`
Autogenerated Lua documentation 2022-01-30 06:47:22 +00:00			`- [Constants](constants.md)`
			`- [Functions](functions.md)`
			`- [Structs](structs.md)`

Doc stuff (#182) 2022-09-13 03:01:45 +00:00			`### Guides`
Document every behavior's object list (#252) 2023-01-31 12:33:51 +00:00			`- [Setting up Visual Studio Code](guides/vs-code-setup.md)`
Doc stuff (#182) 2022-09-13 03:01:45 +00:00			`- [Hooks](guides/hooks.md)`
			`- [gMarioStates](guides/mario-state.md)`
Document every behavior's object list (#252) 2023-01-31 12:33:51 +00:00			`- [Behavior Object Lists](guides/object-lists.md)`
Autogenerated Lua documentation 2022-01-30 06:47:22 +00:00
Add notes on player indices to Lua docs 2022-03-05 07:20:53 +00:00			`## Important notes on player indices`

			Something important to realize is that the `localIndex` for each player is different (unfortunately).

			So the order of `gMarioStates[]`, `gNetworkPlayers[]`, and `gPlayerSyncTable[]` is different for each player.

			Luckily `gPlayerSyncTable[]` will automatically translate the player indices, so setting `gPlayerSyncTable[0].example = 1` will set it for the correct player for everyone.

			The `globalIndex` of each player is consistent among everyone connected. So if you absolutely need to sort things in order you will have to grab it from `gNetworkPlayers[<LOCAL INDEX HERE>].globalIndex`.

			`All of this is a holdover from when there were only two players. It was a reasonable idea back then.`

			`<br />`

Merge branch 'unstable' of github.com:sm64ex-coop-dev/sm64ex-coop into unstable 2022-03-19 07:59:06 +00:00			`## Example Lua mods (small)`
Move audio test example 2022-05-08 07:26:55 +00:00			`- [Low Gravity](examples/low-gravity.lua)`
Autogenerated Lua documentation 2022-01-30 06:47:22 +00:00			`- [Faster Swimming](../../mods/faster-swimming.lua)`
Moved low gravity and mario run to examples 2022-04-13 08:38:32 +00:00			`- [Mario Run](examples/Mario-Run.lua)`
Added rect rendering to Lua API 2022-02-16 06:15:49 +00:00			`- [HUD Rendering](examples/hud.lua)`
Add spawn-stuff lua example 2022-02-26 08:03:21 +00:00			`- [Object Spawning](examples/spawn-stuff.lua)`
Add custom behavior Lua examples 2022-03-05 07:14:01 +00:00			`- [Custom Ball Behavior](examples/behavior-ball.lua)`
Made adding to behaviors possible in Lua 2022-03-05 09:29:24 +00:00			`- [Replace Goomba Behavior](examples/behavior-replace-goomba.lua)`
			`- [Add to Goomba Behavior](examples/behavior-add-to-goomba.lua)`
Added the ability to set surface collisions on custom behaviors 2022-03-10 06:58:45 +00:00			`- [Behavior with Surface Collisions](examples/behavior-surface-collisions.lua)`
Added big paddle example 2022-03-31 04:36:47 +00:00			`- [Custom Surface Collisions](examples/big-paddle)`
Add custom box model example 2022-03-17 05:55:16 +00:00			`- [Custom Box Model](examples/custom-box-model)`
Added custom player model example 2022-03-18 04:41:46 +00:00			`- [Custom Player Model](examples/koopa-player-model)`
Fix broken link to Moonjump.lua thanks to nonperforming on github 2023-11-07 08:51:54 +00:00			`- [Moonjump](examples/Moonjump.lua)`
Add get/set_environment_region (#56) Set the water height with a function. Also added an example for it in the documentation. 2022-04-05 22:53:16 +00:00			`- [Instant Clip](examples/instant-clip.lua)`
			`- [Water Height Changer](examples/water-level.lua)`
Custom level example 2022-04-16 05:01:19 +00:00			`- [Custom Level](examples/custom-level)`
Add custom hud texture example 2022-05-07 05:06:35 +00:00			`- [Custom HUD Texture](examples/custom-hud-texture)`
Move audio test example 2022-05-08 07:26:55 +00:00			`- [Custom Audio Test](examples/audio-test)`
Add texture overriding example 2023-11-13 14:30:20 +00:00			`- [Custom Texture Overriding](examples/texture-override)`
Merge branch 'unstable' of github.com:sm64ex-coop-dev/sm64ex-coop into unstable 2022-03-19 07:59:06 +00:00
			`## Example Lua mods (large)`
			`- [Hide and Seek Gamemode](../../mods/hide-and-seek.lua)`