In this short tutorial you will create a simple module, learning about the structure of a module, contents of the module manifest, the nature of declaration blocks and more.
Internal structure of modules is almost completely arbitrary. You can organize your files as you want. This is because all module files (also called user files) are "the same" in terms of their internal structure. Inside the files we have declaration blocks that allow us to declare different kinds of elements. No external context is required.
The only element that's always required is the manifest. The manifest always exists in the top directory of the module.
A single module is itself a single directory with a module manifest
module.yaml inside. Such a module with only the manifest present is a valid one, even though it's totally empty otherwise.
Let's start by creating a new directory and naming it:
Remember that the name of the directory has to always match the name of the module as defined in the manifest.
Module name is a string of characters without spaces. Doesn't really matter whether it's written as
FirstModule; although it's useful to keep the convention the same for any single project you work on (e.g. a single module or scenario).
Next we'll create a new file. You can use any text editor you want. Call the file
module.yaml. This is our module manifest. Paste the following lines into the new file and modify the entries as you see fit.
name: "first_module" title: "First module" desc: "First module created using the glorious tutorial." author: "User" version: "0.1.0" engine: "*"
There are a few more entries we could use, like
desc_long for long description and
website to point anyone who uses our mod to the right place if they needed help or wanted to submit a fix. We also didn't declare
dependencies which simply means there aren't any.
If you use some sort of version control solution like
gitit's useful to include an online address of the repository in the
Let's create a new file. Call it whatever you want, just make sure the extension is
.yml. I created a file named
examples.yaml. The directory tree should look something like this
first_module ├── examples.yaml └── module.yaml
We will include a couple things in our file:
- new entity type
- new component type
- new entity
- new component
Each of these elements requires us to create a new block. Consider the following example.
new_block: - element_1 # '-' means a list in yaml, so this is an element in the "new_block" list - element_2 # '#' means a comment, so anything after it on that particular line is ignored:)
And here's what we're going to include in our file
entity_types: - id: "region" component_types: - id: "property" entities: - id: "greenland" type: "region" components: # a component to track the bear population in a region - id: bear_population type: property entity: region start_state: main # "tick" clock event is built-in, called on every clock tick trigger_event: tick vars: - pub int count = 2275 states: # this is the only state in this component's state machine - id: main cmds: # it will simply print the "count" integer var every tick - print int/count
That should do it. There is only one problem though - we can't run a simulation with just a module. Before we can run this and see how it prints the bear population count every tick we have one more step ahead of us. We need to create a scenario.