Modding

From Spring:1944 Wiki
Revision as of 17:58, 29 March 2012 by Koshi (talk | contribs) (Importing text file)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Modding Spring: 1944 can be quite simple -- as long as you aren't looking to modify the engine itself. While the Spring engine is, of course, completely open source, it is being developed seperately from Spring: 1944 and any desire to modify or develop it should go through the Spring engine community.

However, if you want to mod Spring: 1944 -- add new units, change existing units, modify values of various sorts -- then this section of the wiki might help.

The first thing you'll probably want to do is open up one of the game files in the \mods\ folder of your Spring install. The .sdz and .sd7 files can be opened up with programs such as WinRAR and 7-Zip.

Inside you will find a folder heirarchy containing all of the essential files needed for the game.

Mutator

"Mutator" is a term used to describe a seperate mod file that modifies, or mutates, an original set of game files as well as depend on it to run, rather than require the entire set of base game files. For instance, if you wanted to mod Spring: 1944 by changing the armour value of the Tiger, you could either copy and paste the entire base file contents into a new package with the modifications, or simply have a mutator containing only the relevant changed files. Mutators do not change the contents of the original files, it simply creates an alternate path to overwrite certain files under a new mod.

It is very easy to make a mutator; in the modinfo.lua file contained in your root mod directory, add the line: depend = {"S44Pre-M_v170.sd7"},

This will make that mod file dependant on the Pre-M v170 version of Spring: 1944.

Give your new mod a new name; when you start a game, you can select either the unmodified original, or your new mutator.

Basics

Let's assume all you want to do is add a new unit. Units require a set of files in several directories:

  1. A UnitDef file in the \units\ folder;
  2. A Script file in the \scripts\ folder;
  3. An .S3O model in the \objects3d\ folder;
  4. A Corpse file in the \features\corpses\ folder;

In order to have your unit buildable somewhere, you'll have to modify the builddefs.lua file in the \gamedata\ folder as well; copy and paste the entire file into your new mutator mod and make the modifications there -- your mutated builddefs.lua will overwrite Spring: 1944's and your new unit will be added to the buildmenu you specify. You'll want to do the same with armordefs.lua; this table keeps track of what type of armour class your unit falls under, be it infantry, a medium tank, or an airplane.

UnitDef

Every unit in the game has it's own UnitDef file. This file contains a myriad of entries that determine a myriad of the aspects of your unit, such as its name, costs, speed, what weapons it has, what unit sounds it makes, what categories it's in, and so on and so forth. For now, you can simply look at any of the unitdefs contained in Spring: 1944 to see what this looks like, as you'll likely be copy-pasting and modifying an existing unitdef to create your new unit with.

Naming Conventions

As you'll see in the unitdef files, there are several instances where a unit's name will be used. Our naming convention has always been a three-letter uppercase abbreviation of the unit's faction followed by the unit's name in normalcase -- for instance, GERTiger, USM4A376Sherman, or RUSIS2. This is the unit's "file name" and should be identical in all of your files -- the scripts, the unitdef and the .S3O file should all be the same as whatever the unitname=; entry is. The "name=" line denotes the unit's ingame name (the GBRCromwell's is "name=A27M Cromwell Mk IV", for instance).

Unit Cost

As you'll see in all units' unitdefs, buildcost and buildtime are identical numbers. While it would seem easier to simply have one entry to determine this, that is a distinction of the engine itself, which we have little part in the development of.

It should be noted that in Spring: 1944 a great deal of the effects of the cost of a unit has to do with where it is built or procured, as the Yard in which a unit is built determines how much of a resource drain you get when building the unit. Units built in the Vehicle Yard for instance usually drain -50 Command Points per second, while units build in the Tank Yard drain from -75 to -100. So plan accordingly.

Category

Category is a definition used mainly to classify each unit in order to determine how other units and weapons interact with it. For instance, in the GBRCromwell unitdef file the category line reads MINETRIGGER HARDVEH. MINETRIGGER obviously denotes that this unit triggers mines, while HARDVEH (Hard Vehicle) denotes that the unit is a fully-enclosed armoured vehicle (as opposed to, say, an M8 Greyhound, which is open-topped and not fully enclosed and therefore has the OPENVEH category).

Further on in the unitdef you will see the "badTargetCategory=" entry. Anything listed in this category will be ignored by this unit. Most units have the "FLAG" entry, and so will not attack flags.

The weapon entries in each unitdef also define what those weapons can and can not fire at. This is done in the unitdef file instead of the weaponfile for various reasons, but most importantly because while several vehicles may share the same base weapon, they may be designed or limited to firing at different types of units. For instance, the copula-mounted AA machinegun on many tanks is the basic machinegun weapon but will only fire at aircraft.

As we see in the Cromwell, the QF75mmHE is set, through the onlyTargetCategory1 (1 denoting that this line is for Weapon1; for Weapon2 it would be onlyTargetCategory2, and so on) line, to fire only at BUILDING INFANTRY SOFTVEH OPENVEH HARDVEH SHIP LARGESHIP DEPLOYED category units. Any unit in any other category (that is, lacking any of these category tags) will not be shot at by this weapon.

Weapons

The weapons a unit has are also defined in the unitdef file (but the weapons themselves have seperate def files in the \weapons\ folder). The Cromwell, for instance, has the QF75mmHE, QF75mmAP (different ammo types for the same weapon), Bren, .50calproof, and Small_Tracer weapons. The .50calproof and Small_Tracer weapons aren't actual weapons that the unit actively uses; .50calproof is actually a shield (which in the Spring engine uses the weapon system) that, as its name suggests, will deflect .50 cal bullets and below, while Small_Tracer is actually a placeholder SFX weapon that fires tracer rounds with the tank's machineguns.

As stated, a weapon's def file can be found in the \weapons\ folder of the root directory. Weapon defs, like unitdefs, contain information that control the behaviour of each weapon, such as its velocity, how much damage it does, and so forth. HE weapons are fairly straightforward -- they're just various sizes of explosions. AP weapons however are a little more complex and have several customparams such as:

   armor_penetration_1000m=;
   armor_penetration_100m=;
   damagetype=;
   

Again, look at existing weapons to get a feel for this.


More will be added to this section of the Wiki soon. For now, I hope this helps in introducing you to modding Spring: 1944 files.