Wiki/Guides/Lua/Exploring the Stormworks Lua API

{{Wiki_Page | content=

After reading this you should proceed with Special advise and little known facts

=Theory=


 * Lua scripts run on the server and on the client, they can get into a state where they are not syncronized (e.g. )! While the composite input and output are syncronized, the output on the screen can be different!
 * When vehicle are out of sight (too far away) they despawn. Once you are coming closer, the spawn again. The values of Memory components is being restored, but the lua scripts are reset (like on spawn from workbench). If you need to persist some data, use Memory components or use a No-Despawn-Block (NOT RECOMMENDED because of performance problems!).

Interacting with composite data / onTick

 * the function is called everytime the physics engine calculates a new tick. The frequency is ~60 times per second, but can be way less when you spawn in large vehicles or are in multiplayer
 * you are not allowed to access screen functions at this time, this needs to be done in onDraw
 * if the execution of onTick takes longer then 16ms, you effectively slow down the physics engine speed of the game (= slow down)
 * if the execution of onTick takes longer then 100ms, the game will exit the function and discard the calculations done

Interacting with the Screen / onDraw

 * the function is called everytime the game draws a new frame. The frequency depends on your games FPS and is either ~60 times per second (no vsync) or ~30 FPS (with vsync)
 * you are not allowed to access composite input and output at this time, this needs to be done in onTick
 * for every connected monitor, this function will be called once. If you have 5 monitors connected, the function will be called 5 times per frame.
 * if you the position of stuff to draw on the monitor is based on its size (e.g. ) the stuff will look different on monitors with different sizes, but connected to the same script
 * if the execution of onDraw takes longer then 16ms, you effectively slow down the FPS of the game
 * if the execution of onDraw takes longer then 100ms, the game will exit the function and discard the drawn stuff

Interacting with http
You can send HTTP requests from within Lua.

Lua is executed on the server itself (a normal game or dedicated server) and on the every connected client. If a Lua script calls async.httpGet every server/client will make a http request to it's own machine (localhost). This means, you cannot transmit any information inbetween players directly, and you cannot access any website on the internet. If a server/client has no webserver running on the specifiec port, the package will simply be dropped and the response_body will be exactly "connect: Connection refused".

You can run your own webserver and pickup those requests and respond to them. Your webserver could also talk with other services (e.g. Youtube or Discord) and behave like a gateway for your lua script.

Important Information: This information is quite important if you want to develop a lua script with http.

Example code:


 * url must begin with a slash: /test?param=hello
 * rate limit: you are only allowed to send 1 http request per tick. If you send more they will be placed into a queue. Every tick, the oldest request from that queue will be processed. This means potential delay!
 * error handling: the error handling inside lua is very very bad. If you want some more documentation create an issue on mcro.org

Available functions
For a complete list, go to https://lua.flaffipony.rocks and scroll down to the bottom part of the page. Here are the most important ones:

Monitor coordinates

 * the top left corner is x=0, y=0
 * x is the axis to the right
 * y = is the axis to bottom

=Practical Examples=

Reading and writing to composite
Let's say we want to read to values from composite, add them together and output the result on the composite again.

Visualize rotation
Let's say you have a velocity pivot and want to visualize it's current rotation.

Drawing a graph of battery level over time
After reading this you should proceed with Special advise and little known facts

}}