PMC Editing Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== ArmA Build Environment ======

**ArmA Build Environment – Setup & Usage** by Synide, May 31st, 2008.

The following stuff may or may not be correct, true or even accurate... take it or leave it... it's just some words... if you don't like it, well... there are 500 billion other words out there on the internet... I'm sure you can find some you do like...


====== Background ======

The ArmA game product provided by BIS is made of essentially two parts.

  * The Engine
  * The Game content.

The "Engine" is BIS's Real Virtuality game engine.

The "Game content" is what is commonly referred to as a Modification or MOD for short.

Yes, that's right the standard game content shipped with ArmA is "Just another MOD" as far as the game Engine is concerned.

When the game is started the engine looks for some basic information in a config.cpp located in the \bin folder. Where is the \bin folder? It's in the bin.pbo sitting in the \Dta folder in your ArmAInstallationFolder.

Next, the game Engine goes looking for Addons to load content. Addons, are single .pbo files. The default place the Engine looks for these addons is in the \AddOns subfolder in your ArmAInstallationFolder.

Try this for a laugh. Take your current ArmA installation and find the \AddOns folder. Move the folder using Windows Explorer out of the ArmAInstallationFolder. Move it one level up in the folder hierarchy on your hard drive so you can easily move it back again in a minute or two.

Now, start the ArmA game but making sure you have no –mod= command line parameters specified.

You should get something like the picture in Figure 1.0. Although, you won't get much further than this because there is no content. Now, shutdown the game and make sure you move the \AddOns folder back to where it belongs.

{{ http://tactical.nekromantix.com/images/wiki/Synide_DevSetup-01.jpg }}

Figure 1.0 – Vanilla ArmA with "No Addons".

This illustrates that all the .pbo's in the \AddOns folder are just another MOD. At the time of writing this document there are currently no known "full conversion" MOD's around. So, most commonly MOD's for ArmA either, inherit, enhance, override or add to the BIS default content.

The BIS default content inhabits a virtual folder prefix called "ca". There is speculation this prefix stands for "combined arms" but it doesn't really make any difference.

Personally, I prefer to think of this BIS virtual folder prefix as a Namespace.
A namespace in programming terms helps to organize code and declare scope. It also, provides a mechanism for creating globally unique types or in terms of BIS's game engine globally unique classes.

Also, people that want to make modifications for ArmA should make themselves aware of some common programming principals such as inheritance & overriding.


====== The <Armawork> Folder ======

I won't go into detail about running through the BIS tools installation setup. It is a pretty painless process.

You can find the links to the latest ArmA Tools Suite through the Biki or through the ArmA Editing News forum.

However, I would suggest you do the following prior to running the BIS tools installation.

1. Make a folder somewhere on your computer called "ArmAWork".

This folder can live anywhere however you should place it somewhere where there is going to be literally 10's of Gigabytes of free space.

For instance I have a physical hard drive partition called the O:\ drive and I created a sub folder in the root called "ArmAWork".

2. Extract the pbo's in the <ArmAInstallationFolder>\AddOns folder. I have extracted all of them. However, you may only want to extract some of them.

3. Move the <ArmAInstallationFolder>\AddOns\Ca folder extracted to the <ArmAWork> folder you created in step 1. Rename the <ArmAWork>\Ca to lowercase "ca". This is not necessary but it's a personal preference thing.

4. Move each of the remaining folders you extracted in the game installation and place them inside the <ArmAWork>\ca folder you move in step 3.

5. Now, run the BIS Tools Suite installation package. And, when asked point the installation at the <ArmAWork> folder you created in step 1, and just moved gigabytes of data into.

When the BIS Tools Suite installation has completed you should have a new "virtual hard drive" on your computer called P:\ (By default). Although, you can have it as another drive letter and this is explained in the Installation information.

This P:\ drive should now be populated with the necessary basic tools setup, which also would have overwritten some of the content you previously copied across from the extraction process of the game data. This is ok.

6. Acquire the 3 (currently) BIS released sample development/source model packages from the Biki or through the ArmA Editing News forum.

The 3 files you are looking for are...

  * ARMA_SampleVehiclesWeapons.zip (110 Megabytes approx.)
  * ARMA_SampleCharactersAnimals.zip (67 Megabytes approx.)
  * ARMA_SampleModelsEnvironmentOther.zip (60 Megabytes approx.)

Also, acquire the BIS Sample Map through the same locations.

The file you are looking for is...

  * BISampleMap.zip (31 Megabytes approx.)

7. Extract the contents of the ARMA_SampleCharactersAnimals.zip to somewhere on your computer.

Inside the extracted folder you will find 4 subfolders called...

animals, Anims, characters & voice

These folders contain P3DM MLOD versions of the BIS standard game content. And, more importantly, they contain the config.cpp, include files and model.cfg text files used when building the content.

8. Move all 4 folders mentioned in step 7 to the <ArmAWork>/ca folder. You will get a warning from Windows Explorer that you are about to overwrite various files. You should proceed with this. That is, you should say "Yes" to overwriting the files.

9. Extract the contents of the ARMA_SampleModelsEnvironmentOther.zip to somewhere on your computer. Inside the extracted folder you will find a listing of 26 files and folders.

10. Move all 26 files & folders mentioned in step 9 to the <ArmAWork>/ca folder. You will get a warning from Windows Explorer that you are about to overwrite various files. You should proceed with this. That is, you should say "Yes" to overwriting the files.

11. Do the thing in the above steps for the ARMA_SampleVehiclesWeapons.zip. Moving & overwriting the extracted data to the <ArmAWork>/ca folder.

12. Locate the BISampleMap.zip file you downloaded in step 6 and extract it. Find the "SampleMap" subfolder. It should have 2 subfolders called "Data" & "Source" and contain 3 files called config.cpp, SampleMap.hpp & SampleMap.wrp.

13. Grab the SampleMap folder and move it to your <ArmAWork>/ca folder.


====== Tools Configuration ======

There are essentially 3 components to the tools suite.

  * O2PE – Oxygen 2 Personal Edition
  * V3 – Visitor 3 Personal Edition
  * Build Tools – BinPBO and its subordinate tools binarize, cfgconvert etc.

Each of these 3 tool groups needs to be able to "see" content that you may reference in your work and build process.

**O2PE**

It is necessary to configure (at the very minimum) 3 settings in O2PE for the application to function.

1. Where to find the viewer and what additional parameters to pass it.

2. Where the DLL folder is for O2PE.

3. The location of the <ArmAWork> folder.

{{ http://tactical.nekromantix.com/images/wiki/Synide_DevSetup-02.jpg }}

Figure 2.0 – O2PE Settings.

You will note that the **–addons=** parameter is specified. Defining this parameter for the Buldozer viewer when run from O2PE is not particularly critical. Although, it is desirable to be consistent with the 2 other tools suite components.

**V3**

Visitor3 requires similar settings to O2PE. The critical thing is that you should make sure your V3 is launching Buldozer with the **–addons=** command line parameter.

**Build Tools/binPBO**

While there are no specific settings that you have to set to use the BinPBO tool there are settings you need to configure each time you build a different .pbo.

These "pbo specific" settings are critical to building your Addon into a working .pbo. And, as such I have dedicated a section to this later in this document.

The settings in question must be implemented in conjunction with a specific folder setup to do with Namespace. This again is discussed in a following section.

For the moment however, it is advisable to start BinPBO and go to the options tab. At the top of the options dialog is a field called "Files to Copy Directly". It is a listing of wildcard filenames that BinPBO will include within your pbo when it finally packs it using the filebank.exe program.

You should add *.rvmat (at the very least) to the list of files. And then close BinPBO. Other people will indicate to you some more file types to add, but this one is particularly relevant.


====== Your Namespace ======

This area of setting up your development environment is quite subjective. Many people successfully have differing setups to me and what I am about to go over is just my way of doing it. My naming conventions may not fit with your way of thinking about things.

Firstly, we should note that the BIS Mod's namespace is "ca". And, it resides in the root folder of your <ArmAWork> folder.

Secondly there is a BIS supported community convention whereby a MOD team or Addon maker registers a short "tag" principally for denoting addons are created by that given person or MOD.

This initiative is not mandatory or a requirement in any shape or form. Although it has its merits and usefulness for some aspects I prefer to have my own subtly different naming convention. This is I believe entirely my prerogative.

You may develop your own naming convention or subscribe in the most part to the community initiatives. It's entirely up to you.

My "tag" registered at OFPEC is SYN. If I was to adhere to the community naming convention I should create a folder on my <ArmAWork> drive called "SYN".

However, I don't... so I have called my "Namespace" Synide. So, my <ArmAWork> drive looks like...

P:\Synide

This then is my Namespace. Like BIS's namespace is "ca".

When I build .pbo's I want them to end up looking like "synBuildings.pbo", or "synRahmadi.pbo" so this is the way I create my subfolders under P:\Synide.

E.g. P:\Synide\synBuildings, P:\Synide\synRahmadi, P:\Synide\synBodies etc. Etc.

If you adhere strictly to the community initiative naming convention then you one would create a folder on the P:\ drive called "SYN". E.g. P:\SYN

And, subsequently name ones subfolders within this namespace like P:\SYN\SYNBuildings or P:\SYN\SYN_Buildings.

Again, it's all subjective and entirely up to you.

Also, you should try to group models and or functionality logically together into subfolders.

For instance, if you plan to create 50 building models you would be best to group these models together into a <YourNamespace>Buildings.pbo.

Or, perhaps you plan on making 50 African type buildings, 50 Tumurid Architectural buildings and 50 25th Century science fiction type buildings and 5 WWI Aircraft. For ease of management one should probably call the subfolders something like...

P:\Synide\synAfricanBuildings, P:\Synide\synTumuridBuildings, P:\Synide\synUnrealBuildings and P:\Synide\synWW1Aircraft

Which, would eventually end up in an \Addons folder as...

synAfricanBuildings.pbo

synTumuridBuildings.pbo

synUnrealBuildings.pbo

synWW1Aircraft.pbo

This aspect of your folder setup and preferred naming convention is entirely up to you. But, I should stress that you should find something you are comfortable with and BE CONSISTENT.


====== CPP's & CFG's ======

A .cfg file describes to the build tools the skeleton, bones & in some cases animations for a model.

A .cpp file describes to the engine at runtime what the model is and what properties it has.

Currently BIS's tool and the engine look for config.cpp/bin files. I would really like it if they altered this slightly so as to have the same naming ability for the file as the model.cfg's can have.

You should make it a habit to name your model.cfg files after the name of the folder in which they live. You can have them named after each and every model. But, I see this as a pointless exercise and a lot harder to keep track of.

E.g. synBodies.cfg, synVehicles.cfg

You should use inheritance in your .cfg's and your .cpp's. Keep them as clean as possible. Do not make it a habit to just cut and paste .cpp & .cfg definitions willy-nilly. It is bad form and will not only confuse you but also confuse others.

Inheriting from BIS Content

1. Make a "ca" folder in the root folder of your "Namespace".

E.g. P:\Synide\ca

2. Inside this folder make subfolders for each of the subfolders in the main BIS "ca" namespace that you intend to inherit from.

E.g. P:\Synide\ca\buildings, P:\Synide\ca\characters, P:\Synide\ca\air etc.

3. From the P:\ca folder on your <ArmAWork> drive where you overwrote/installed the BIS Example p3dm mlods find the config.bin, model.cfg files and copy them to the appropriate folder in your namespace.

E.g. P:\ca\config.bin & P:\ca\model.cfg – copy them to P:\<YourNamespace>\ca\

P:\ca\buildings\config.bin & P:\ca\buildings\model.cfg – copy them to P:\ <YourNamespace>\ca\buildings\

**Note:** You only want the config.bin & the model.cfg, not all the rest of the content.

4. Go into each of the subfolders in P:\<YourNamespace>\ca\... and extract the config.bin file into a config.cpp text file format with community tools or the BIS tool cfgconvert.exe


====== Building From Your Namespace ======

When you run BinPBO and you and making use of the above detailed folder structure and have included in your namespace the reference config.cpp & model.cfg files from the main P:\ca namespace you should use the following BinPBO settings. Or, in your case the appropriate equivalents.

{{ http://tactical.nekromantix.com/images/wiki/Synide_DevSetup-03.jpg }}

Figure 2.0 –BinPBO Settings


{{ http://tactical.nekromantix.com/images/wiki/Synide_DevSetup-04.jpg }}

Figure 3.0 –BinPBO Settings

Now, a little explanation as to what's happening here will help you understand the process involved when running BinPBO like this and with the above mentioned folder setups.

If we are building P:\Synide\synRahmadi folder into a pbo the Namespace prefix you must have inside the pbo is "Synide\synRahmadi". Now, in the above example you can get BinPBO to use this prefix by simply ticking the "Addon Prefix" Automatically checkbox. The resulting pbo created will have a "prefix" based on its current folder hierarchy.

Which in this case is P:\Synide\synRahmadi. So all is good, this is what we were aiming for.

But, then why do I have it specified instead of letting BinPBO do it automatically. For 2 reasons. 1, when done automatically BinPBO makes the prefix all lowercase. But, I want it Uppercase and Lowercase. This is a preference thing and is not an absolute requirement. 2. In the future, prefix's may become case sensitive, who knows, but it's always a good to plan ahead... :)

The main reason this feature is in BinPBO is so that technically you can have this subfolder sitting under P:\work\synRahmadi and still build it into the Namespace prefix of Synide\synRahmadi.

There is just one problem when doing this however. When BinPBO runs it passes the necessary information to binarize.exe to build your .p3d or .wrp into a binarized version. If you are referencing other models in other namespaces (e.g. ca\buildings, when processing a .wrp) then binarize needs to be able to have access to the definitions for those reference models etc.

If you build P:\work\synRahmadi and it needs the P:\ca\buildings\majak.p3d AND the model.cfg & config.cpp information for that model it will not have access to them.

Instead if you build P:\Synide\synRahmadi using the above settings then binarize.exe can look in P\Synide\synRahmadi folder for model.cfg & config.cpp information AND can go up one level to P:\Synide to find information as well. Now, because binarize.exe is going up one level it by default parses ALL subfolders as well... looking for config.cpp & model.cfg information.

Now, because we have the model.cfg & config.cpp's from the main P:\ca\ reference folder inside P:\Synide\ca\ binarize.exe now has access to all the correct definitions it needs to successfully build your synRahmadi folder.

Now, I should point out that probably the most critical part of all to get things working properly is the text you write in your config.cpp's and model.cfg's.

Most, people place far, far too much stuff in there config's. That is, they tell the game engine a certain property on a model has a value of "x". When, the class that model inherits from already has this property set to the same value.

You do not need to tell it yet again. Use inheritance. Don't worry though, all of us are guilty of doing it at one time or another.

Also, many community members have suggested that it is sometimes beneficial to all concerned that the config's for models & islands be kept in separate smaller AddOns of their own. So, as to facilitate easier integration with and troubleshooting AddOns. Sometimes I do this, and sometimes I don't... depends on the situation. Again, it's all up to your preferences.


====== Ca Or Not To Ca? ======

Don't do it.... Don't do it... don't make your addons inside the P:\ca namespace... just take my advice... don't do it!

If someone tells it's ok... well technically it is... but still, just don't do it... I've been mucking around with config's for a lot of years and there is no reason you need to build your stuff out of this folder.

This is BIS's Namespace... make your own frik'n Namespace...!

You can have your folders inside the P:\ca\. For instance P:\ca\synBuildings with a "Path to Project" setting of P:\ca.

And you could specify a pbo prefix of "Synide\synBuildings".

And, BinPBO would build a synBuildings.pbo over to C:\Games\ArmA\Synide\Addons\synBuildings.pbo.

This is ok. BUT, when I come to build P:\ca\synRahmadi and I want to place a building on the island from synBuildings. This reference building should be sitting in P:\Synide\synBuildings... not in P:\ca\synBuildings.

So, it's much, much easier if you build outside of the P:\ca folder in your own namespace.

E.g.

I have P:\Synide\synBuildings\BigHouse.p3d

The config.cpp for synBuildings specifies that BigHouse inherits from BIS's definition class called "House".

When I BinPBO synBuildings it goes up one level and processes all config's in all subfolders under P:\Synide.

So, it correctly finds the reference to class House from BIS's config because there are all the config's and model.cfg's sitting in a subfolder called P:\Synide\ca\...

I have P:\Synide\synRahmadi\synRahmadi.pew open in Visitor3. I place a building from synBuildings folder called "BigHouse" AND I place a building from P:\ca\buildings called "Majak2.p3d".

Now, I build synRahmadi folder. BinPBO & binarize process the P:\Synide\synRahmadi folder AND because I have "Path to Project" set to P:\Synide it processes all the subfolders... one of which is \synBuildings\ and another is \ca\.

The P:\Synide\ca\ folder contains ALL the config's and model.cfg's (and only them) from the MAIN reference folder.

So, your island gets built with all correct references. But, ONLY if the config.cpp for P:\Synide\synRahmadi is WELL WRITTEN!

Please, note that all folder names are entirely up to you and what you want for naming conventions.

Hopefully that's all as clear as mud... good luck!

Cheers, Synide.


( ILLUSTRATION MISSING DUE PROBLEMS EXTRACTING IT FROM PDF FILE! )

**BinPBO**

  * Input: P:\Synide\synRahmadi
  * PathToProject: P:\Synide
  * Prefix: Synide\synRahmadi

Results to ->

  * Output: <ArmAInstall>\<Namespace>\Addons\synRahmadi.pbo
  * Prefix: <Namespace>\synRahmadi

Down to -> 

P:\Synide\synRahmadi + all subfolders

Down to ->

P:\Synide + all subfolders

Down to -> 

P:\Synide\ca + all subfolders

P:\Synide\synBuildings + all subfolders

P:\Synide\etc...

An Illustration

If you place config.cpp & model.cfg files as reference in the P:\<Namespace>\ca\ folder structure so that BinPBO can reference the definitions correctly you will go a long way to successfully building your Mod/Addon.


====== Notes ======

This development environment setup by Synide was posted here with this permissions. Thank you Synide for your continued support for ArmA community.
PMC Editing Wiki

User Tools

Site Tools

Page Tools
