The time now is Sat Jan 19, 2019 10:53 pm
All times are UTC + 0
Joined: 09 Feb 2015
|Posted: Sun Jun 03, 2018 10:19 pm Post subject:
G-E's RA2 INI scripts Pack for October 2018
|Combined RA2 ini scripts pack README
This pack contains:
- AICHECK 5.6b
- AICLEAN 5.7
- MAPCLEAN 2.2
- SOUNDCHECK 2.2
Each script will have to be edited (the .tcl) to configure the basic parameters to run
with your installation, and crucially any mods. None of the scripts read the .mix files
and thus the relevant .ini files must be extracted for parsing, those files then need to
be specified in the script. In the case of RA2 and YR mod installations in parallel, each
script can only be set to handle one at a time, not both, without reconfiguring. Some
scripts also have an external configuration file which also must be edited.
Every script comes with one or more batchfiles to run them, the batchfiles will be
specified in their own document section below.
For most of the scripts to work, rules.ini, art.ini, ai.ini (or YR equivalents) must be
extracted from the ra2.mix/ra2md.mix even if not modified for the particular mod being
checked/cleaned. In the case of SOUNDCHECK, sound.ini and audio.idx must also be present.
None of the scripts currently support Ares #include function, any external .ini files with
relevant code should be merged back into their parent files for proper parsing. As a rule,
Ares features are not supported; though #include may be supported in the future, there are
no plans for it at the moment.
Ares and custom clients are able to use custom .ini and map filenames, and this practice
is perfectly acceptable to all the included scripts, since each filename is defined in the
script header, they are able to use them as well. If using any of the helpful batchfiles
as a shortcut for processing, such as for MAPCLEAN, simply update those with the correct
file mask. For example, in the case of using AICHECK to scan maps, substitute *.map or
whatever your particular mod map extensions are in the batchfile.
The result of running each script isn't what is seen on screen, that's more to do with
parsing indication, basic errors or conversions are reported purely to get a sense of what
they are doing, and is by no means the important part, rather it is the log file created
that matters. Although the file paths to the .ini files are defined in the script, the
resultant log output will be written where the script is located. For this reason, it is
usually best to extract the scripts to the same directory as the game/mod itself.
These scripts are the result of on-going sporadic efforts, and have evolved as RA2/YR
modding itself has evolved. Any suggestions or code updates are welcome to be submitted
to G-E on ppmforums.com ...
Every script will require ActiveTCL's tclsh runtimes:
Each script has a dedicated notes section below, which should describe in more detail
basic operation, as well as any usage that may not be listed within the script header out
of a desire to keep the header concise, or is an odd use case that rarely comes up.
Now on with the document.
AICHECK 5.x Reference Notes:
Input: rules.ini, art.ini, ai.ini
Optional input: maps
AICHECK is the primary tool for analyzing the various critical game .ini files used by
RA2 and YR, it does not modify the source files in any way, it is strictly for analyzing.
In general AICHECK is the go-to for an active mod developer, after a round of changes or
edits, it is worth doing a quick run to verify nothing was missed, nothing was incorrectly
declared, or in some cases a value was out-of-range.
AICHECK has a number of parsing sections dividing up all objects into major sections, and
then cross-checking to see that a weapon has a valid warhead, a unit has a valid building
prerequisite, and exposing any other such declarations where there may be a problem or
missing objects. It would take a whole volume to describe every test and association the
script completes during its run, but this is the core function of the script. Later other
important functions were added, such as AI processing, primarily because of all the things
that cause a mod to crash in-game, AI is the biggest culprit, and generally the least
understood part of it all.
Yuri's Revenge compatibility has improved over the past year, with more of it's quirks and
changes covered by the code, highlighting deficiencies and mistakes with the common areas
like non-existent weapons or improperly declared objects. There is however 1 caveat that
can't be overcome without a total overhaul of the code, and that is the structure of
aimd.ini being out of order for processing purposes, due to this script being written for
RA2's ai.ini structure. The simple repair for this issue is running AICLEAN with just the
basic settings, translate and cleanrules disabled, as a first pass on aimd.ini to rearrange
the code. Once this has been done, AICHECK will have no issues cross-checking between all
the ini files.
AICHECK also has a function for checking maps, it checks for missing objects outside of
the IsoPack'ed data, which means only overlays are ignored. Buildings, units, trees and so
on are checked against the mod to ensure they exist. When using the map checking function
via batchfile, the error/warning messages for the maps will be added to check.log after all
subsequent normal processing sections. Each map will have its filename written along with
any errors for quick at-a-glance viewing.
Errors and warnings are divided in the ART and AI sections of check.log, with warnings
written after the important messages usually, but in some cases the warnings themselves
will indicate an error exists somewhere, thus it is worth reading it all.
The combined output is organized in check.log by the source .ini, that is RULES, then ART,
then AI. This visual division makes it easier to read, but will have the occasional effect
of seemingly duplicating an error from multiple angles, such as animation is listed as
unused because the referencing warhead is missing. The output is designed to be descriptive
not specifically minimalist. Any and all messages are purely for the mod author to read,
investigate, and subsequently make a decision how to deal with it. There will be many noted
false-positives as some call them, and many errors that can be safely ignored, but again it
is up to the author to opt to fix or ignore the issue, and an author may choose to fix the
majority of irrelevant errors purely for the sake of consistency.
Some common and largely unimportant errors found by AICHECK:
- orphaned/disabled code from TS, and in some cases deprecated development code in YR
- unused objects: objects that exist for use in mission mapping or left for future use
- missing declarations for objects that still function without, like bibs and buildups
- missing art code: many objects don't require art, others don't require settings
- virtual objects or those with hardcoded functions that break normal convention
- house mismatch in AI triggers: unit is forbidden for a house in a generic Taskforce
- passenger/transport size mismatch: valid teams can be made with units that don't all fit
In some cases, objects are added to internal tables by their explicit usage from within
another object, in such case the objects are appended to the tables, and the declaration
becomes irrelevant, but this isn't the rule. In these instances, the obvious question is
whether they should be declared properly, or should this irregularity remain. The author
may decide, along with similar pseudo-errors, that there is no good reason for these
broken or irregular cases to exist, and can opt to fix them in accordance with the usual
One of the more common problems with mods, stemming from Westwood's own typos and mistakes,
is incorrect capitalization of keywords, like "maxdebris" instead of "MaxDebris", and thus
the code doesn't function. The same is true however for object names, in a few instances
an object can be declared with mixed case, and the object called with lower or upper case,
but again, this isn't the ideal, and AICHECK will throw errors for all such instances.
Thoroughly cleaned up, all the reported errors by AICHECK can be entirely eliminated in the
RULES section of the log, and almost all in the ART section can as well. Most likely, due
to the overly strict parsing of AICHECK, not all AI errors can be eliminated, however
almost all can be even with very extensive AI code.
Remember, it is better to know and choose to ignore, than not to know.
As a bonus, AICHECK will also collate RequiredHouses/ForbiddenHouses/RequiresStolen*Tech
options within buildings and units, and can output a neat table of values for quicker
overview of something largely hidden during the normal modding process.
There are 3 batchfiles included to execute:
> aicheck.bat -- the main sanity checking the author should use regularly
> aicheck-mpr.bat -- same as above, but scan all RA2 (*.mpr) maps for incompatibilities
> aicheck-yrm.bat -- same as above, but scan all YR (*.yrm) maps for incompatibilities
AICLEAN 5.x Reference Notes:
Input: rules.ini, ai.ini, aiclean.cfg
Output: ai.ini, clean.log, ai backup (timestamped)
Optional output: rules.ini, translated.log, rules backup (timestamped)
AICLEAN is the second most complicated script in the bundle, in the process of cleaning
the .ini code for publishing (or a desire for neatness) many subtle errors will be caught
that AICHECK might even miss. One such area is the script code, where values or objects are
not enumerated correctly. Another common problem area is line numbering, in rules.ini most
line numbers are handles purely as a unique identifier, and the value itself has no meaning,
but in ai.ini both the number of lines and the line numbers can have significance.
AICLEAN attempts to correct basic mistakes, either created by Westwood, or by the author
to generate a new ai.ini that is minimalist, neatly spaced, and potentially comment free.
More recently, a cleaning function was also added to the RULES parsing section, and can
also generate a cleaned rules.ini for publishing, though the resulting code is not likely
ideal as the development source. In this respect, the cleanrules option could be considered
as unrelated to the core function of cleaning the AI, and as more post-production oriented.
AICLEAN's secondary function after basic parsing and cleaning is the AI translation. If set
to do so, AICLEAN will write a translated.log containing the plain english version of what
all the ScriptTypes are commanding the units to do. This is especially helpful to catch
basic mistakes in building targeting, which are defined by their position in the table
rather than by name, but that enumerated id may have been corrected by enabling cleanrules
and reindex options before processing. So it is easy to see how AICHECK and AICLEAN operate
somewhat in a symbiotic relationship.
Recently a building-sorter and unit-sorter function was added, which attempts to reorganize
the tags/code within their respective objects to be a common topical order where possible.
The code order is defined in aiclean.cfg, and the output is dictated by the order of the
tags listed in each section [Structures] and [Units]. Any tags not listed will be positioned
after all known tags, thus the omission of any valid tags will not create jumbled code. The
sorter configuration can be updated to include Ares specific tags, but keep in mind AICLEAN
does not understand or understand Ares extensions to AI conditions or triggers, nor will it
catch definition type errors that might result from the custom code.
In a disorganized mod, AICLEAN can help prepare rules.ini and ai.ini for editing, as well as
acting as a post-production cleanup script.
* AIEdit compatibility added, no longer removes its section for storing global settings.
SOUNDCHECK 2.x Reference Notes:
Input: rules.ini, art.ini, sound.ini
Optional input: audio.idx
SOUNDCHECK has a singular purpose when it comes to identifying problems, to catch any and
all mistakes or omissions regarding the audio resources and the sound object definition.
The two most common areas of sound related mistakes are made are inconsistent object names,
and missing wave files that were not added to the audio.id/audio.bag as necessary. Fixing
these errors is well beyond the scope of SOUNDCHECK, so no files are modified.
Unlike most mod errors, sound related mistakes don't generally cause crashes, but they can
manifest with weird side effects, like causing unrelated sound glitches, or sound effects
just disappearing after a while of playing. Due to the rather divergent ways of using sound
objects within the game, namely they can be referenced from rules.ini or art.ini, and even
maps themselves, catching these mistakes can often be very time consuming and repetitive
This script aims to solve the problems for the most part by cross-checking all forms of
usage in the core .ini files, but does not check maps, so any errors or invalid sounds used
within a map script will be up to the author to catch, and subsequently correct by hand in
The script will attempt to read audio.idx to figure out which wave files were included and
compare that to all the files referenced by every valid sound object in sound.ini, however
this checking will be automatically disabled if audio.idx can't be read, and all remaining
checks will be performed as usual.
Like other scripts, SOUNDCHECK is very particular about object name capitalization, errors
can result if object names aren't referenced exactly as declared, whether or not this is a
game breaking problem. Consistency should always be a priority when writing code, laziness
is not encouraged.
It is very likely there will be a large number of unused sound objects when complete, even
after thoroughly fixing/updating the mod and specifically sound.ini to remove errors. The
consequence of removing all unused sounds from the index is unknown/untested, and there
seems to be no functional limit to the number of additional sound objects that can be added,
replacing unused sounds rather than removing them can be a safe option.
Note that since ambient sounds used in maps are named [_Amb_xxxxxxxx], sounds objects with
that prefix (_Amb_) are ignored for the purposes of checking for unused sounds, but their
code and referenced wave files will be checked as normal.
MAPCLEAN 2.x Reference Notes:
Input: map, maclean.cfg
Output: maps.log, map, map backup (*.old)
MAPCLEAN exists to scrub maps of irrelevant/unnecessary code added by FinalAlert2, and now
add or replace code as well. Originally the houses and other redundant code was removed from
maps, usually as a first-and-only cleaning pass after completing the map. This shrunk maps
slightly and reduced the chance of duplicate definitions competing to set the same values.
This was expanded to allow removing all known junk sections, which are listed in mapclean.cfg
under the [Remove] section, but can be used on mod-specific maps to quickly and easily scrub
scripts and triggers that may cause problems if desired.
Belatedly, with the external configuration, a [Modify] section was included, whereby almost
any of the existing code can be modified tag by tag. The format is simple, and it allows new
tags to be added to existing sections just as easily as removing those tags from existing
Note some sections are parsed as critical objects, and written as-is to the output map file
without further processing. All matching and modifying is done after this step, and resulting
code changes will be written after the critical sections, but before [Digest].
These are off-limits for such modification:
MAPCLEAN can be run from commandline invoking the interpreter directly:
> tclsh mapclean.tcl map1.mpr [map2.mpr ...]
There are 2 batchfiles included to execute common filemasks:
> mapclean-mpr.bat -- scrub and replace all RA2 (*.mpr) maps as configured
> mapclean-yrm.bat -- scrub and replace all YR (*.yrm) maps as configured
There is also a batchfile included useful to drag-and-drop maps onto:
|| 38.03 KB
|| 23 Time(s)
Last edited by G-E on Sun Oct 07, 2018 1:07 pm; edited 5 times in total
Joined: 28 Jun 2015
Location: It was Damascus.
|Posted: Mon Jun 04, 2018 12:54 am Post subject:
|Completely unrelated, but I'm curious:
What takes longer: writing the descriptions or working on your scripts?
Joined: 09 Feb 2015
Joined: 09 Feb 2015
||You can post new topics in this forum
You can reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
You cannot attach files in this forum
You can download files in this forum
Powered by phpBB © phpBB Group