Using the SDK
This page gives you guidance on how to make the best use of the Aether Engine SDK.
aether CLI command is the entry point for developing a simulation using the Aether Engine SDK. It enables the creation of new simulations, alongside building and running existing simulations. Most developers will use the CLI in conjunction with the local VM installed with the Aether Engine SDK in order to build and test new features in their simulations. Once a feature is ready for larger scale testing, it can be deployed onto a cluster.
Creating a new simulation
To get started creating a new simulation, run
aether new <project_name>. This will create a folder called
<project_name>, which will contain a basic simulation and muxer. You can
cd into this project to use the new simulation.
Building a simulation
Compilation of your simulation for local development happens within the local VM. Compilation is done through CMake using the Clang compiler. You can compile your simulation and muxer by running
aether build within your simulation directory. If you prefer to run it from elsewhere, then use the
--directory flag to point to the root of your simulation. You have control over the CMake configuration for your simulation, the only requirement imposed is that you must finish by installing one binary called
simulation and another called
muxer for the simulation and muxer executables respectively. The demo projects show some examples on how you may choose to do this. The demos also show how to link against the libraries and headers the Aether Engine provides.
Running a simulation
Once you have a simulation that you are ready to run, then from within your simulation directory, run
aether run to start up your simulation. This will launch the simulation on the local VM, launching both the simulation and muxer. You can connect to a muxer running on the local VM from a client by using the address
aether-sdk.mshome.net:8881. Once running, the CLI will show you the logs received from the VM. You can use the
AETHER_LOG(INFO)("message") macro to log information from your simulations. Once you are finished with a simulation, press
ctrl+c - you will be presented with a prompt allowing you to either shut down the simulation (the default) or leave it running. If you choose to leave the simulation running, you can use
aether run to re-attach to the log stream, or
aether stop to stop the simulation. If there is a
user.cfg file in your simulation directory, this will be passed to the running simulation, allowing you to inject runtime configuration into your simulation. If at any point you wish to check if a simulation is running, you can run
aether status to find out.
You need to be connected to the internet for the first time when running a simulation on your local VM, but can then work offline after this.
Once you have a simulation that you wish to run on a remote cluster, you will need to have a provisioned cluster to run on. If you already have a cluster running and configured, you can get the ID for it from the Hadean Web Portal. The following assumes you have a cluster provisioned and you have the ID for it. If you need to provision a cluster, see Provisioning a cluster.
Building a simulation
When building a simulation to run on a remote cluster, you will still use the Local VM as the build environment. When running on a cluster, the locally built artefacts will be copied to the remote cluster.
Running a simulation
Running a simulation works in the same way for clusters as for local development, you can start a simulation with
aether run --cluster <cluster_id>. Initially you will be presented with a list of possible muxers to connect to - this will reflect your cluster setup. Press
enter to continue the deployment. This will now start your simulation on the cluster and begin streaming logs back to your terminal. If you wish to stop receieving logs, then press
ctrl+c. This will present a prompt asking if you would like to shut down your simulation (the default) or leave it running. If you choose to leave a simulation running then you can re-attach to the log stream with
aether run --cluster <cluster_id>, or stop it with
aether stop --cluster <cluster_id>. If you would like to know if a cluster is currently running a simulation, you can use
aether status --cluster <cluster_id>.
In order to use a cluster, you must be connected to the internet, and have been granted access to that cluster. Administrators for your company can control access to a specific cluster on the Hadean Web Portal.
The local VM
To enable local development, you can install a virtual machine that has the Aether Engine and build environment already installed. You can do this by using the Aether Engine SDK installer. If you did not install it originally, you can re-run the installer to add this component. The local VM is run using Hyper-V, and you can turn it off and on through the Hyper-V Manager. When developing locally, the Aether Engine will still use multiple workers that hand over entities to each other so you can develop in confidence, knowing that your code developed locally will work when deployed on a cluster.
Cross compiling (preview feature)
From version 1.2 you can build directly on Windows (instead of on the Virtual Machine). This greatly speeds up building and iterating. To check you can use the new build process run
aether build --help and look for the
--x-compile option, if it's not there, update to the latest version of Aether Engine SDK. All you need to do is add the
--x-compile flag to aether
From your simulation folder, the commands you need are:
aether build --x-compileBuild the simulation and create a CMake build folder.
aether run --x-compileCopy the build to the local VM and run the simulation.
aether run --x-compile --cluster <cluster_id>Send the build to the specified cluster and run the simulation.
Debug as usual with
aether run --debug