Author Topic: Documentation: mod.ini  (Read 10055 times)

0 Members and 1 Guest are viewing this topic.

Offline urraka

  • Soldat Developer
  • Flagrunner
  • ******
  • Posts: 703
Documentation: mod.ini
« on: February 24, 2016, 06:31:26 pm »
With Soldat 1.7.0 we introduced a new mod.ini file which controls how some things are displayed. There are two different sections in this file: [SCALE] and [GOSTEK].

Scale

The purpose of this section is to solve a problem that came along with the new HD rendering support: we needed to decouple pixel units from in-game map/world units. Without this, all new HD images would show up huge.

In this [SCALE] section you may have a DefaultScale entry and as many file/folder specific entries as needed. Here's an example:

Code: [Select]
[SCALE]
DefaultScale=4.5
interface-gfx/cursor.png=10  # file specific
interface-gfx=2              # directory specific

For any given image file, it first tries to find an entry for that specific file. If there is none it will try to find an entry for the directory where the file is contained. If that's not there either it will use the DefaultScale value (or 1 if it doesn't exist). Note that directory entries do not apply to sub-directories.

Custom interfaces and mods need their own mod.ini file. If they don't have this file it is assumed that it's an old interface/mod and the scale for the images it contains will default to 1. The file/folder paths are always relative to where the mod.ini file is located.

The scale value defines how many pixels of the image fit in 1 map/world unit (another way to think of it is how much bigger the image is compared to the old version). If you design an image for a specific resolution, you can calculate the scale value with a simple formula:

Code: [Select]
scale = resolution height / 480
That's because map units are 1:1 with pixels when using 640x480 resolution and the bigger the resolution, the more pixels a map unit will cover. The width of the resolution doesn't matter because it only affects the field of view.

Gostek

The soldier is composed of a skeleton and a number of sprites that are hooked to specific skeleton points. That hook is defined by 3 properties:

  • A point from the skeleton used for the sprite position.
  • A reference point from the skeleton used for the rotation angle of the sprite.
  • An anchor point (or center point) for the sprite.

The [GOSTEK] section from mod.ini provides the ability to change the anchor point of each sprite, which is the point from where the sprite is positioned and rotated in relation to the main skeleton hook point. This anchor point is expressed in normalized coordinates going from (0,0) to (1,1). Here is a visualization of how it works:



Most of the images in gostek-gfx/ and weapons-gfx/ have a flipped version with "2" or "-2" suffix. These flipped images should have the same size as the non-flipped one, otherwise the sprite alignment will be different when the soldier is looking to the left.

For now there is no way to setup different alignment values for the "team2" gostek graphics, so it's best to keep those with the same size and similar shape as main gostek graphics.

Attached is a list of all the soldier sprites that can be tweaked from the mod.ini file, along with the image file they are related to. The actual entry that goes in the [GOSTEK] section is the sprite name with a "_CenterX"/"_CenterY" suffix.

Online tool for editing and previewing the alignment values:

http://urraka.github.io/soldat-gostek/

You can drop a zip with gostek-gfx/ and weapons-gfx/ folders to load custom graphics. The soldier looks slightly different in this tool because it doesn't account for some skeleton modifications done by the game logic (like aiming), but it looks close enough to be helpful. A mod.ini file can be loaded/saved with the buttons on top of the table on the right.
The mod.ini file you save from there is not intended to directly replace the one you have in soldat, as it won't have any scale information.

Note: This tool hasn't been updated to load scale information from the mod.ini file. It still relies on the scale.ini file which was used during the alpha/beta versions of Soldat 1.7.0, so if you drop a zip with the graphics it should have a scale.ini file inside each directory.
« Last Edit: February 25, 2016, 01:26:27 pm by PerroAZUL »
urraka

Offline CCalp

  • Global Moderator
  • Soldier
  • *****
  • Posts: 238
  • calp (SN)
Re: Documentation: mod.ini
« Reply #1 on: February 24, 2016, 07:00:22 pm »
Cool, thanks for writing that up!
~ stickied

Offline %%%%%%%

  • Soldier
  • **
  • Posts: 205
Re: Documentation: mod.ini
« Reply #2 on: February 25, 2016, 01:38:08 am »
Does the y-axis for sprite anchor points actually go from 1 to 0 from the bottom to top or is that an error with the example shotgun image


Offline urraka

  • Soldat Developer
  • Flagrunner
  • ******
  • Posts: 703
Re: Documentation: mod.ini
« Reply #3 on: February 25, 2016, 10:31:29 am »
Does the y-axis for sprite anchor points actually go from 1 to 0 from the bottom to top or is that an error with the example shotgun image

It goes 0..1 from top to bottom. Top to bottom might seem backwards from a math point of view but it's quite common when dealing with images and 2D graphics in general. So in this case (0,0) is top-left and (1,1) is bottom-right.
urraka

Offline %%%%%%%

  • Soldier
  • **
  • Posts: 205
Re: Documentation: mod.ini
« Reply #4 on: February 25, 2016, 12:20:39 pm »
It goes 0..1 from top to bottom. Top to bottom might seem backwards from a math point of view but it's quite common when dealing with images and 2D graphics in general.
Cool, learn somethin' new everyday. :)

Offline urraka

  • Soldat Developer
  • Flagrunner
  • ******
  • Posts: 703
Re: Documentation: mod.ini
« Reply #5 on: February 25, 2016, 01:28:08 pm »
Replaced the image with one suggested by SyavX (on irc) so it's less confusing.
urraka