ArmA 3 Co-op Mission Frameworkby
Ladies and gentlemen, Armaholics of all ages, I am proud to present a work over a year in the making: Zenophon's ArmA 3 Co-op Mission Framework. My framework is a library of over 220 SQF functions and 80 macros organized into a carefully designed API that is both easy to use and extremely powerful. The functions cover everything from manipulating arrays to an extensive task system. Each one has been meticulously designed and tested to provide useful features with minimal bugs and issues. The framework is designed so that each function is a logical building block that achieves a straightforward effect. The strength of the framework is that each small part fits together neatly with others, allowing you to quickly implement your mission design intuitively.
The framework works with any map and requires no addons. It is compatible with any mod because you choose which functions execute. There is effectively no performance impact to compile the entire framework, and every function has been diligently optimized. All 180 public functions are also carefully documented in an exacting style, and many resources are provided to help you learn to use the framework. The framework is created with these goals in mind:
Simple co-op fun for both players and mission makers
Bottom-up design using flexible pieces that you control
Truly random and dynamic missions without extra work for mission designers
Procedural mission design instead of manual placement using the editor
Eliminating large, static functions with assumptions about what you want in your mission
Server-oriented execution to create more efficient multiplayer missions
A simplification of locality and interacting with clients in multiplayer
A solid, powerful, and bug-free library to use as a foundation for your own code
The framework's many functions are divided into 13 categories with a specific purpose:
The Data functions are the foundation of the framework, supporting both simple and complex operations on arrays and strings.
The Fire Support system is a tool for mission makers, not players, to create any imaginable artillery, mortar, or airstrike.
The Loadout functions, including a full custom loadout system, provide every option you need to easily equip both players and AI.
The Math functions are auxiliary functions that deal with various 2D trigonometric operations on positions and polygons.
The Misc functions are just that, miscellaneous. They don't fit in anywhere else, but are still useful.
The Object functions deal with objects, and provide numerous ways to check on and interact with players, AI, and static objects.
The Objective system is designed to make side missions extremely simple for mission makers with just one line of code.
The Orders functions provide a tested and working way to make AI do things, and some offer simple but powerful randomization.
The Position functions generate and check random positions, allowing infinite randomization within your control.
The Preprocessor library offers both general and framework-specific macros that improve ease of use for many small tasks.
The Spawning functions allow you to spawn any object, AI or static, that you need and offer both straightforward and randomized spawning.
The Task system is a complex system are meant to separate the mission maker completely from the issues of tasks, making any task operation simple.
The Trigger functions perform operations on tasks based on preset conditions and are designed to complement the Task system.
Installation / Usage:
The framework must be installed separately for every mission that uses it. It is easiest to install the framework first before creating your mission. See FrameworkIntroduction.txt for details. This process is also covered in the tutorials.
1: Start ArmA, open the editor, create a new (blank) mission on any map, save it with any name
2: Navigate to (Windows 7) C:\Users\<userName>\My Documents\Arma 3 - Other Profiles\<profileName>\missions
3: Open the directory with your mission name
4: From the sample mission, Shell.Stratis, copy Zen_FrameworkFunctions, Init.sqf, and Description.ext into your mission directory
a. If you already have a mission with an Init.sqf or Description.ext:
b. Open each file in Shell.Stratis and copy ALL of the code to the TOP of your corresponding file
c. Do not place the Zen_FrameworkDocumentation folder in your mission folder.
5: Go back to the editor, save (ctrl+s) your mission
6: Continue to create your mission, coding what you want in the init.sqf, (fullscreen windowed mode is recommended for alt-tabbing)
What to do first:
If you are not sure what you have just downloaded, take a look at FrameworkIntroduction.txt to see what the framework is all about.
Even if you know what you want, I suggest reading FrameworkIntroduction.txt and FAQ.txt soon. FrameworkIntroduction.txt is the full version of the abridged text used for the framework's forum thread. Before you begin making missions on your own with the framework, I advise reading HowToDebug.txt, HowToUseDocumentation.txt, and KnownIssues.txt. You can also see the readme specific to each subfolder for more about its contents. If you want to just dive in, here are some suggestions based upon relative experience level.
For all experience levels, I have packaged some sample missions I have made. These are full missions you can export and play in singleplayer or multiplayer, but you might just want to preview them in the editor to see the code in action. Even if you don't understand all the code, these missions contain various common techniques I use repeatedly to make missions. The piece-wise design of framework functions means that doing certain common actions in a mission follow a simple, logical pattern that is easy to remember.
If you have little to no experience with the sqf scripting and the editor, I strongly advise that you start with the first tutorial. Open the Zen_Tutorials folder and read the readme file there. You probably have a slight advantage in that you don't have any misconceptions about sqf.
If you have experience with the editor but little with sqf, I strongly advise that you start with first tutorial. The tutorials assume you do not know the editor, but they focus almost exclusively on using the framework. Using the framework is a lot different from the editor, and I hope that you will see that the framework is a better way to create missions. Once you get the hang of coding missions using the framework, it gets easier to put together more functions.
For those doing the tutorials, after about the fifth tutorial, you should know enough to look at some of the easier demonstration missions. At this point you can feel free to switch between demonstration and tutorials, or start making simple missions of your own.
If you have intermediate experience with sqf (or know a real programming language), feel free to skim through the tutorials and see what is done. Each tutorial becomes increasingly complex, and each one offers a 'technical corner' that is more advanced. I suggest that you look at the code in later tutorials to see what the framework can do at an intermediate level. Also, I suggest you read some or all of the demonstration missions (Zen_Demontrations folder). Some might seem too easy or too hard, but they will help you get more out of using the framework. If you are serious about learning sqf, invest some time practicing and studying example code (you can look at framework source code too). You don't need to be a professional programmer (I'm not) to be really good with sqf.
Finally, if you are an advanced scripter (hundreds of hours coding complex functions and systems and/or professional programmer in real life), you probably already know what you want out of a function library. I suggest looking through the index and documentation files for functions that interest you. Also, see the demonstration missions for some common ways to use framework functions and an explanation of some framework data structures. You are free to look through all the source code for the framework and edit it for your personal use (be sure to update the documentation too). However, please read the Legal.txt file and understand what is said there.
Credits & Thanks:
I want to thank everyone who has used and supported the framework.
In addition to the terms of the Legal.txt file (please read), the framework is also released under the Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International (CC BY-NC-ND 4.0) license.
Fixed: Framework preprocessor library prevents repeated definition
Fixed: Zen_FindCenterPosition caused an error if given an empty array
Fixed: Zen_UpdateControl would not update Map control type
Improved: Zen_RefreshDialog accuracy of detected changes
Improved: Zen_RefreshDialog causes less flickering
Improved: Zen_RefreshDialog restores the currently selected list item
Improved: Zen_SpawnVehicleCrew uses the crew classname defined by the vehicle's config if possible
Added: Zen_CreateControl properties Event, MapPosition, MapZoom, and Transparency
Added: Zen_RefreshDialog parameter for control change time
Added: Zen_CreateControl type StructuredText
Added: Zen_InvokeDialog parameter to prevent Esc key exits
Documentation: Improved Zen_SpawnInfantry
Documentation: Updated for Zen_InvokeDialog, Zen_RefreshDialog
Documentation: Updated Notepad++ SQF language and autocompletion file with ArmA 1.68 stable commands
New Function: Zen_SubdivideMarker
Fixed: Zen_OrderAircraftPatrol, Zen_OrderBoatPatrol, Zen_OrderInfantryPatrol, and Zen_OrderVehiclePatrol now interpret their arguments correctly
Fixed: Zen_InvokeDialog caused an error when attempting to show a list with no elements
Fixed: Zen_OrderInfantryPatrol did not generate waypoints correctly for groups within the minimum radius
Added: Zen_InvokeDialog parameter to allow user input to control their character while the dialog is open
Added: Zen_InvokeDialog parameter to move the center of the dialog
Added: Framework macro ZEN_FMW_Code_GetRemoteVar
Added: Zen_CreateControl type Map
Documentation: Fixed ZEN_FMW_MP_REClient, Zen_GiveLoadoutCustom and Zen_StringGenerateRandom Notepad++ hints
Documentation: Added for ZEN_FMW_Code_GetRemoteVar, Zen_SubdivideMarker
Documentation: Updated for Zen_CreateControl, Zen_InvokeDialog
Documentation: Updated Notepad++ SQF language and autocompletion file with ArmA 1.66 stable commands
Fixed: Zen_FindCenterPosition did not remove itself from the stack trace when exiting on special cases of arguments
Fixed: Zen_FindInRange rounded numbers were not equally distributed at the edge
Fixed: Zen_MoveAsSet caused an error by including markers in its height calculations
Fixed: Zen_SpawnInfantry rarely spawned the maximum number of units
Fixed: Zen_SpawnInfantryGarrison argument checking did not allow a nested array for the skill parameter
Added: Zen_ExecuteCommand command for enableFatigue
Added: Zen_ExtendVector parameter for cylindrical vector
Added: Zen_SetAISkill preset for 'player' skill
Added: Zen_SpawnInfantry and Zen_SpawnInfantryGarrison parameter for Gaussian distribution of random unit number
Added: Zen_TrackGroups, Zen_TrackInfantry, and Zen_TrackVehicles parameter for marker update time interval
Improved: Zen_CreateTemplate, Zen_FindGroundPosition, Zen_GetAmbientClutterCount, Zen_IsForestArea, Zen_IsUrbanArea, and Zen_OrderInfantryPatrolBuilding optimized
Improved: Zen_FindAveragePosition averages the Z coordinate
Improved: Zen_FindTerrainGradient finds the 3D gradient
Improved: Zen_ExtendPosition renamed Zen_ExtendVector
Improved: Zen_OrderInfantryPatrol sets the behavior of groups chasing the enemy to combat
Improved: Zen_OrderInfantryPatrol orders the AI to return to their normal patrol pattern when they lose contact with the enemy
Tweaked: Zen_SpawnInfantry allows the AI to flee
Tweaked: Zen_TrackGroups and Zen_TrackInfantry start from 1 when using number text
Documentation: Added Dialog System demonstration
Documentation: Removed for Zen_FindTerrainSlope
Documentation: Corrected for Zen_RotateAsSet
Documentation: Improved for Zen_ExecuteCommand
Documentation: Improved AI Caching demonstration
Documentation: Updated for Zen_FindAveragePosition, Zen_FindTerrainGradient, Zen_ExtendVector, Zen_SetAISkill, Zen_SpawnInfantry, Zen_SpawnInfantryGarrison, Zen_TrackGroups, Zen_TrackInfantry, and Zen_TrackVehicles
Documentation: Updated Notepad++ SQF language and autocompletion file with ArmA 1.64 stable commands