Script Reference
This is reference documentation for all public functions and properties exposed by the Finmer game engine. When writing Lua code for your own scenes and scripts, refer to this documentation for details on function names, signatures and the like.
If you intend to use the visual scripting feature, you do not need to consult this script reference. Simply create a Visual Script instead of a Raw Script when the Editor asks which one of the two you wish to pick.
Feature requests are welcome! If you'd like to implement behaviors that Finmer does not (fully) support, please feel free to reach out in the community - maybe a new system could be built to help support your use case!
The game engine may or may not expose additional functions or properties that are not included in this script reference. Usage of such undocumented features is not supported; they may change or break without notice in future updates.
About Lua
Lua is a simple, elegant script language. If you would like to learn it, there are lots of resources available online for you to peruse. You can find the official Lua 5.1 reference manual here, and a large directory of user-made tutorials here. Check the Script Reference to see what you can do with the game engine.
The game makes available for you most standard Lua libraries. You can use the base, coroutine, table, string and math libraries. Note that for security reasons, the io, os, package and debug libraries are unavailable.
Reference pages
The API is split up into these categories:
📄️ Messages & Logging
These are the basic functions for controlling text output in the main game screen.
📄️ Constructors
With these constructors, you can create instances of objects. These are used in various other functions; for example adding a participant to a combat session requires a Creature.
📄️ Scene & Flow Control
Functions related to controlling UI and the active scene.
📄️ World & Gameplay
Functions related to the world state.
📄️ Text & Grammar
Functions relating to the grammar engine. Please consult the section on Grammar & Contexts for information on how to use the grammar engine.
📄️ Combat System
Functions relating to the combat system. You can start and stop fights, and manipulate and inspect their state.
📄️ Rumor System
Rumors are pieces of game text, usually dialogue snippets, that can be spoken by various innkeepers or shopkeepers around the game world. They have a number of uses: they help steer players toward new content they may not have explored yet, they provide an easy way for the world to 'react' to player choices, and (especially more general quips) provide a little context for the game world.
📄️ Encounter System
Encounters allow for creating easily-moddable randomized events, such as a walk in the woods that could lead to any number of events occurring. You could add a new encounter with a wandering merchant, or perhaps a new monster encounter, or a new quest.
📄️ Shop System
These functions and properties are members of Shop instances. Create a Shop instance using the Shop function.
📄️ Save Data
These functions allow you to create save data. When save data is loaded, the game will load the scene that was active when the save was created, and resume the scene from the specific State or Choice node that created the save data. In other words, the script that caused save data to be created, will run again from the top. (The save dialog will not be presented again.)
📄️ Variables & Persistent Storage
These functions can be used to store data and keep it around between scenes. The key/value pairs are saved with the player's savegame. Because all Scenes each have their own self-contained script environment, this is the one and only way to communicate data between two Scenes, or to remember data the next time the same Scene is visited.
📄️ Quest Journal
These functions can be used to manipulate the player's quest log or 'journal', shown on the character sheet.
📄️ GameObject Interface
These functions and properties are members of GameObject instances. All Creatures, Items and the Player are GameObjects.
📄️ Creature Interface
These functions and properties are members of Creature instances. You can create an instance of a Creature using the Creature() function (see Asset Instantiation). The player character - obtained using the Player global variable - is also a Creature, so you can use the same properties.
📄️ Player Interface
These functions and properties are members of the Player instance. You can get the player object using the Player global variable.