CMA:DevelopmentSetup

Development setup

This site focuses on getting your work ingame, as well as all aspects of addon,
pbos as a subset, development.

Motivation

• Correct setup to use binarize to track down errors and improve the quality.
• Best addon design for easy recognition, updating and quality.
• Dev setup to work with least time and resource effort.

Related topics

• Minimal Addons Setup
• PBO naming thoughts
• Good design - separate an addon in multiple PBOs
• Formatted A2 configs and all-in-one config as part of the CMB git repository.

Unpacking A1/A2

Motivation

For non simple addons you have references to BI configs, textures or proxies.
More specially the BI namespace CA.
Binarze is trying to locate these references during the optimization process.
In other words without these files available binarize is unable to do its job properly.

The models referenced by other models or wrp files can be both MLOD or ODOL format.

Process

Virtual partition P

We will create a virtual partition P: to map your arma folder.
This is required by the BI toolset and allows easy access to the arma folder.
It is recommended to create a link on your desktop or quicklaunch bar to P.

As a sidenote, at the same time you should create one central folder with
all your arma related tools in it. Map this one to T.

Are two arma installations necessary

The BI tools create by default a separate folder/location called ArmAWork.
This may or may not be needed.

Considerations:

• Two separate folder/locations to keep your play-install clean.
• Duplication of files may be needed for two separate.
  Possible to avoid with Junctions, if both are on the same HDD.
• Both play and dev combined in one folder avoids messing around.
  You only need to keep your folder structure well designed.
  You can ensure that only PBOs, and NO unpacked data, are loaded via

-noFilePatching

Done via ArmA: Startup Parameters.

Create P drive

1. Create a file called mapGameFolderToP.bat.
2. Add the line and adapt the path your arma folder:

subst p: "D:\Games\arma"

3. Move the file to the autostart location. IE (XP32b):

C:\Documents and Settings\YourUserAccount\Start Menu\Programs\Startup
or 
C:\Documents and Settings\All Users\Start Menu\Programs\Startup

Extract files from the PBOs

There are several PBO tools out there to do the job.
Personally I recommend you ExtractPbo.exe made by mikero
as part of the PBOdll suite.

.\ExtractPbo.exe -a -d -y .\pathToArmA\arma\addons\PboFileName.pbo

Do this for each PBO in .\arma\addons and all PBOs in .\arma\dta.

Move the files in the appropriate place:

Result

The folders of the unpacked PBOs should be moved to .\arma to look like:

.\arma\ca\config.cpp
.\arma\ca\ca\*
.\arma\ca\a10\*
...

For the dta PBOs:

.\arma\bin
.\arma\core
...

Addon development

Use namespaces

In OFP the engine rebuild the file-folder structure in the memory from the
folder naming of the addons: .\ofp\addons\MyAddon.pbo
Results in the path in the memory: MyAddon\*.

A1/A2 support the namespace or also called (pbo)prefix.
It is not required to use it, yet it is BAD practice not to use it!
The namespace is defined in a file called $PBOPREFIX$.
The $PBOPREFIX$ site directly in your addons location: .\myAddon\$PBOPREFIX$.
The $PBOPREFIX$ is basically a text file with no file extension.

It allows you to name your pbo independent from the future in memory structure:

PBO location and name: .\arma\myMod\addons\myTag_PboName_2009_06_02.pbo
$PBOPREFIX$: x\myMod\addons\myPboName

Create a PBOPREFIX file

1. New file -> text file.
2. Rename to $PBOPREFIX$. No file extension!

  Make sure your windows OS displays all file extensions.

3. Open the $PBOPREFIX$ with your favorite text editor.
4. Add your namespace:

myMod\myAddon

Or better (see more info below):

x\myMod\addons\myAddon

5. No newline, no space before or after the namespace!
6. Save the file.
7. Move the $PBOPREFIX$ file to the root of your addon: .\myAddon\$PBOPREFIX$.
NOT in a subfolder of your addon!

Benefits

• Different pbo to memory naming (the later is the namespace).
• Use version/date tag for the pbo and have same inner namespace without it for every release.
• Define your own home via the prefix: myMod\.. instead of just myAddon,
  or worse to use the BI CA namespace - NEVER do this!
• Avoid addon (model/texture/sound) path conflicts with your own namespace.

In addition it allows you to utilize it for a few design and development tricks:

Develop with unpacked data

Note that the system also works for non development, yet it is not recommended.

Binarized files loaded faster and give better performance.
PBOs are needed to have the verifySignatures system work.

Benefits

Let's start with the benefits this time:

• No need to pack PBOs (more details to follow).
• No need to repack the PBO for newly created files.
  In other words also the ability to add new files during runtime (no configs though!).
• Flat PBOs (small). Only $PBOPREFIX$ is needed inside.
• Work only with unpacked data. Readable, always possible to modify
  (expect configs), modifications available live or via mission restart.
• Nicely manageable system to decide which addons are active in your dev setup:
  • Have both PBO and unpacked data to have the unpacked data loaded.
  • Delete the PBO to have it disabled.
  • Create PBO again to have the unpacked data loaded.
• If you have both your dev env combined with binarize env, you can easily
  

binarize your addons during dev to see, if that works or check the log
for errors.

In short:

1. You work with the unpacked data.
2. You create a PBO to have it active.
3. You binarize it in the same setup to get the log and to have it available
   optimized once (the current version/release is) complete.
4. You can ensure that only PBOs, and NO unpacked data, are loaded via

-noFilePatching

Done via ArmA: Startup Parameters.

Mikero provides an excellent pbo and rapify toolset to make the handling very enjoyable.

Basics

The key to understand that if you have $PBOPREFIX$ defined, the engine looks
for the data unpacked in the same place:

$PBOPREFIX$ contains: x\myMod\addons\myPboName
The engine looks at .\arma\x\myMod\addons\myPboName for the data.

If it finds data there, it will replace all data in the namespace,
x\myMod\addons\myPboName here, with the unpacked data found at the path.

Setup

1. You are recommended to use a subfolder with one char for your dev env.
x is easy to type.

2. You are very much advised to use your ofpec tag as namespace in the next level.

3. To be able to have both PBO and unpacked data in the same folder,
to have the string addons as 3rd folder level.

4. Finally PBO name is the last folder level.
Keep the PBO naming thoughts and Good design - separate an addon in multiple PBOs topics in mind.

Considerations

• You can have the PBO and unpacked data in the same directory.
  This makes it easier to delete the PBO if needed.
  At the same time it can become messy with lots of PBOs in one folder.

A1 to A2 difference

While this wasn't tested extensively, in A2 a PBO only needs the $PBOPREFIX$
inside the PBO, while A1 still needed all the same files in pbo as in
unpacked data.

In other words in A1 you had to repack the PBO each time you have added
a new file. A2 an empty PBO but the correct $PBOPREFIX$ is enough.