mizflow

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.

Usage

Create a DCS mission project

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), 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
• JetBrains WebStorm or IntelliJ IDEA (commercial, with free trials)
• Vim or Neovim (for advanced users)
• Cursor (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:

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 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:

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).
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:

• Right-click the script file in the Explorer and select Copy Relative Path.
• By default, VSCode uses backslashes (\) on Windows.
  To always use forward slashes (/), open Settings (Ctrl+,), search for explorer.copyRelativePathSeparator, and set it to / (forward).
• 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:

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:

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.

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

• Make a copy of debugger.sample.lua and save it as debugger.lua in your project.
• Edit the copied file according to your requirements. You can remove the sections that you don't need.
• Launch your mission in DCS and open the communications menu in-game.
• 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.

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.

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.