Using the SDK

Overview

This page gives you guidance on how to make the best use of the Aether Engine SDK.

Local development

The 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.

Remote clusters

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 build and run commands.

From your simulation folder, the commands you need are:

• aether build --x-compile Build the simulation and create a CMake build folder.
• aether run --x-compile Copy 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