mizflow/README.md

DCS mission dynamic script injection and distribution tool

# MizFlow

DCS mission dynamic script injection and distribution tool

## One time setup
To run MizFlow commands it is necesary to have `NodeJS` already installed in your computer.

`NodeJS` is a very popular tool that helps computers run JavaScript outside of a web browser.

Most people know JavaScript as the language that powers websites — it helps pages respond when you click buttons or fill out forms.\
Normally, JavaScript runs inside your web browser (like Chrome or Firefox). \
But with Node.js, we can use JavaScript on its own, outside the browser, to build all kinds of software — especially things that run in the background like servers and automation tools.

Download NodeJS [here](https://nodejs.org/en).

## Usage

### Create a DCS mission project

```bash
npm create mizflow <project-name>
```
This command will create a DCS mission folder along all necessary files.

>💡 The mission in this project will be already initialized, so it won't be necessary to run the MizFlow `init` command.

### Open Your Project with an IDE

After creating your DCS mission project, it's highly recommended to open the project folder with a code editor or IDE (Integrated Development Environment). This will make it much easier to edit Lua scripts, manage your project files, and work with configuration files.

The most popular choice is [Visual Studio Code (VSCode)](https://code.visualstudio.com/), which is free and available for Windows, macOS, and Linux. VSCode offers:

- Syntax highlighting and autocompletion for Lua, JavaScript, and other languages
- Integrated terminal for running MizFlow commands
- Extensions for Git, formatting, and more

Other good editor options include:

- [Sublime Text](https://www.sublimetext.com/)
- [JetBrains WebStorm](https://www.jetbrains.com/webstorm/) or [IntelliJ IDEA](https://www.jetbrains.com/idea/) (commercial, with free trials)
- [Vim](https://www.vim.org/) or [Neovim](https://neovim.io/) (for advanced users)
- [Cursor](https://www.cursor.so/) (AI-powered, based on VSCode)

>💡 **Tip:** In VSCode or Cursor, you can open your project by right-clicking the folder and selecting "Open with Code" or "Open with Cursor", or by running `code .` or `cursor .` in your project directory if you have their command line tools installed.


### Initialize your DCS mission project

You can create a new mission from scratch if the miz file doesn't exist. Run this command:
```bash
npx mizflow init
```

This command also creates some internal configuration in the DCS mission file, including the working directory.
>⚠️ **Important:** If you move your project to a different location, you MUST run this command again.

Alternatively, you can place your existing mission file in your project and name it `mission.miz`, then run this command to inject the MizFlow script.  
If you prefer to keep your mission file's original name, you can do so. Just update your [`missionFilePath`](#configuration-file) configuration to match your mission's filename.


## Link your external lua scripts from DCS Mission Editor

Open your project's `mission.miz` file using the `DCS Mission Editor`.

### Actions

Create a `Do Script` action in the Mission Editor with the following content:

```lua
run("path/to/script.lua")
-- Example: run('_triggers/mizflow-example/do_something.lua')
```

By default, the base directory of the specified path will be the `scripts` directory of your project (see your [`scriptsDir`](#configuration-file) configuration).\
The content of these linked scripts will be updated in the mission if you edit them.

>⚠️ **Important:** Use forward slashes (`/`) in script paths, as backslashes (`\`) are escape characters in `Lua` and will cause issues in your mission.

>💡 **VSCode Tip:**  
> To quickly link a Lua script in the Mission Editor, you can copy its relative path in VSCode:
> 1. Right-click the script file in the Explorer and select `Copy Relative Path`.
> 2. By default, VSCode uses backslashes (`\`) on Windows. \
To always use forward slashes (`/`), open `Settings` (`Ctrl+,`), search for `explorer.copyRelativePathSeparator`, and set it to `/` (forward).
> 3. Remove the `scripts/` prefix from the pasted path before using it in your `run("...")` call. 

### Conditions

For a condition, create a `Lua Predicate` condition in the Mission Editor with the following content:

```lua
return run("path/to/script.lua")
-- Example: return run('_triggers/mizflow-example/cond_always.lua')
```
>⚠️ **Important:** For conditions, remember to use the `return` keyword in the Lua Predicate action 
and also in the referenced script code to properly return the condition result to `DCS`.


## Lua scripts naming convention

To quickly find the script you want to edit, you can name the lua scripts following this convention:

```bash
scripts/
    _triggers/                                # The "_" prefix is used to keep this folder on top, 
                                              #   since it will be edited very frequently
        trigger-name/
            cond_condition-1.lua              # use "cond_" prefix for representing a condition
            cond_condition-2.lua
            do_action-1.lua                   # use "do_" prefix for representing an action
            do_action-2.lua
    blue/                                     # groups of blue coalition
        airplane/                             # airplane groups
            airplane-1/                       # group name
                task_triggered-action-1.lua   # use "task_" prefix for representing a triggered action, 
                                              #   the rest of the filename is the triggered action name
                task_triggered-action-2.lua
                w01/                          # "w01" stands for waypoint 1, but you can use the number just to sort the waypoints
                    waypoint-action-1/        # waypoint action name
                        cond.lua              # condition to start the waypoint action
                        cond_stop.lua         # condition to stop the waypoint action
                        do.lua                # code to run as the waypoint action
                    waypoint-action-2/        # waypoint action name
                        cond.lua              # condition to start the waypoint action
                        do.lua                # code to run as the waypoint action
                w02/
                    waypoint-action-3/
                        do.lua
        ground/                               # ground groups (follow the same structure as the airplane groups)
        helicopter/                           # helicopter groups (follow the same structure as the airplane groups)
        naval/                                # naval groups (follow the same structure as the airplane groups)
    neutral/                                  # groups of neutral coalition (follow the same structure as the blue coalition)
    red/                                      # groups of red coalition (follow the same structure as the blue coalition)
```

But remember, this is only a **convention**, you can place your scripts under the `/scripts` directory as you wish. 

## Distribute your mission

Once you are happy with your mission, you can inject all external scripts you've been working on.

Run this command, and a packaged mission will be created in the `/dist` directory of your project.
```bash
npx mizflow dist
```
A distribution version of your mission will be created in the `/dist` directory of your project.

This version will have all your external scripts included. The MizFlow script and the debugger functions will be removed from it.

You can share this version, it will work for **everyone**.

## Debugger

The debugger allows you to inspect and manipulate flag values in your mission while it's running, as well as run custom macros for testing and debugging.

### How to use the debugger

1. Make a copy of `debugger.sample.lua` and save it as `debugger.lua` in your project.
2. Edit the copied file according to your requirements. **You can remove the sections that you don't need.**
3. Launch your mission in DCS and open the communications menu in-game.
4. Go to `F10. Other...` and select `Debugger...`.

You will see options to inspect and modify the flags you listed, assign preset values, increment/decrement by defined steps, and run any macros you have added.

```lua
return {
    -- flag names you want to watch or change during your mission
    flags = {
        "FLAG_A",
        "FLAG_B",
    },
    flagAssignments = {
        -- preset values you can assign to each flag from the debugger menu (other than just 0 or 1)
        values = { 50, 100 },
        -- step amounts for incrementing or decrementing the flag value (other than just 0 or 1)
        -- each step will be available in the debugger menu as both positive and negative
        steps = { 10, 20 },
    },
    -- lua functions to run from the debugger menu, this feature allows advanced control over the mission by running custom code
    macros = {
        ["your macro title"] = function()
            -- type your lua code here
        end
    }
}
```

>💡**Tip:** You can edit the `debugger.lua` file while the mission is running. To reload the debugger configuration and see updated options and values, select `F10. Other...` > `Debugger...` > `Reload Config` in the menu.

## Configuration file

You can customize all paths and filenames used by MizFlow if you edit the `mizflow-config.lua` file.

Do not delete this file. It must exist to letting the configuration values to be read from the DCS mission editor.

```lua
return {
    missionFilePath = "mission.miz",        -- mission file path
    scriptsDir = "scripts",                 -- scripts directory
    debuggerFilePath = "debugger.lua",      -- debugger file path
    cacheDir = ".mizflow",                  -- cache directory
    distributionDir = "dist",               -- distribution directory
    distributionFileName = "mission.miz"    -- distribution file name
}
```

>⚠️ **Note:** if you edit this configuration and you are using `Git` (you should 😉), make sure your `.gitignore` file includes your `cache` and `distribution` directories.