berto -> AGEpp -- MUST READS & README (11/20/2012 7:16:00 PM)
Here are some must-read docs for installing and making best use of AGEpp:
Here, for your coding pleasure, is AGEpp.
What is AGEpp? AGEpp is akin to a common programmer's tool, the code beautifier, or "pretty printer". (See http://en.wikipedia.org/wiki/Pretty_printer.) AGEpp is a tool to reformat poorly laid out, confusing, hard to read AGE event scripting code.
(Standard disclaimer: I offer no judgment about AGEOD, or its games. Nothing asserted, nothing implied. AGEpp is a tool, not a weapon. We use it to build better games, not to tear down any company or anybody. Please let's keep our discussions positive and constructive, shall we?)
In the spirit of empowering modders, and bettering the gaming experience, I give you AGEpp.
Modders of the world unite! You have nothing to lose but your confusion!
In order to install and run AGEpp, you will need to use (a) Linux (or some other suitable Unix-like OS, such as FreeBSD); and/or (b) Cygwin for Windows (or some other Unix-like environment for Windows).
AGEpp, at least as currently constituted, is firmly rooted in Unix/Linux. (Note: after this, I will mostly cease referring to Unix/Linux, Cygwin, and qualifying the terms. Henceforth, I will mostly just use "Linux". You should take that to mean Linux, but also any of the alternative compatible host environments. I will only qualify as necessary.)
I make no apologies for that. AGEpp works on the vast amounts of AGEOD game text file data. And Linux, in countless ways, is a superior OS to Windows for raw data processing. (If you doubt that, just consider this one fact: Most of the world's financial exchanges are now Linux-based. But also: Linux is at the heart of many well known cutting edge technology companies, such as Google. And if not Linux, one form or another of Unix. Windows is okay as a consumer and gaming OS, but for back-end production work, Unix/Linux is king.)
To install and run AGEpp, it's easiest simply to do it on Linux, with AGEOD game installations to process copied to your Linux filesystem (using rsync or scp/WinSCP over the network, for example), else installed on a USB stick (the method I preferred).
If you are not prepared to run this in Linux, there is at least one Windows-based Unix environment alternative -- Cygwin for Windows. See
From the Cygwin home page:
* a collection of tools which provide a Linux look and feel environment for Windows.
* a DLL (cygwin1.dll) which acts as a Linux API layer providing substantial Linux API functionality.
Cygwin is not:
* a way to run native Linux apps on Windows. You must rebuild your application from source if you want it to run on Windows.
* a way to magically make native Windows apps aware of UNIX® functionality like signals, ptys, etc. Again, you need to build your apps from source if you want to take advantage of Cygwin functionality.
I have installed and used Cygwin for Windows over the years on multiple Windows systems. It is easy to install. It's a nice way to get your feet wet with Unix, short of diving right into Unix/Linux.
If you are handy with Linux, indeed if you are "just" a Windows power user, installing Cygwin is not that hard. It's certainly no harder than (following the "official" AGEOD modding procedure):
--installing the AGE CSV splitter
--editing the "official" AGEOD DB/.xls files
--saving those files as .csv files
--running those saved .csv files through the CSV splitter
--placing the resulting game data files in their appropriate folders
--running the AGEOD game in special edit mode
--saving the game
I will have nothing more to say about the "difficulty" of installing/running Linux/Cygwin. You decide how far your comfort zone extends.
For installing AGEpp itself, please see the INSTALL_AGEPP file.
Turning away from my AGElint project for a while, and with the intent to begin modding, I begin to read the game Event files -- this time, not with an eye for syntax, but rather for *meaning*. I find the Event script layout to be confusing, hard to read. It
has inconsistent line spacing
has inconsistent indentation
runs together in one continuous stream, doesn't clearly demarcate independent sections of code
has gratuitous NULL lines
is littered with duplicate, redundant SelectFaction & SelectRegion statements
suffers from other deficiencies
that detract from the clarity and that obscure logic and meaning.
It seems to me that the mangled formatting in the default event scripting code is the result of (a) problems in the source DB (.xls) files, (b) CSV Splitter quirks, and (c) careless human text file edits.
I don't know about you, but being the visual thinker that I am, I really need to reformat, beautify, "pretty print" the "ugly" event scripting code.
applies consistent line spacing
applies consistent indentation
demarcates events and other code sections with horizontal rules
removes gratuitous, pointless NULL lines (while retaining legitimate comments)
combines and consolidates SelectFaction & SelectRegion statements
that, in their totality, make AGE event script code easier to read and understand.
Please refer to the distribution USAGE file to see how, using AGEpp, we accomplish that.
Refer to the INSTALL_AGEPP file for instructions on how to install AGEpp on your Windows (or Linux) PC. See the INSTALL_CYGWIN file, if you intend to run this in Windows.
Like AGElint, AGEpp is yet one more example of thinking outside the box. Indeed, for modding, the text file paradigm can be quite liberating.
At present, AGEpp only reformats event scripting code -- the Events/*.sct and Includes/*.inc files (and perhaps also the Scripts/*.ini files). We can tweak it, add more bells and whistles, and apply it to other AGE game data files in future as needed.
I would think that for anybody, easier to read and comprehend Events etc. files will lead to (a) fewer mistakes and (b) faster coding.
Good luck, and happy pretty printing!