Project Perfect Mod Forums
:: Home :: Get Hosted :: PPM FAQ :: Forum FAQ :: Privacy Policy :: Search :: Memberlist :: Usergroups :: Register :: Profile :: Log in to check your private messages :: Log in ::

The time now is Wed Apr 24, 2024 7:29 pm
All times are UTC + 0
G-E's RA2 INI Scripts Mega-Pack for March 2023
Moderators: Community Tools Developpers
Post new topic   Reply to topic Page 1 of 1 [1 Post] Mark the topic unread ::  View previous topic :: View next topic
Author Message
Defense Minister

Joined: 09 Feb 2015

PostPosted: Thu Mar 09, 2023 3:33 am    Post subject:  G-E's RA2 INI Scripts Mega-Pack for March 2023 Reply with quote  Mark this post and the followings unread

G-E's Combined RA2 ini scripts pack README

This pack contains:
- AICHECK 8.1f
- AICLEAN 5.8c

EACH SCRIPT WILL HAVE TO BE EDITED! That is every *.tcl in the package must undergo at
least some configuration, to set the basic parameters like RA2 directory, to run with
your installation, and crucially any mods. In some cases, additional .cfg files will
need to be customized for purpose, such as the one that comes with AICLEAN, to get
the best results.

NONE OF THE SCRIPTS READ THE MIX FILES! Every referenced ini file used by a script,
must be extracted for parsing first, then those filenames and locations need to be
specified in the header of 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. However, being
as each script has its own internal settings for filenames and paths, this means you can
make copies of the script, with modified copies of the batchfiles pointing to them. In
this way, you could have a set of scripts working with RA2, and a duplicate set working
with YR in the same place. The scripts that have an external configuration file could
share it, if there's no particular incompatibility with goals, but can also be cloned.

Every script comes with one or more batchfiles to run them, the batchfiles will be
specified in their own document section below. In a few cases

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. For SOUNDCHECK, sound.ini must also be present, but audio.idx should
also be extracted for it to be more thorough, that file is located within audio.mix,
which is located within language.mix, not ra2.mix.

relevant code should be merged back into their parent files for proper parsing. As a
rule, Ares features are not supported; there are no current plans to support include,
nor the distributed nature of the lists it allows with undenominated additions. A
future version of AICLEAN might have the option to merge all the include files into
the original file arrangement, but as of now, it doesn't support the feature either.

Ares and CNCNet 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
within the script header. As long as they use proper ASCII safe filenames and paths,
all the scripts should be able to access them as well. When using any of the helpful
batchfiles for scripts that scan multiple maps in one go, such as for MAPCLEAN, simply
update or make copies of the batchfiles, with the correct file mask for your client.

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 you configure each script to the file paths and ini
filenames within the scripts, 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 directory
where the game/mod itself resides.

These scripts are the result of on-going sporadic efforts, and have evolved as RA2/YR
modding itself has evolved. Any support for Ares, Phobos, Kratos, or anything similar
is off the table, as each of them seem to be a moving target in terms of what's right
or wrong. Plus I'm not sure how reasonable it is to break up the script into blocks
that only operate when specific extensions are available/active. It seems best to use
Ares' own internal debugger function in such case, or at least to catch everything
outside the scope of Westwood's programming.

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 documentation.

AICHECK 8.x Reference Notes:

Input: rules.ini, art.ini, ai.ini
Optional input: maps
Output: check.log

AICHECK is the primary tool for analyzing the various critical gameini 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 sourceini, 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:
- 100 unit bug: having buildable units past the 100th index (Ares fixes this)
- 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
- name collisions between disparate objects, excluding TerrainTypes and OverlayTypes
- orphaned/disabled code from TS, and in some cases deprecated development code in YR

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/RequiresStolenTech
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. Recentl updates
have added warnings for unused weapons, but this has been expanded to check for unused
warheads as well, including within particles.

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
Optional output: rules.ini, art.ini, translated.log, backup files (timestamped)

AICLEAN is the second most complicated script in the bundle, in the process of cleaning
theini 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 before releasing a mod publicly.

AICLEAN is compatible with current versions of AIEdit.

To execute normally:
> aiclean.bat

There are 3 batchfiles included to execute common filemasks:
> aiclean-mpr.bat -- inspect all RA2 (*.mpr) maps as configured
> aiclean-yrm.bat -- inspect all YR (*.yrm) maps as configured
> aiclean-map.bat -- inspect all mission (*.map) maps as configured

SOUNDCHECK 3.x Reference Notes:

Input: rules.ini, art.ini, sound.ini
Optional input: audio.idx
Output: checksnd.log

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 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 coreini 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. Assuming audio.idx is readable, SOUNDCHECK will report
any waves that are present in audio.bag without a corresponding sound object using them.
The script will also report duplicated usage of wave files within a sound object too.

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_something", sounds objects with
the _Amb_* prefix are ignored for the purposes of checking for unused sounds, but their
code and referenced wave files will be checked as normal.

To execute:
> soundcheck.bat

SOUNDCLEAN 1.x Reference Notes:

Input: sound.ini
Output: sound(NEW).ini

SOUNDCLEAN is one of those scripts you will likely only use once as a modder, although there
could be reasons to reorganize the sound.ini contents which could require another execution.
Its main function is to replace the index numbers of the [SoundList] section with a newly
generated sequential number starting at 0. This means it will remove commented out entries,
and the associated numerical gaps they create.

As the cleaning process ignores the index, moving large blocks of the SoundList entries above
or below each other to keep their names or application grouped will not adversely affect the
operation. No manual indexing is required, simply move the entries around with their existing
index numbers, and re-run the script.

SOUNCLEAN also has the secondary functions of removing unwanted comments, with 3 options for
retaining comments, as well as removing unreferenced/unindexed sound objects. In this way, the
script operates similar to AICLEAN, but focusing on unnecessary sound.ini content only.

Since this is a drastic reorganization of the sound tables, saved games will likely break,
and there could be side effects regarding mission scripting. Because of the risks involved,
there is no option to overwrite the existing ini, and a new ini will be generated alongside it
for comparison.

The latest update adds an alphabetical sorting option the sound object list, this makes it a
little easier to search the list in FA2, when adding a sound effect to a trigger. Also as an
extension to this list re-ordering, SOUNDCLEAN can now re-write the entire sound.ini in an
order matching those lists!

To execute:
> soundclean.bat

MAPCLEAN 3.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.

Recent updates have added support for an external configuration, as well as the ability to
specify the filename of the configuration, should you wish to have parallel copies that
follow different rules, or for use on different kinds of maps. The latter will be of use if
you plan to clean both singleplayer and multiplayer maps, you probably don't want generic
rules applicable to skirmish maps to apply to a mission equally.

Within the configuration, a [Modify] section was included, whereby almost any of the existing
code can be modified tag by tag. The format is simple, it allows existing tags to be changed,
and new tags to be added to known existing sections. If the heading doesn't exist for what
tags you are adding, the script will automatically create them. In short, you can change the
Image= value for specified units if you have some winterized voxel units, or you can affect
the gameplay by disallowing the creation of certain buildings via TechLevel, such as naval
units and naval yards on land-locked maps.

Even more advanced uses are possible for making missions, a whole host of ScriptTypes and
TaskForces can be added in one step, which can then speed up mission editing as a whole.
Currently the script will not re-index any of the lists within the map, but to guarantee you
won't have any line index collisions, do what Westwood did, and use really large numbers that
FA2 would never reach.

Note some sections are parsed as critical objects, and written as-is to the output map file
without further processing, meaning not all sections can be modified via the configuration.
The rules for matching and modifying is done after the commmon compressed terrain data, any
previews or headers that may be present, and any map scripting code that could never be
generalized enough to modify with an automated script like this one. There are a number of
map sections that are placed at the beginning as necessary, and a fair number of sections
typically used in mission maps will be sorted into topical groups, before any of the many
possible sections that aren't critical to have anywhere specifically are added. This should
improve readability for those advanced modders who wish to edit or debug a map manually
via text editor.

Noteworthy readable sections that are off-limits for such modification:
> Header, Map, CellTags, VariableNames, Waypoints, Actions, Events, Triggers, Tags

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-n-DROP maps onto:
> mapclean.bat

MAPKILL 1.x Reference Notes:

Input: multiple maps
Output: file deleting or renaming

MAPKILL exists for automating the eliminating maps with YR-only theaters, and/or any map
that can be presumed damaged because of missing [Header] section. This is a rather niche
script in that it's primary use is to weed out large numbers of maps from map packs, which
would be incompatible with the original RA2, or RA2-only mods.

The included batchfile is already preset to use the hotmask of *.yrm but could be edited to
use *.map for example. It doesn't much concern itself with multiplayer vs mission maps, the
theaters LUNAR and DESERT are the issue, and the MAPKILL will delete them.

Because MAPKILL only reads maps, both the mapkill.tcl and batchfile can be copied to wherever
the maps are and run there. There are also coincidentally no settings, as none of the game's
ini files need to be loaded to operate.

In 1.1 the maps without a valid [Header] section are now renamed instead of deleted. This
change was made to save survival maps or replacement missions, that still comply with RA2
theaters, but could still be interesting maps for modification.

To execute:
> mapkill-yrm.bat


 Filename:  G-E's_RA2_ini_scripts_03082023.rar
 Filesize:  44.34 KB
 Downloaded:  44 Time(s)


Back to top
View user's profile Send private message
Display posts from previous:   
Post new topic   Reply to topic Page 1 of 1 [1 Post] Mark the topic unread ::  View previous topic :: View next topic
Share on TwitterShare on FacebookShare on Google+Share on DiggShare on RedditShare on PInterestShare on Del.icio.usShare on Stumble Upon
Quick Reply

If you are visually impaired or cannot otherwise answer the challenges below please contact the Administrator for help.

Write only two of the following words separated by a sharp: Brotherhood, unity, peace! 

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

[ Time: 0.1720s ][ Queries: 13 (0.0085s) ][ Debug on ]