Gil R.
Posts: 10821
Joined: 4/1/2005
Status: offline
|
I'm about 60% done writing up the modder's guide, and thought I would post it here for questions and feedback, either on the part I've done or other things you might want to do. I should have the full thing ready by the weekend, and want to put it in the first patch, which should be out next week. So I'll post the rest as I get to it.
Here's chunk#1. (Disclaimer: I've not proofread this yet, and therefore reserve the right to have included typos.)
“Brother against Brother” Modding Guide
Introduction to Creating and Modding Scenarios
Creating or modifying “Brother against Brother” is done in two ways: working with specific scenario files, and using the scenario-editor in order to position units. All files that you will need to work with are standard text (.txt) files, though some are tab-delimited. This is even true of the scenario-editor, which makes changes to a specific .txt file, though far more quickly, efficiently and accurately than one could if entering the changes directly into that file manually.
Scenario Files: The Basics
All scenarios are located in individual folders within the SCENARIOS folder, which is easily found inside the main “Brother against Brother” folder. As you can see by looking there, the names of these folders correspond precisely to those of the scenarios in the game’s menu, with two crucial differences: underscore characters take the place of spaces, and each folder ends with an ‘S’ (a capital ‘S’). Scenario folders’ names must follow these two rules, and also cannot be too long. (You will know that a name is too long if, when you load the game, the name appears on the same line as another scenario.)
Inside each scenario folder you will find files with the same generic names:
• AcwPlayers.txt: A file you should ignore. It does not affect the game at all, other than telling it that the USA is Player#1 and CSA is Player#2. (The fact that they are ‘1’ and ‘2’, respectively, is crucial for some of the other files to function.)
• MapTags.txt: This file is used to provide information that is linked to specific hexes on the map. If you type a word or phrase into it and a hex’s X and Y coordinates in the next line then that word or phrase will be superimposed on the map; or, if you do the same thing but begin the text line with an asterisk, you will produce one of those yellow question marks indicating hidden text that WCS has used to provide information about the battlefields.
• OrdersOfBattle.txt: The file devoted to putting all of the units, brigades, divisions, corps and armies into their correct place in the army hierarchy, assigning up to three commanders to each of these, determining all of the statistics, weapon types, etc. for each unit, and scripting the AI. (See below.)
• Positions.txt: The file that uses six columns of numbers to identify every unit on the battlefield and assign it its starting hex, formation and facing. While this file can be changed manually, it is primarily changed by means of the scenario-editor.
• Preview.pcx: This is the graphics file for the small map that appears when selecting one’s scenario, showing the locations of Victory Hexes and the two sides’ forces.
• Scenario.txt: An essential file that serves as a catch-all for basic scenario information, including date, start/stop times, locations of Victory Hexes, weather conditions, and the scenarios’ introductory text. (See below)
• ScenarioCommanders.txt: While every general and officer assigned to a unit or brigade/division/corps/army is named in the OrdersOfBattle.txt file, it is in this file that their ratings are assigned. (See below)
Important: When working with the scenario files, be very careful to use underscores for spaces where appropriate, or the game will not work. (To know where this needs to be done, simply study the files that came with the game.) If you wish to leave yourself a note, put it at the start of a line and use // to get the code to skip to the next line.
Scenario Files: The Big Three (Scenario.txt, OrdersOfBattle.txt, ScenarioCommanders.txt)
The three files that are at the heart of each scenario require detailed explanation of how each column functions. Of the three, Scenario.txt is the easiest to use, since it is a straightforward text file that can be opened, changed, and closed after saving. The other two, however, are tab-delimited, which means that they really should be worked on in a spreadsheet-type format so that the columns line up properly, using Excel, Notepad++, or something similar – so long as it permits opening and saving the file in tab-delimited format. All of the files for “Brother against Brother” were prepared using Excel, which works perfectly, but with one hitch: when saving the file Excel inserts quotation marks throughout, which means that after saving and closing the file it needs to be reopened in a text-file reader – basic Notepad works perfectly for this – and a universal search-replace should be done to erase every quotation mark in the file.
Scenario.txt
Each scenario.txt file is arranged in the same order, which is crucial. And all text that is not made invisible to the code by means of // uses underscores for spaces (which is also crucial). The elements are:
1. A line that says “notEditMode” (see below)
2. The game and scenario name
3. The scenario’s introductory text, which must not exceed the size of the window it appears in, or else a crash will occur.
4. A line with the name of the map files (four PCX files that fit together) and the file produced by the map-editor (with .gbmap as its extension), all of which are in the MAPS folder. There is no reason to change these.
5. The number ‘1’ is used to indicate that the Union is considered “first player” – something that should not be changed.
6. The time when the scenario begins, using the number of minutes from midnight, followed by the time when it ends.
7. The times of sunrise and sunset. (We have not research the precise time for each battle, but these two lines permit a mid-winter battle to be shorter than one fought in the summer.)
8. The date when the scenario begins as well as the next six dates (permitting multi-day battles), in each case providing the date on one line and then the month and day on the next two lines.
9. The list of Victory Hexes, for which each line must provide X-coordinate + <space> Y-coordinate + <space> + Side. For the latter, one uses 0 if a V.H. is USA-only (blue hex), 1 for CSA-only (red hex), and 2 for one that can benefit either side (white hex). It is essential to end this list with ‘0 0 0’ so that the code knows it has reached the end.
10. Hour-by-hour weather, with the hour assigned in the first column (using military time, e.g. 17 for 5:00 p.m.) followed by weather type. If you want for the weather to be normal the whole time just use ‘0 0’ and then there will be nothing but “clear” weather. It is essential to end this section with ‘-1 0’. [Note: I still need to confirm with Eric that all of the weather types listed in the file will work. Also, at the time of release weather type #8, heat, was omitted from the in-file list, but is in use in our July and August battles.]
OrdersOfBattle.txt
This file, which contains all of the forces and commanders present at the battle as well as all of the basic information for the units and the AI scripting, is set up as a tab-delimited text file. However, it is best worked on as an Excel (or similar) spreadsheet, which permits use of color-coding, boldface, different point sizes, etc. to help navigate more quickly among the various columns and rows. What follows is a list of the columns, identified by both their label in the top row of each file and their column letter(s) if the OrdersOfBattle.txt file is loaded into Excel.
1. PosID (A): Every unit or “container” – WCS’s term for brigades, divisions, corps and armies, as these contain subordinate containers and units – has a sequential i.d. number, which is used in the Positions.txt file and by the code itself.
2. child (B): Shows the hierarchy of containment: the largest “container” for each side normally an army, will always be ‘0’ and then any other container (e.g., a corps) or unit attached to it will be ‘1’. The highest number one will ever use will be ‘4’, for a regiment or other unit inside a brigade (3), division (2), corps (1) and army (0). (Note: It is possible for one side to have co-equal and independent 0-level containers. This was the case for the CSA at Wilson’s Creek, where neither McCulloch commanded the Western Army but not Price’s Missouri State Guard, and vice versa.)
3. playerID (C): Use ‘1’ for USA and ‘2’ for CSA.
4. ContainerUnitName (D): This is where the full name of every “container” and unit goes. Be sure to use <underscore> instead of <space>.
5. Truncated Name (E): Provides the option of using an alternative, abbreviated name (e.g., “1st Vt.” for “1st Vermont Infantry.” If not using a cell just leave an ‘x’ there and the code will default to the name in Column D.
6. ContainerUnitType (F): Every “container” and unit must be identified by type for the code to handle it properly, and this is done by means of assigning it one of the following abbreviations: AM, CORPS, DIV, BDE, CAVBDE, ARTBDE (all containers), and REG, INFCOY, CAV, CAVCOY, HRSART, ARTBAT (all units).
7. IsHQ (G): For “containers” to be commanded their commander must be assigned a small “staff and escort” cavalry unit. To distinguish these from regular cavalry regiments a ‘1’ is entered in this column. (Note that the commanders themselves are named in the army/corps/division/brigade’s row, not the Headquarters unit’s row. As can be seen by studying each HQ’s unit’s row, they function like other units, needing to be assigned arrival times, strength, etc., and also having a “child” level in Column B that indicates attachment to their “container.” They do not need to have AI scripting, however, as the code has special routines that will ensure that HQ units go where their subordinate units go.)
8. BrigadeCommand (H): This column, which should only be used for a brigade’s rows, is used to assign each brigade’s Brigade Order at the beginning of a scenario. These are the B.O.’s and the number to use: No brigade command (-1), March (0), Rally (1), Hold (2), Fighting withdrawal (3), Advance (4), Attack (5), Mass charge (6).
9. Red / Green / Blue (I, J, K): These three columns assign the color-coding used to indicate the hierarchies, both in the order of battle that is found on the left side of the screen and the circles and squares beneath the individual units. Colors, which are indicated using the basic RGB system with values of 0-255, should only be assigned to armies, corps, divisions and brigades – not units.
10. Officer1number (L): For the unique number of the general or officer commanding the “container” or unit. (See ScenarioCommanders.txt section.)
11. Officer1name / Officer1FirstName (M, N): Two columns for that officer’s name, with the first being last-first-middle and the second for presenting the name more properly. It is this second column that shows up on the screen. Be sure to use <underscore> instead of <space>.
12. Officer1rank (O): Assigns that officer his rank: GEN, MG, BG, COL, LTC, MAJ, CAPT, LT.
13. Officer2number / Officer2name / Officer2FirstName / Officer2rank (P, Q, R, S): Same as Columns L-O, but for the subordinate officer (normally of a regiment or other unit, but some “containers” have a secondary officer listed). These subordinates do not have a role in the game unless Officer1 is killed or severely wounded (or promoted to brigade command), in which case they take over, or unless their unit is split, in which case the second-in-command takes over.
14. Officer3number / Officer3name / Officer3FirstName / Officer3rank (T, U, V, W): Same as Columns P-S, other than that this third officer plays no role whatsoever unless the first or second is incapacitated (or promoted out of the unit). Note that if a unit is not to have a second or third officer these columns should each have ‘0’; if, however, there should be an officer but his name is unknown then use ‘0’ for the number and name columns, but assign him a rank.
15. CompaniesNumber (X): For infantry and cavalry regiments indicates the number of companies present, while for infantry and cavalry companies as well as artillery batteries indicates that the unit is company-sized. For infantry and cavalry regiments this figure also indicates the number of abstracted junior officers (normally captains).
16. MaxCaptains (Y): This column is used for mid-battle scenarios to let the code know that it should calculate how many junior officers remain to an infantry or cavalry regiment that has seen action: by replacing the ‘0’ with ‘1’ such a calculation will be made, using the ratio of current strength to starting strength to estimate how many officers have been killed or incapacitated. (Since infantry and cavalry companies as well as artillery batteries are already at company size their junior officers, normally two lieutenants serving under a captain, are represented among the unit’s three officers, and thus this function does not apply to such small units.)
17. StrengthCurrent (Z): Indicates a unit’s strength at the start of the scenario. (This figure should be the same as Column AA or AB if a scenario is set at the beginning of the battle.)
18. StrengthStarting (AA): Indicates a unit’s strength at the start of the battle.
19. StrengthStarting(Estimated) (AB): When accurate numbers for units’ strength are unavailable – a very common phenomenon – an estimated strength can be provided using this column. (One should choose between assigning unit strength via Column AA or AB, rather than using both.)
20. HistoricalCasualties (AC): This column is intended only for scenario design and is ignored by the code: when creating mid-battle scenarios, which requires estimating how many casualties a unit has already suffered, it is much easier to have its total casualties right there beside Columns Z-AB.
21. Encamped (AD): If a unit should begin a scenario in “encamped” mode a ‘1’ should be used, while if set to “guard” mode a ‘2’ is used. (The column is named “Encamped” rather than the more accurate “EncampedGuard” because “guard” mode was added at a later point in development.)
22. UnencampMinute (AE): Uses the number of minutes past midnight (e.g. 420 = 7:00 a.m.) to set the time for when a unit in “encamped” or “guard” mode is activated.
23. ArrivalDay / ArrivalMonth / ArrivalYear (AF, AG, AH): Sets the date of a unit’s appearance in a scenario – superfluous information in battles fought on a single day, but essential for multi-day battles.
24. ArrivalHour / Arrival Minute (AI, AJ): Uses military time (e.g., 13 = 1:00 p.m.) to set the hour, and 0/20/40 to set the minute.
25. Quality (AK): Assigns a unit’s quality at the start of a battle.
26. Morale (AL): Assigns a unit’s current morale level (which at the start of a battle will be equal to its quality, whereas for mid-battle scenarios it will normally be lower for a unit that has been engaged in fighting). Note that it is possible to assign a morale level higher than a unit’s quality, if one wishes to have a unit begin a scenario especially eager to fight and confident of success.
27. Fresh (AM): If a unit should start a scenario “fresh” replace the ‘0’ with a ‘1’.
28. FatigueLevel (AN): If a unit should start a scenario “fatigued” replace the ‘0’ with a ‘1’.
29. FatigueProne (AO): If a unit should start a scenario not fatigued but on the verge of fatigue – perhaps from heavy fighting, a forced march, etc. – replace the ‘0’ with a ‘1’.
< Message edited by Gil R. -- 4/23/2015 7:36:53 PM >
|
Printable Version
Modder's Guide draft - 
New Messages
No New Messages
Hot Topic w/ New Messages
Hot Topic w/o New Messages
Locked w/ New Messages
Locked w/o New Messages
Post New Thread