Chapter 6.2: Creating Custom Building
Any Spellforce building is a conglomerate of assets linked together by game engine. A building requires 3d model, textures, animations, which in their turn require to be registered within various game files. The building must also have game data which defines its game logic.
Game logic for towers becomes even more complicated than for other buildings, because towers act as combination of building and a unit (figure) which is tasked with running AI.
Finally, the most of tower projectiles are made as spells. If we don't want to use already existing animations and visual effects as placeholders, we can extend the long list of spell effects with our own visual.
Adding unique building requires a lot of preparatory work, so this section will detail the necessary steps for integrating a custom tower into the game.
To be displayed in game world, the building requires to have 3D model. To be accessible in interface, the building requires its own picture. Also, its appearance changes when it progresses from construction site to the actual building require set of animations. So, roughly speaking assets are divided into 3 categories: 3D model, textures, animations. The assets should be placed in folders mesh, texture, animation within the Spellforce main folder respectively.
Spellforce models use .msb extension. This format is rarely used, but Spellforce beta-version (that is required for SFSF to function, meanwhile) provides a set of modding tools including SF1 to FBX converter. It's located within %Spellforce\modding\SF1 to FBX Converter folder. It supports converting .msb models into .fbx and vice versa.
Using the converter can be helpful to export model to 3D-editor (for example, to Blender) and check its coordinates to write a proper collision mesh for the building.
Textures come with .dds extension.
Building animations come as .bor format (bone-reference file) and are automatically generated by the SF1 to FBX converter, when model is imported from .fbx file.
The handful set of assets designed specifically for this example can be downloaded here.
The building game data can be represented as JSON file. It contains building parameters, and its collisions. The most convenient way to create JSON is to get template, and customize it according to mod needs.
The json template containing necessary building game data can be downloaded there.
The JSON possesses following fields:
| Field | Description | Acceptable values |
|---|---|---|
| building_required | The ID of building which you must have built before in order to construct. Vanilla buildings within GameData.cff occupy numbers in range 1-213, and custom buildings can have any number higher than that, provided this number isn't already taken.* | Integer in the range 214-256 |
| can_enter | This boolean defines whether units can enter the building. | True if unit is allowed to enter into the building. |
| center_x | The center of model rotation along X axis. Also it's position of the worker if it's attached to building. NB: Must be outside of any collision polygons, otherwise the building gets inaccessible. | |
| center_y | The center of model rotation along Y axis. Also it's the position of the worker if it's attached to building. NB: Must be outside of any collision polygons, otherwise the building gets inaccessible. | |
| collision_count | The amount of polygons determining the building's collision. The building can no more than 5 collision polygons | Integer in range 0..5 |
| Collisions | This field contains an array of coordinates (points) that outline the collision boundary of the buildings. | Array of points defined with X, Y values represented as integers. Also, "collisions" object has got "shadow" property which accepts values "true" or "false". |
| description_id | The ID of a text data record that stores building description. | Integer |
| flags | Integer | |
| health | The building maximum amount of health. | Integer in range 1-32767 |
| id | The building ID. Should be anything above 213, since range 1-213 is occupied by vanilla buildings. | Integer in the range 214-256 |
| name_id | The ID of a text data record that stores building name. | Integer |
| race | The ID of a faction to which the building belongs to. More IDs can be checked with GameData editor in section 2022 "Race stats" | 1 - humans, 2 - dwarves, 3 - elves, 4 - trolls, 5 - orcs, 6 - dark elves. |
| resources | An object containing array of resources called "list" and an integer field "number" which determines the number of resource types necessary to construct the building. | |
| resources.list | Array of type-amount pairs containing data of required resources. | "resources": { list: [ { "amount": 200, "type": stone } ], "number": 1 } |
| resources.list[n].type | The json string representing type of resource that is required to construct the building | Possible types are "stone", "food", "wood", "iron", "moonsilver", "aria", "lenya" |
| resources.list[n].amount | The json integer representing amount of resource of specified type that is required to construct the building. | Integer |
| resources.number | An amount of resource types which are required to construct the building. | |
| slot_count | An amount of units which can enter the tower | Integer in range 0-256 |
* Building slots are 35, 50, 54, 97, 101, 105 are free. Building slot 37 is registered for "Elf Druid Guild" but is unused too, since it can't be constructed by workers of the faction (3, elves) it is assigned to and its model is archer tower put there only as placeholder.
In fact, the tower projectiles are simulated with spells. To make the Dwarf Tower, you have to create a custom spell that works against a single target. Let's call it Hammer Throw, because the tower we're making is going to garrison dwarven hammer-thrower.
In more details creating a custom spell is explained in Chapter 0, section Creating new spell.
You should repeat steps from there, aside from that you don't need to create a scroll carrying this spell, since we don't need to make this spell usable by player character.
Declare new Spell Type for Hammer Throw. Assign it flags, type and range as on the screenshot.
Then you should create respective spell for newly created Spell Type. It should have Requirements 1 fields set as 7 and 1 and 5. Faction 1 stands for enemy, Target type 1 stands for a single figure.
Casting time and recast time determines the tower's attack speed.
Mana cost must be set to 0, otherwise tower attacks would become inconsistent. This value can be experimented with, but it's better to put it as 0 currently for the sake of simplicity.
Effect power should be set to 100.
Parameter 0 is the only custom parameter the spell has. It stands for spell base damage before armor reduction is applied.
You can refer to the screenshot below to check if each parameter is correct.
The spell is ready for use. Now it must be added to a unit, which is going to control tower's AI.
When a tower is built in Spellforce, it gets assigned with a unit which runs its AI. The unit decides which target to attack and when with the spell that is made to simulate tower projectile.
The Spellforce unit is built from two main records, which are held in sections 2024, Unit general data/link with unit stats and 2005, Unit/hero stats. Unit general data defines unit equipment and spells, and appearance, and Unit stats define unit parameters such as Strength, Agility, Intelligence, etc.
Because the unit is going to exist in game only virtually, and it's only purpose to cast spells, it will be enough to duplicate any of vanilla tower units. You can filter them among other units with search field. Open section 2025 Unit/hero stats, enter searching word "Tower", pick "Text" group and then press "New search" button.
The editor will show all tower units which exist in game. Select any stats and press "copy" button.
Then click "Clear search" and press "Add button" which will be highlighted yellow, because there is a unit in clipboard. It will create unit which already has got stats, so you won't need to manually fill every parameter.
Replace new unit's Race ID with number 2 which stands for Dwarves faction.
When we've got unit stats, let's proceed to the section 2024, Unit general data/link with unit stats. Copy-paste any suitable unit and edit Unit stats ID field to match with the index of stats which you've made before.
For this example unit stats list has ID 2964, and the unit has ID 2997 (vanilla units belong to range 1-2996).
Then you should go to the Unit's Equipment tab and edit it accordingly.
Don't mind it having human right hand, there is no right hand made specially for dwarves. All dwarven units are using human hands.
Edit the equipment and go back to unit's general data.
After that you should go to Unit Spells tab.
Select the empty record and change Spell ID there to index of a spell created before. In this example, it is numbered 3553 for example.
The unit it's ready. Mark down its ID somewhere, because you'll need to reference it in mod's code to attach the unit to the tower as part of Building Done handler.
The building can't be constructed out of nothing. Your character needs to obtain and equip building rune, in order to make tower available to be built by dwarven workers.
Fortunately, building projects are represented as a set of two scrolls: inventory one and its equipped version. They have their own type, so game engine doesn't confuse them with spell scrolls. However, the principle remains the very same.
Open 2003, Item general info section. Add two new items. The first item must have Item type set to 7 and 3, the second item must have Item type set to 9 and 3.
The former field determines Item type. 7 stands for unequipped building plan, 9 stands for instance of building plan when it's equipped to the hero.
The latter field stands for building faction. Due to some error, this number must be 3 for building to be available for Dwarves, even though in general 3 stands for Elves faction.
Also, both scrolls must have building ID matching the index of the building which was used to register the building within the code. In this example, this number is 222.
Then you should link scrolls to each other. Select the first (uninstalled scroll) and press "Add scroll link for the item" button twice. Put the index of the second scroll to the field Installed item ID.
Let's add UI to the scroll. The UI we register here would work as a frame for image of the tower loaded directly from custom assets.
The unequipped instance of scroll requires two UI lines. Assign ui_item_planscroll_dwarf to the first one.
Then make the second line, and assign ui_btn_tower_dwarf to it.
The equipped instance of scroll requires only one UI icon.
Go to its UI data and assign ui_btn_tower_dwarf to the line inside.
With that the building plan is complete.
Add it to the inventory of any familiar merchant. Then you can buy a scroll any time and test building in-game. The building plan will be accessible via "plans" section of merchant inventory.
For example, you could add scroll to Offensive Mind Magic Merchant (121) who stands exactly in the middle of map called "Marketplace". Then you should place the scroll to character's plans section to Dwarves group. The building will become accessible in building menu of dwarven workers.
We've compiled all steps above into single patch which can be merged with main GameData file. In case you don't want to be bothered with doing all those steps manually, you can download it here.
In order to merge the patch with GameData you should open Spellforce editor by shovel_knight. Go the usual way you load Game Data, but pick Load mode: 'Merge' instead of 'Full'.
Click Add gamedata and select original GameData file from %Spellforce/data folder.
Then click Add gamedata once more and specify the path to file which you've downloaded before (dwarf_tower_dependency.cff). Loader should look like that now.
Press "OK". The editor will automatically merge main file and dependency. When it's done, it will display game data records as usual. Scroll down 2002, Spell data down. If you've made everything correct, there will be Hammer Throw level 5 spell in the bottom.
If merge is successful, you should save its result now now. Just save it as you usually save GameData after making some edits to it. Select Load mode: 'Full' and save new version in place of GameData.cff. This will replace original gamedata with merged file, and will make changes appear in-game. The new building is almost ready for testing.
To complete preparations, you'd also need to register building's assets for the game engine. Game data stored in JSON must be somehow linked with mesh, textures and animations.
The scripts which register game objects are stored compiled within game files. However, if you've downloaded the Spellforce beta version, there will be a folder called modding within the Spellforce main folder. This folder contains decompiled scripts. Those scripts can be edited in order add new models, animations, spell visual effects and so on.
You should open the modding\Original scripts folder, then \script subfolder, find files named sql_building.lua and sql_unit.lua there and copy them into %Spellforce\script.
You should move again to modding\Original scripts folder, open \object subfolder, find files object_effect_register.lua and object_effect_test.lua and copy them into %Spellforce\object folder. Those files are used to determine spell visual effects.
Moving decompiled script into game folder will make Spellforce use edited versions of those scripts, and hence it will become possible to add new models and spell visuals to the game.
When you've completed preparatory steps, you should open sql_building.lua Scroll its down and add the following line below the "blade tower" numbered 213.
[222] = {mesh={"building_dwarf_hammer_tower", "building_dwarf_forge_decal", "building_dwarf_forge_frame", }, selectionscaling=3},This line would assign the building its unique ID, as well as link the building with its model. The number in square brackets must be 214 or higher, because IDs in 1-213 range are used by vanilla buildings (except slots 35, 50, 54, 97, 101, 105 and 37 as explained above).
The mesh name should match the mesh filename spelled without .msb extension.
Selection scaling essentially can be anything below 20. The number can go higher, but it would make the building overtly big.
Find file name sql_unit.lua inside. Navigate down and add the following line below "Bergteufel" numbered 2996:
[2997] = {r=255, g=255, b=255, a=255, name="AI dwarf hammer thrower (DO NOT PLACE)"},Number 2997 corresponds to ID of the unit which is going to be attached to the tower. If you have mods which add custom units to the game, then this number can be any other. It's only important for it to match with the Dwarf Hammer Thrower within GameData.cff.
Brief reminder, if you haven't do this before, you should move again to modding\Original scripts folder, open \object subfolder, find files object_effect_register.lua and object_effect_test.lua and copy them into %Spellforce\object folder. Those scripts are used to register spell visual effects.
You should open object_effect_register.lua within %Spellforce\object folder. Then you should ind the line SpellEffect{line=kGdSpellLineWaveOfIce, cast="CastIce", resolve="ResolveIce", projectile="WaveIce"} and place the following lines below it:
SpellEffect
{
line = 249, -- kGdSpellLineHammerThrow --
resolve = "NoEffect",
hit = "ThrowHammerTower"
}This would associate specific Spell Type (line = 249) with visual effect.
Then you should open object_effect_test.lua in the same folder. Scroll down and insert the following lines below.
NewMovie(1)
Translation { min = {0,0,0} }
GlobalTrail{buffer=0.03, range=0.03, trail=1}
Color{max=0, range=0.3, trail=1}
Scale{min=1.5}
Rotation{ axis = "x", min = -90, direction = 0}
Rotation{ axis = "x", max = -360, range = 0.3 }
Rotation{ min = 90, direction = 0}
NewObject{mesh=flics.hammer, movie=pMovie, restriction=kDrwCsProjectile, bone=kDrwBoneChest, bonesource="Shoot", boundingradius=30, shadow=1}
EffectSave("ThrowHammerTower")Those lines determine the visual effect which was linked to Spell Type governing Hammer Throw in previous paragraph.
Now the custom tower is fully complete and it's finally ready for testing. You should buy a scroll from the merchant you added it to, equip it to the hero and go to any map which has the Dwarven Monument on it.
Hint: You can use command Application: GiveMeGoods(1000) in Spellforce console which can be opened with pressing 'Ctrl'+'['.
Tower should become available for construction for dwarven workers, and it will attack any enemies it sees in range. Good luck!