This repo contains documentation and specifications for MACS (Mechanized Assault Commanders) build-in scripting system
This specification explains about MACS embedded scripting API. Using this API you can write your own scenarios.
The script can be used to initialize the match by modifying the initail game conditions, or affect the game itself by modifying in-game behavior.
- In order to find unit types, open Units/originalUniset.json, refer to _type value. For example, Heavy vehicle plant is hvplant.
- In order to find available maps refer to loadedRemoteMaps.json in Saves folder. You should put desired map's file property + .wrl, for example 224x2246.wrl to start on Revelation map.
Game loads the file named initScript.lua. The file should be located in root directory of the scenario's zip arhive.
For details about initializion script please refer to Scripting Guide.
Scripts will be running on the main thread so please avoid running complicated calculations.
The script will be provided with a memory pool that is not syncronized between players so you should not retain any objects in the script global variables, outside of the API methods. Instead, you must retrieve all the needed data directly from the match on-the-fly.
You can still create some global structure the first time you run the script, but remember that you do this at your own risk, and it is entirely up to you to keep that structure (and all the script behvior derrived from it) reproducible.
Our recommendation is to follow the stateless approach as much as possible, leaving the management of persistent data to the hosting game.
To start creating your scenario you should open test match script which is located in game resources folder: Resources/Scripts/testMatch.lua:
You can open it with any text editor, I would recommend you Visual Studio Code, Atom, Sublime Text or Notepad++ because they have option to highlight script syntax, it is very useful.
In order to run the script, start the game, go LOCAL GAME and press small {>} button on the top-left corner of the screen. Game will start a local game with the content of testMatch.lua.
For details about initializion script please refer to Scripting Guide.
After you done with your scenario and want to show it to community you should do following steps:
- rename initialization script file (testMatch.lua file) into initScript.lua
- zip this file into arhive. Archive should contains this file in a root folder.
- go to website https://macsgame.com/#
- naviage to MY -> My Scenarios: https://macsgame.com/my/scenarios.html
- Choose Create New https://macsgame.com/my/edit-scenario.html
- Press Choose File button and select your zip archive
- Website will parse your script file and show its data. Press Add
- Now your script is uploaded. Press Ready and Save to show it in the game.
Now new scenario should appear for you in game.
On scenarios page (navigate to Game -> Scenarios https://macsgame.com/game/scenarios.html ) you can see all available scenarios.
Choose any scenario created by other member (for example: https://macsgame.com/game/scenario/3.html) and press Add to my list in order to see it in game.
This section contains information about objects and its APIs that hosting application exposes to lua side.
Structures are passed to script by value with transferring ownership into lua.
Objects will be passed by pointer and will stay owned/managed by MACS engine. Do not retain them for a long time - basically script will not know when object will be deleted.
Coming soon.
Built-in event system allow you to track and handle some game events.
Coming soon.
Quest system is based on handling events.