DSJ4 Hills Engine Documentation

Welcome to the official DSJ4 Hills Engine Documentation. This documentation covers almost completely all XML parameters and attributes required to create custom hills.

TIP

DSJ4 hills are written in XML. This documentation assumes that you have basic knowledge of this language. If not, browse the guide on the internet.

Getting started

TIP

This documentation is still subject to change. If you found something not clarified, not understandable either you found a mistake, please follow the Contributing section.

Every documentation section includes:

  • parent element name
  • element name
  • attribute
  • type
  • description
  • allowed values, default value and optional column in some places

WARNING

When writing your XML hill, you have to include attribute type and allowed values. If you won't do that, the game may crash or throw an XML error.

TIP

The optional column means that such an attribute is not required in your XML code. In this case, this attribute value will default to the Default value column.

Consider the Location section (parent element name is hill and element name is location).

AttributeTypeAllowed valuesDescription
lattitudeFloat<-90.0; 90.0>Lattitude
longitudeFloat<-180.0; 180.0>Longitude
orientation+Integer<0; 360>Terrain rotation in regard to the Earth
timezoneInteger<-12; 12>Time zone
altitudeFloat(-inf; +inf)High above sea level

Basing on the information above, you can write the following XML code.

<hill version="DSJ4-1.7.0">
    <!-- Rest of code omitted for clearance -->
    <!-- 
        The parent element is hill, so the location element is placed under the hill attribute
        The element name is location, so it's placed in the first place as an attribute
        Next on there are attributes with their values respecting type and allowed values.
     -->
    <location latitude="49.1976" longitude="20.0712" orientation="245" timezone="2" altitude="1300" />
</hill>

WARNING

Version attribute in the hill element equal to DSJ4-1.5.0 or DSJ4-1.7.0 is required.

Understanding types

Next to the attribute name, you could notice the Type column. When writing your hill you have to be specific about attribute values types. The table below presents how to understand types.

NameAllowed valuesDescriptionExample
Integer(-inf; +inf)Integer-100, 100
+Integer<0; +inf)Natural numbers100, 1000
Float(-inf; +inf)Numbers with digits-1.01, 1.01
+Float<0.0; +inf)Positive numbers with digits1.01, 1000.01
-Float(-inf; 0.0>Negative numbers with digits-1000.01, -1.01
StringTextMediamond, Vikersund
Booleantrue, falseTruthy or falsytrue, false
TextureTextures.*.pngTexture in .png formatTextures\metal.png, Textures\flag-aut.png
MaterialMaterials.*.xmlMaterial in .xml formatMaterials\wood.xml, Materials\metal.xml
Color0x[000000 - FFFFFF][00 - FF], [000000 - FFFFFF]Color in hexadecimal format0x123456, 123456

Additional notes

To avoid text repetition, some attribute names may be shortened. The table below presents how to understand different cases.

AttributePossible attributes names
[r, g, b]r, g, b
[t, m, c]1t1, m1, c1
[t, m, c][1, 2]t1, t2, m1, m2, c1, c2
c[0, 1, 2]c0, c1, c2
[summer, winter]-dsummer-d, winter-d
refx[1, 2]?refx or refx1, refx2

WARNING

Notice possible attribute names at refx[1, 2]?. They can be refx OR refx1 and refx2. That means you can have either refx or refx1 and refx2 - such attributes when mixed are excluding each other.

Contributing

Everyone is welcomed to contribute to the documentation! Source code is available here. You can send your issues or pull requests. In case you don't have that much programming knowledge, you can contact the documentation maintainer using Facebook or GitHub.