Getting Started
🌐 English · 日本語
- Getting Started with Mana
- What is Mana?
- Writing a program as text
- Setting up Mana
- Your first Mana program
- Compiling, running and fixing errors
You start by writing code, saving it, and running it to print some text. At the end you look at how compilation works and fix an error.
- What is Mana?
- Writing a program as text
- Setting up Mana
- Your first Mana program
- Compiling, running and fixing errors
If you are used to editing files and working in a terminal, start from setting up. If you can already run mana, go ahead and run your first program.
Next comes the Mana Tutorial.
Mana is a programming language for describing, in text, how characters and events unfold in a game. You use it to combine work done by several roles, such as "the guide speaks → the gate opens → the guide gives the next hint".
First you print some text, then you build a small event in which a guide and a gate work together. The practice event prints text to the terminal. You do not need a game screen or character images.
Guide: Welcome!
Gate: Open.
Event: Finished.
In a real game, the parts that print text are connected to the game's own conversations, animations and so on. Graphics, physics and sound are provided by the game, and Mana describes the order and the conditions in which they happen.
In this example, the guide and the gate each become an Actor. An Actor is a unit of execution with its own processing and state. Besides characters, it can be a gate or the controller that runs a whole event.
The work an Actor does is an Action, and the way to ask for an Action to run is a Request.
| Term | Example in this event |
|---|---|
| Actor | The guide Guide and the gate Gate
|
| Action |
talk to talk, open to open |
| Request | The event controller asks the guide to talk |
You do not need to memorise these names now. You will check them as you write code.
A Mana program is written in a text editor and saved to a file. The program a person writes is source code, and the file it is saved in is a source file.
Mana has a compilation step. Compiling means checking the source code and turning it into data that can be run. An execution environment called the Mana VM runs that data.
flowchart LR
A["Write the source code"] --> B["Compile it"]
B --> C["Run it on the Mana VM"]
C --> D["Check the result"]
In this guide, one command compiles and then runs your program. You do not have to program the compiler or the VM yourself.
- If you have never programmed before, continue with Writing a program as text.
- If you are used to editing files and working in a terminal, you can start from Setting up Mana.
- If you want to embed Mana in a C++ application, see the integration guide.
This page helps you tell apart the place where you write code and the place where you run it. You can read it before you have set up the Mana tools.
A text editor is an app for typing text and saving it to a file. Mana code is saved as plain text, not in a document format that stores text colours or paragraph styles.
A terminal is a window where you type commands to run tools. On Windows you use PowerShell, and on Linux a shell.
In these lessons, each code box is labelled with what it is for.
Example source code — what you type in the editor:
actor Hello
{
action main()
{
print("Hello, Mana!\n");
}
}
Example command — what you type in the terminal:
mana hello.mn
You do not write the command into the source file. mana is the name of the tool, and hello.mn is the file it processes. How to point to the tool is set up on the next page.
The .mn in hello.mn is the extension: the end of a file name that shows what the file is for. Mana source files normally use it.
When you save, check the following.
- Name the file
hello.mn. Make sure it has not becomehello.mn.txt. - Use UTF-8 as the character encoding. The examples in these lessons are saved and used as UTF-8.
- Remember the folder you saved it in. A folder is also called a directory.
- Save after editing. The command reads what has been saved to disk.
If you cannot see extensions on Windows, turn on file name extensions in File Explorer.
print("Hello, Mana!\n"); is an instruction that prints text.
| Written as | Role |
|---|---|
"Hello, Mana!\n" |
The text to print. A string is enclosed in straight double quotes "
|
\n |
A line break inside the string |
; |
The end of this statement |
{ and }
|
Enclose the extent of a definition or a block of work |
Type brackets, semicolons and other symbols in half-width (ASCII) characters. Upper and lower case are different, as in Hello and hello.
The spaces at the start of a line are called indentation. To make it easy to see which block a line belongs to, these lessons add four spaces each time a line goes one level further in. Indentation does not let you leave out any brackets or ; that are needed.
Everything from // to the end of the line is a comment. You can write explanations there for people to read.
Example inside an Action:
// Print the welcome text
print("Welcome!\n");
A program does not have to be finished in one go. Make a small change and check the result. An error is a clue for reviewing what you typed. You will practise reading errors later.
Next, Setting up Mana prepares the tool you use to run programs.
The goal of this page is to run mana --version in a terminal and see the version information.
Here you build the tool from the repository. Building means turning the C++ sources that implement Mana into an executable you can use. It is not something you do every time you write a Mana script.
If you have Git, run the following in a terminal. Git is a tool for fetching and managing source code.
git clone https://github.com/shun126/Mana.git
cd Mana
cd is the command that changes the folder you are working in. In these lessons, the folder you have just entered, the one containing CMakeLists.txt, is called the Mana folder.
If you do not use Git, download the repository's source as a ZIP, extract it, and open a terminal in that folder.
You need Visual Studio 2022 or newer with C++ desktop development (MSVC v143 or newer and the Windows SDK), CMake 3.20 or newer, Python 3, Bison 3.8 or newer, and Flex 2.6.4 or newer. Bison and Flex generate the C++ code that processes Mana's grammar.
- In the Visual Studio Installer, set up Desktop development with C++.
- Get Bison and Flex executables that run on Windows.
- In PowerShell in the Mana folder, run these commands. Set the required environment variables to the absolute paths of the Bison and Flex executables at their actual locations.
$env:BISON_EXECUTABLE = "C:\path\to\bison.exe"
$env:FLEX_EXECUTABLE = "C:\path\to\flex.exe"
cmake -S . -B build -A x64
cmake --build build --config Release --parallel
ctest --test-dir build -C Release --output-on-failureBoth environment variables are required even if Bison and Flex are on PATH. To configure in the Visual Studio IDE, set them as Windows user environment variables and restart Visual Studio, or supply them in a local CMakeSettings.json environments entry. For a 32-bit build, use -A Win32 and a separate build folder. CMake uses the newest Visual Studio it finds; to use a specific version, add -G with its generator name, such as -G "Visual Studio 17 2022".
Once the build succeeds, check it in PowerShell in the Mana folder.
.\build\Release\mana.exe --versionWhen the version information appears, enter the following in the same PowerShell.
Set-Alias mana (Resolve-Path .\build\Release\mana.exe).Path
mana --versionNow, as long as this PowerShell stays open, you can run the tool by the short name mana. You do not need to change PATH. When you open a new PowerShell, run Set-Alias again in the Mana folder.
Install a C++17 compiler, CMake 3.20 or newer, Make, Python 3, Bison 3.8 or newer, and Flex 2.6.4 or newer. Follow your Linux distribution's instructions for installing the packages.
Run the following in a terminal to check that each tool is available.
cmake --version
bison --version
flex --versionBuild in the Mana folder.
export BISON_EXECUTABLE="$(command -v bison)"
export FLEX_EXECUTABLE="$(command -v flex)"
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
ctest --test-dir build --output-on-failure
./build/mana --versionWhen the version information appears, run the following in Bash.
mana_executable="$(pwd)/build/mana"
mana() { "$mana_executable" "$@"; }
mana --versionFrom now on you can type mana in the same terminal. The function remembers where the executable is and passes the arguments on to it. It only lasts for the current shell, so set it up again in the Mana folder whenever you open a new terminal.
The rest of the lessons assume that you work in the Mana folder and use the same terminal you set up here. If mana --version works, you are ready.
If something goes wrong, check in this order.
| Situation | What to check |
|---|---|
| The build fails because Bison or Flex cannot be found | Whether BISON_EXECUTABLE and FLEX_EXECUTABLE point to existing executables |
| The executable cannot be found | Whether the build succeeded. On Windows, whether you built Release / x64
|
It works with the full path but not as mana
|
Whether you set up the short name in this terminal |
| The source file cannot be found | Whether the terminal's working folder matches where you saved the file |
Next is Your first Mana program.
You print some text, then change that text yourself. Use the terminal you set up on the setup page.
Type the following whole file into your editor and save it in the Mana folder as hello.mn. Save it as UTF-8 plain text.
actor Hello
{
action main()
{
print("Hello, Mana!\n");
}
}
In the terminal in the Mana folder, enter the following.
mana hello.mn
Expected output:
Hello, Mana!
If you see it, it worked. If not, check that the file has not become hello.mn.txt, that you saved it, and that the terminal's working folder is the Mana folder.
To compare with the example, you can also use the finished code that comes with Mana.
mana examples/tutorial/01-hello.mn
actor Hello defines an Actor named Hello. Hello is a name you chose.
The action main() inside it defines work the Actor does. main is a special Action name that runs at startup. For now, remember that this is where you write the first thing to run.
print("Hello, Mana!\n"); is a statement that outputs text. In the examples so far, output goes to the terminal.
If you follow which { matches which }, you can see that print is inside main, and main is inside Hello.
Replace the print line with these two lines.
print("Welcome!\n");
print("The gate is closed.\n");
Save, then run mana hello.mn again.
Welcome!
The gate is closed.
Inside this Action, statements run from top to bottom. Swap the two lines and the output swaps too.
Next, Compiling, running and fixing errors shows what happens before a program runs, and how to investigate when something is wrong.
mana hello.mn compiles the source and runs the result on the Mana VM. This page looks at the two steps separately and has you fix an error.
The compiler checks grammar, names, types and so on, and produces the data to run: a Program Image. A Program Image is data the Mana VM reads; it is not an executable the CPU runs directly.
flowchart TD
A["Edit and save the source"] --> B["Compile"]
B --> C{"Did it succeed?"}
C -->|No| D["Read the diagnostics and fix"]
D --> A
C -->|Yes| E["Program Image"]
E --> F["Run on the Mana VM"]
F --> G{"Expected result?"}
G -->|No| A
G -->|Yes| H["On to the next change"]
A program that compiles does not necessarily do what you intended. For example, a program that prints things in the wrong order still runs if its grammar is correct.
Replace hello.mn with the following. This example is code that fails to compile on purpose.
actor Hello
{
action main()
{
print("Hello, Mana!\n")
}
}
Save and run it.
mana hello.mn
The print line has no ; at the end, so compilation fails. These are the diagnostics the current implementation reports. The file name may be preceded by the path where it is saved.
hello.mn(6): error: syntax error
hello.mn(8): error: syntax error
The first line means "a grammar problem was found on line 6 of hello.mn". The wording of diagnostics differs between versions, but look for the following information.
| Information in a diagnostic | What to check |
|---|---|
| File name | Which file to fix |
| Line number | Where the problem was found |
| Message | Whether it is a grammar problem, a naming problem and so on |
The compiler may only notice a mistake on the line after the one where something was left out. Here, even if it points at the line with the closing brace, check the print just before it.
Put the ; back at the end, save, and run it again. Fixing the first error can also make the errors after it disappear. Don't try to fix everything at once; start from the first diagnostic.
| Symptom | What to do first |
|---|---|
mana cannot be found |
Check the short name set up on the setup page |
hello.mn cannot be found |
Check where it is saved, the working folder and the extension |
| Compilation fails | Check the file and line in the diagnostic, and the line just before it |
| An error occurs while running | Read the runtime message. Some problems are not prevented just because compilation succeeded |
| No error, but the result is wrong | Check that you saved, then add print calls partway through to see which parts ran |
| The program does not finish | Press Ctrl+C in the terminal to stop it, and check things like the exit condition of a loop |
When you ask for help, include the command you ran, the code, the full diagnostics and the result you expected. That makes the situation easy to understand.
For everyday learning, mana hello.mn is enough. If you want to compile and run separately, use the following.
Command that compiles and saves:
mana hello.mn -o hello.mx
-o is the option that sets the output file. Here it creates hello.mx and does not run it.
Command that runs the saved result:
mana --execute hello.mx
Changing the source does not change a hello.mx you made earlier. Compile again to include your changes. All options are listed in the CLI reference.
Next, Actor and Action splits the work into roles.