System Editing Guide [WIP]

[Moberg]

3. Asteroid Fields

Now that you have hopefully experimented a lot already and placed a few objects in your system, it is time to move on to additional means to shape the atmosphere of a system while designing it. In my experience, finding elements you like in existing systems, understanding how they work and replicating them in your own system is a good way to learn.

---

There is surprisingly little that you have to edit in your system ini to add an asteroid field or a nebula. Freelancer often moves required information elsewhere, but points to that information through shortened nicknames and/or filepaths. The same is what we do here. Add a new [Asteroids] section below the [Background] section, as detailed in the example to the right. Here we point to an asteroids file that holds all the details for the field, and a zone nickname which points to the zone that is supposed to be filled with asteroids.

Freelancer can't actually find what we pointed to just now, we have to create it first. Add the zone we referenced to the bottom of the system file. Give it appropriate positioning, shape, size, infocards, property flags and other properties you want for the zone. I am using the example on the right.

---

Next up is the actual asteroid ini, where all the details about the fields are saved. Again, I will explain what each line does.

[Texture Panels] Filepath
Load the appropriate textures for asteroid billboards and bands. Those are the 2D asteroid images you see in the distance before the actual 3D asteroid objects appear as well as the 2D "ring" that surrounds many asteroid fields. If you forget this line, no asteroid billboards will apear and bands will be large stripe that surrounds your asteroid field.

[Field]
Asteroid fields are zones which Freelancer divides into cubes that are filled with asteroid objects. The inside of a cube follows a predetermined pattern you set in the [Cube] section, although some cubes are empty and all cubes have a rotation on their own. It seems to be randomly determined which cubes have what rotation, but it can be set to a fixed rotation. This will be covered in the cube section. While you can set a percentage that determines how many cubes are empty, the empty cubes seem to be randomly selected as well.

Cube Size
This determines how large the cubes are in which the patterns are generated. Larger cube size means that the set asteroid are generated in a large cube, while small cube size generates the same asteroids in smaller cubes (which means that fields are more dense, as the asteroid amount per cube stays the same while there are more cubes that have to be generated). For modifications that are supposed to be integrated into the mod, avoid extremely dense asteroid fields, for example through an enormous amount of asteroids per cube or extremely small cube sizes. Either is going to have a large impact on the FPS rate.
If you experience performance issues with the test setup to the right, try increasing the cube size until it's playable.

Fill_Dist
Asteroids are generated in a sphere around your ship. The fill distance determines the radius of that sphere.

Diffuse Color
Color of the asteroid objects when illuminated by white light, basically what the color of the object itself is. What this means is something you learn in chromatics. The short and simple version you need here is that an object has its own color and "absorbs" the part of the incoming light that is not part of this color while "reflecting" the parts that are. If an object is pure cyan (0, 255, 255 in RGB) and is illuminated by a white light source (255, 255, 255 in RGB) then the object will appear cyan (0, 255, 255). If the same object is illuminated by a pure red light source (255, 0, 0) then it will appear black/colorless. If it is illuminated by a pure green or pure blue light source, it will appear as green or blue, respectively.
Try to keep the diffuse color to something between white and grey if you want to allow the texture to determine the color of the object.

Ambient Color
The color of an asteroid object when it is not illuminated by a lightsource. Note that this color combines with the ambient color of your system ini.

Ambient Increase
To be honest, I have not really figured the point of this one out quite yet. It is another modifier for the ambient color, possibly related to intensity. It's best to keep the ambient lighting of an object not too bright unless the object is surrounded by plenty of possibilities for light to be reflected onto it (i.e. in nebulae). For objects in asteroid fields, a low ambient lightning is okay, to demonstrate that some light is reflecting from other asteroids.

Empty Cube Frequency
This value *100 is the percentage of cubes within the fields that are going to have no contents. A empty cube frequency of 1.0 will result in an empty asteroid field, as all cubes are empty.


[Exclusion Zones]
Exclusion zones in asteroid fields are zones where no asteroids are generated. The zone nicknames have to be valid and in the system the asteroid field is in. The game crashes otherwise. Exclusion zones do not have to overlap with the asteroid field, though in that case the exclusion zones are redundant.

exclusion
The name of the zone that will be used as an exclusion.

exclude_billboards
Prevents asteroid billboards from spawning in the exclusion; billboards will vanish upon entering.

exclude_dynamic_asteroids
Prevents dynamic asteroids from spawning within the exclusion.

[Properties]
The list from the property flags in zones also covers this part, which serves as another modifier for the minimap and ingame warnings. "Warning: Volatile gases detected", "Warning: Mines detected" as well as field representation on the minimap are covered here as well.

Cube
Now, this is one of the most relevant parts in the asteroid field. In here we determine exactly what objects appear, in which position, with which rotation.
The syntax here is:
asteroid = asteroid_archetype, x-axis factor, y-axis factor, z-axis factor, pitch axis rotation, yaw axis rotation, roll axis rotation.
The actual distance is dependent on the cube size, the coordinates you give here are simply factors that lead in combination with the cube size to actual coordinates.
The rotation uses Euler angles. The names pitch, yaw and roll axis give a better impression of what the rotation is when you imagine a plane. All rotation values are in degrees.

Additionally, in case you can't replicate my example in your system for performance reasons or because you choose your own values/entries, I recorded a video that showcases the cube generation. Details are in the video description.

The asteroid archetypes are listed in DATA\SOLAR\asteroidarch.ini
Note that although you may use different asteroid archetype, they will only use one material library at once. That means that if you chose a scrap metal "asteroid" and a minedout asteroid, they will share one texture, which will result in either the scrap metal having rock textures or the rock having scrap metal textures.[/url]


To remove a randomised rotation value for cubes, add
xaxis_rotation = 0, 0, 0, 0
yaxis_rotation = 0, 0, 0, 0
zaxis_rotation = 0, 0, 0, 0
to the cube section.

[Band]
Bands are the 2D asteroid "belts" that surround many asteroid fields.

Render_parts
Appears to be unused. Asteroid fields with bands have it, but deleting the line or changing it doesn't result in changes or crashes.

Shape
The nickname of the texture shape that the band uses. See DATA\SOLAR\ASTEROIDS\ock_shapes.ini for more.

Height
The height of the band. Do not use too high or too low values, it stretches the texture horribly.

Offset_Dist
The distance between the start of the zone and the band.

Fade
The first value must be 1.0, I receive crashes while testing any other value than 1. When you toy around with the second value, you'll see that the distance at which the 2D asteroid band around the field starts to fade is increased (or reduced). Values closer to 1.0 make it fade later and less smooth, high values make it fade from afar and very smooth. I couldn't figure out what the last two numbers do.

Texture_Aspect
Changes the aspect ratio of the textures. Values above 1.0 will stretch the texture, while values below 1.0 do the opposite. 1.0 will leave the band texture unchanged.

Color_Shift
Applies a custom color to the band texture. Format is Red, Green, Blue with percentage values (0 to 1), respectively. 1, 0, 0 will result in a pure red band texture, as an example.

Ambient_Intensity
Basically applies a factor to each parameter you set in the system and field ambient light. If your ambient light features a value larger than 1 for each color, giving this a high enough value will result in a white-texture band.

Vert_increase
No idea what this does, there isn't any notable difference at different values


[ExclusionBand]
Identical to the above, except used for a specific exclusion. Only used in vanilla for exceptionally large exclusions like the Hammen Hole in Omega-5. Exclusion Bands are not visible from outside the field.

zone
The name of the exclusion zone that will use a band.


[AsteroidBillboards]
These are the 2D asteroids you see at a distance when you navigate through a field, which usually fade in favor of 3D asteroids once you get closer. These asteroids are not the same as band asteroids.

Count
Straightforward. How many of these 2D asteroids are allowed to appear around you.

Start Distance
The distance at which these asteroids will appear/disappear (depending on your direction of movement).

fade_dist_percent
Some asteroids are already faded by themselves. This is the percentage that are slightly transparent on spawn already. Regardless of this value, asteroids will disappear when you are in despawn distance.

Shape
The texture used by the asteroids. Options are at \DATA\SOLAR\ASTEROIDS\rock_shapes.ini

Color_shift
Applies a custom color to the 2D asteroid texture. Format is Red, Green, Blue with percentage values (0 to 1), respectively. 1, 0, 0 will result in a pure red 2D asteroid texture, as an example.

ambient_intensity
Basically applies a factor to each parameter you set in the system and field ambient light. If your ambient light features a value larger than 1 for each color, giving this a high enough value will result in a white-texture 2D asteroid.

size
Higher Values: Larger 2D asteroids. Too big sizes will look horrible as the texture remains the same resolution.


[DynamicAsteroids]
The small asteroids floating through the field, which you can shoot and destroy that way.

asteroid
The archetype for the asteroids floating around. Options at \DATA\SOLAR\asteroidarch.ini

count
The maximum amount of asteroids able to spawn around you.

placement_radius
The radius in which dynamic asteroids spawn around you.

placement_offset
Exactly what the name says.

max_velocity
Spawning asteroids are moving at a speed chosen 'randomly' between this value and 0.

max_angular_velocity
Same as above, only with rotation speed instead of movement speed.

color_shift
Applies a custom color to the dynamic asteroid texture. Format is Red, Green, Blue with percentage values (0 to 1), respectively. 1, 0, 0 will result in a pure red dynamic asteroid, as an example.


[LootableZone]
When dynamic asteroids are destroyed, there are options to allow them to drop resources. This is otherwise known as mining.

Zone
Optional. Name the zone in which the dynamic asteroids of this asteroid field should drop resources. If no zone is specified, the entire asteroid field will be chosen.

asteroid_loot_container
The normal loot looks when you just shot them out of space. Technically not necessary anymore, as cargo is directly transferred to your cargo bay, but should be kept nonetheless.

asteroid_loot_commodity
The actual commodity that you can pick up into your cargo pod. Refer to the internal nickname of the commodity.

dynamic_loot_container
There is also something called dynamic loot, which is basically something similar to the normal loot, except you can set another alternative commodity here (or different drop patterns). This line is the same as the asteroid_loot_container, except for the dynamic loot.

dynamic_loot_commodity
Same as above, except with dynamic loot.

asteroid_loot_count
How many resources are dropped per asteroid? The first value is the minimum, the last value is the maximum, the game chooses a value inbetween.

dynamic_loot_count
Same as above, except with dynamic loot.

asteroid_loot_difficulty
Adds a chance at which the asteroid drop. Higher difficulty means that more dynamic asteroids have to be destroyed for the same loot as normal.

dynamic_loot_difficulty
Same as above, except for dynamic loot.