Scripting allows automation of Microcosm worlds with the Lua programming language. This can be used to insert templates (including with randomizations), generate noise or geometric patterns, or even create (very) simple games.
This power means scripts can change or erase the currently open world; changes made by scripts may not be possible to undo! You should always test scripts in a blank or backup world to confirm they work how you expect they will.
You can try running some example scripts before unlocking the full feature. Unlocking allows you to write your own scripts or use ones shared by other people. The warning about testing in a blank/backup work applies to these examples as well, many of them make irreversible changes to the current world!
This guide assumes no existing familiarity with computer programming. All the examples can be copied and run directly in Microcosm, so you can easily experiment with them while figuring out how things work. Microcosm logs error messages with line numbers in the app to help you when things need debugging.
If you’re already familiar with programming but not Lua in particular, I highly recommend this whirlwind Lua tour. It’s also a great reference if any syntax in the examples confuses you. In any case, I’ve tried to design the Microcosm API to be as intuitive and beginner-friendly as possible.
This guide is designed to be read sequentially once, then referenced as needed going forward.
Before getting started, make sure you’ve got both Microcosm and a text editor app installed on your iOS device. I used the Runestone text editor while developing the API and creating this guide. It’s really pleasant, and has a generous free version.