AMSCRIPT
table of contents
overview
The auto-mcs scripting API (amscript) is available to quickly create universal plugins for your auto-mcs servers. It functions primarily as an asynchronous wrapper which fires events from what happens in-game and uses standard Python 3.9 syntax. Because of this mechanic, a single script will work with every Vanilla, CraftBukkit (and derivatives), Forge, and Fabric server regardless of the game version.
getting started
Note: If you don’t wish to write scripts yourself or would like to view examples, there’s a built-in repository available from the amscript manager by clicking ‘Download’
The amscript engine and all of its dependencies are pre-installed and entirely integrated into auto-mcs. You don’t need to download anything to get started! As mentioned previously, amscript is generally based on Python 3.9. If you’re unfamiliar with Python, there are a plethora of resources to learn from such as this. Because of this functionality, you can utilize effectively anything you can do in Python like web requests, OS operations, other APIs, and so much more.
On top of Python, amscript includes an API by default to manage auto-mcs and your server. Additionally, amscript implements events to run code based on in-game activities.
Another useful feature is a fast and simple built-in IDE with API auto-completion, real-time syntax error detection, and familiar keyboard shortcuts. From the Server Manager, you can start coding in two clicks without needing to download anything else! You can also download, import, or drag ‘n’ drop scripts. They are shared between every server, but can be enabled/disabled independently.
Note: Scripts are not backed up automatically by the Back-up Manager. Click on the folder icon in the top right and copy them elsewhere, or even write a script to back them up!
API & events
The amscript API provides modules to interact with auto-mcs (imported by default). Additionally, there are events driven by special decorators. These events are triggered by certain conditions in-game to run snippets of code.
For a comprehensive reference of the module & event syntax, arguments, and methods, consider viewing the API documentation.
amscript IDE
You don’t need any special software or tools to take advantage of the power of amscript. This development environment is included directly with the installation of auto-mcs.
controls
Inside the Server Manager, create a new script or edit an existing one to open the amscript IDE. Here’s a reference to common controls in the editor:
Right-click the background to view the context menu of options
Press
CTRL-Cto copy andCTRL-Vto pastePress
CTRL-Zto undo andCTRL-Rto redoPress
CTRL-Fto find andCTRL-Hto find & replace
Press
TABto indent andSHIFT-TABto unindent
Press
CTRL-/to toggle commentsPress
CTRL-PLUSorCTRL-MINUSto change font sizeamscriptToggle, download, or import scripts
saving & modification
As you’re editing your script, the IDE will auto-save. There’s no need to worry about losing your progress.
Note: If editing a script while the server is running, you’ll need to reload the amscript engine by clicking ‘Reload Scripts’ in the top right corner of the Script Manager. You can also use the
!ams reloadcommand in the console or in-game chat
auto-completion
With the addition of custom modules and events, auto-completion makes it easier to reference available methods and syntax. Press TAB/ENTER to fill in the entirety of a method or event call. You can also press the 🡡/🡣 keys to switch between different auto-complete suggestions.
error detection
Simple syntactic errors in the IDE are displayed inline with a red highlight, and the error itself is shown in the bottom right corner. Clicking on the error text will scroll to the line.
Deferred code (in function execution) is not able to be processed until runtime. You may see errors for more complex issues in the server console.
external modules
To further elaborate on Python integration, it’s entirely possible to create your own modules or install them from PyPI with pip.
First, verify that the amscript libs folder is available. In the top right corner of the amscript manager, click on the folder icon to open the amscript directory and look for the folder there. If it doesn’t exist, create it. Make sure that you have a valid Python 3.9 installation to utilize the pip package manager.
Note: Keep in mind that amscript files have a file extension of
.ams, and all libraries have a.pyextension. Libraries are unable to use the amscript modules or events
Windows installation
Open a Command Prompt and run the following command:
pip install --target "%appdata%\.auto-mcs\Tools\amscript\libs" <package-name>
Linux installation
Open a terminal and run the following command:
pip install --target ~/.auto-mcs/Tools/amscript/libs <package-name>
custom modules
Writing a module works the same way it would in a normal Python environment. In such cases, it’s beneficial to utilize a more in-depth IDE such as PyCharm or Spyder. This guide won’t go over writing modules, though you can learn more here. Make sure to place them in the libs folder detailed above.