Asteroid Ring Mod

Example XML configuration file
This is an example configuration file for the Bylen ring in the Perdiso system, with asteroids dense enough to bring many systems to their knees. You will likely want a lower density than this.


<?xml version="1.0" encoding="utf-16"?><RingConfig xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <PlanetName>Bylen-396150125d120000</PlanetName> <ModId>1669459989.sbm</ModId> <Vanilla>false</Vanilla> <RingOuterRadius>1100000</RingOuterRadius> <RingInnerRadius>650000</RingInnerRadius> <RingHeight>3500</RingHeight> <SectorSize>10000</SectorSize> <MaxAsteroidsPerSector>500</MaxAsteroidsPerSector> <RingLongitudeAscendingNode>-2.67</RingLongitudeAscendingNode> <RingInclination>22.44</RingInclination> <MinAsteroidSize>128</MinAsteroidSize> <MaxAsteroidSize>2048</MaxAsteroidSize> <EntityMovementThreshold>512</EntityMovementThreshold> <SizeExponent>2</SizeExponent> <VoxelGeneratorVersion>4</VoxelGeneratorVersion> <ExclusionZoneSize xsi:nil="true" /> <ExclusionZoneSizeMult xsi:nil="true" /> <RingZones> <RingZone> <InnerRadius>880000</InnerRadius> <OuterRadius>920000</OuterRadius> <RingHeight xsi:nil="true" /> <InnerRingHeight xsi:nil="true" /> <OuterRingHeight xsi:nil="true" /> <MaxAsteroidsPerSector>10</MaxAsteroidsPerSector> <MinAsteroidSize xsi:nil="true" /> <MaxAsteroidSize xsi:nil="true" /> <TaperEdges xsi:nil="true" /> </RingZone> </RingZones> <TaperRingEdge xsi:nil="true" /> <Enabled>true</Enabled> <EarlyLog>false</EarlyLog> <LogDebug xsi:nil="true" /></RingConfig>


Global options
The below options are generally configured globally in the ringDefaults.xml file, but can be overridden per planet.

Option name
Default
Description
SectorSize
10000
Ring sector size in metres
MaxAsteroidsPerSector
50
Maximum asteroids per sector
MinAsteroidSize
128
Minimum asteroid size in metres
MaxAsteroidSize
2048
Maximum asteroid size in metres
EntityMovementThreshold
512
Distance any grid or player needs to move before new sectors are considered for population with asteroids
ExclusionZoneSize
64
Minimum space around asteroid in metres to exclude other asteroids
ExclusionZoneSizeMult
1.5
Minimum space around asteroid as a multiple of its size to exclude other asteroids
TaperRingEdge
true
Taper inner and outer edges of ring
SizeExponent
2.0
Size weighting exponent. Values larger than 1 prefer smaller sizes, while values smaller than 1 prefer larger sizes
VoxelGeneratorVersion
-
Space Engineers voxel generator version - defaults to value in VoxelGeneratorVersion in Sandbox.sbc
LogDebug
-
Used for logging; log debugging information into a file per planet in local storage directory (by default in AppData\Roaming\SpaceEngineers\Storage\{ModId}_{ClassName})
EarlyLog
-
Used for logging; start logging before planet is ring enable check
DebugDrawRingBounds
-
Draw ring bounds with equatorial, ascending node, and maximum latitude planes
IncludePlanetNameInRandomSeed
-
Include the planet name in the sector seed used to generate asteroids
DisableAsteroidCleanup
-
Disable the cleanup of asteroids out of range of grids and players


Per-planet options
The below options are configured per-planet. At the moment only one ring is support per planet (though zones can be used to divide it into sub-rings, as is done with the Bylen ring in the Ares at War system).

Option name
Description
PlanetName
Planet storage name (from config file basename)
ModId
Used to anchor the config to a specific mod (i.e. not apply if the planet comes from a different mod)
Vanilla
Set to true if putting rings around a base-game planet
Enabled
Set to true to enable ring asteroid generation for this planet
PlanetRadius
Planet average radius in metres
RingInnerRadius
Ring inner radius in metres
RingOuterRadius
Ring outer radius in metres
RingHeight
Distance between ring plane and upper / lower limit of ring
RingLongitudeAscendingNode
Longitude of ascending node (where the ring crosses the planet's equator going northwards)
RingInclination
Inclination of ring to planet's equator
RingZones
Zero or more RingZone elements


Ring zones
A ring can be split into zones - e.g. gaps can be carved out of rings, or zones with different heights, densities, or size makeups can be created.

OptionName
Description
InnerRadius
Inner radius of ring zone in metres
OuterRadius
Outer radius of ring zone in metres
RingHeight
Override ring height for this zone
InnerRingHeight
Override ring height for inner edge of this zone
OuterRingHeight
Override ring height for outer edge of this zone
MaxAsteroidsPerSector
Override maximum asteroids per sector in this zone
MinAsteroidSize
Override minimum asteroid size for this zone
MaxAsteroidSize
Override maximum asteroid size for this zone
TaperEdges
True to taper inner and outer edges toward the normal ring height


Predefined defaults
I have created pre-defined defaults for the following planets:

• Bylen (from e.g. Paradise)
• Bylen as it is in Ares at War part 2/3
• Demus
• Limitar

Bylen in the Paradise mod
The ring around this planet has an inclination of slightly less than 22.5 degrees, crossing the equator slightly off the X axis.

Option name
Value
PlanetRadius
500000
RingInnerRadius
650000
RingOuterRadius
1100000
RingHeight
3500
RingLongitudeAscendingNode
-2.67
RingInclination
22.44
The ring texture also suggests an area of lower density

Zone 1:
OptionName
Value
InnerRadius
880000
OuterRadius
920000
MaxAsteroidsPerSector
10
Bylen in Ares at War system
The ring around this planet has zero inclination (it is on the planet's equator), and has two notable gaps.

Option name
Value
PlanetRadius
500000
RingInnerRadius
650000
RingOuterRadius
1100000
RingHeight
3500
RingLongitudeAscendingNode
0
RingInclination
0
Zone 1:
OptionName
Value
InnerRadius
730000
OuterRadius
780000
MaxAsteroidsPerSector
0
Zone 2:
OptionName
Value
InnerRadius
880000
OuterRadius
920000
MaxAsteroidsPerSector
10
Zone 3:
OptionName
Value
InnerRadius
980000
OuterRadius
1030000
MaxAsteroidsPerSector
0
Planet Demus
The ring around this planet is a smaller version of the one around Bylen.

Option name
Value
PlanetRadius
76200
RingInnerRadius
100000
RingOuterRadius
170000
RingHeight
1000
RingLongitudeAscendingNode
-2.67
RingInclination
22.44
Planet Limitar
The ring around this planet has zero inclination (it is on the planet's equator). A default configuration has been defined for a planet diameter of 300km. These default values should scale if the planet diameter is different.

Option name
Value
PlanetRadius
150000
RingInnerRadius
200000
RingOuterRadius
330000
RingHeight
1000
RingLongitudeAscendingNode
0
RingInclination
0


Other ringed planets not yet with defaults
Below are some possible parameters for planets for which defaults are not currently defined in this mod (or where the planet diameter is different to that defined in the defaults):

• Planet Limitar

Planet Limitar
With a planet diameter of 350km as requested by silver.talon, the following values should work:
Option name
Value
PlanetRadius
175000
RingInnerRadius
230000
RingOuterRadius
390000
RingHeight
1200
RingLongitudeAscendingNode
0
RingInclination
0


More detail on various parameters
Some ring parameters probably deserve a more detailed description.

Units
This mod measures distances in metres and angles in degrees.

Planet Radius
The planet radius, if defined in the ring configuration, is the radius for which the inner radius, outer radius, ring height, and sector size are defined. If the actual planet's radius is different, then these will be scaled accordingly.

Inner / Outer Radius
The inner and outer radii of a ring are simply the distance of the inner and outer edges of the ring from the centre of the planet in metres.

Conversely, the inner and outer radii of a ring zone are the distance of the inner and outer edges of the zone from the centre of the planet in metres.

Ring height
The ring height is the distance between the ring's centre plane and its upper and lower bounds in metres. Therefore a ring height of 3500 means that the upper and lower bounds of the ring are 3.5km from its centre plane, or the ring is 7km thick.

Inclination / Longitude of Ascending Node
The inclination of a ring is the maximum latitude of the path its plane draws on the surface of the planet, while the longitude of ascending node is the longitude where this path crosses the equator (X/Z plane) on the planet going north (Y+). In this instance, zero longitude is taken as where the planet-relative X+ axis comes out of the planet, and longitudes increase in a counter-clockwise direction (as viewed from above the north pole).

Voxel Generator Version
The Space Engineers procedural voxel generation has gone through a few changes from its initial early access versions in 2013. In order to prevent drastic changes to asteroids in old saves, Keen has versioned the voxel generation for asteroids. This version number is stored in the VoxelGeneratorVersion element in Sandbox.sbc (with no element being assumed to mean version 0).

Version
Description
0
Original procedural generator without ice (before 01.074)
1
Default version before about September 2015 (introduced 01.074)
2
Generation identical to version 1 (introduced somewhere between 01.079 and 01.083)
3
New-style procedural generation (introduced 1.188)
4
"No Uranium on planets and tweaks in distribution of ore on asteroids" (introduced 1.189)
In order to be able to select which of these generator versions is used to generate asteroids in rings, separate to the version configured in the world configuration file, the VoxelGeneratorVersionelement was added to the ring configuration. Note that specifying non-existent versions could have undefined results (though will probably just cause asteroid generation to fail).


Asteroid generation
You may be wondering how this mod is able to have asteroids that aren't just nickel and ice (as would be the case with MyAPIGateway.Session.VoxelMaps.CreateProceduralVoxelMap(int, float, MatrixD)) or specify what generator version to use.

This mod uses the MyAPIGateway.Session.VoxelMaps.CreateStorage(byte[]) and MyAPIGateway.Session.VoxelMaps.CreateVoxelMap(string, IMyStorage, Vector3D, long) calls to load in a procedural asteroid file that is created in memory using the given parameters.

Note that unlike the normal procedural generation, where untouched asteroids are not added to the world file or written to disk when the game is saved, the asteroids created by this mod are added the world file and written to disk when the game is saved. Using default values of 50 asteroids per ring sector, this could result in a few thousand asteroids being saved to disk on world save, and being loaded on world load. It can also take a few minutes to generate all of the asteroids within visual range.

At the moment the asteroid generation only checks for other asteroids in the sector, and not grids or players, so it's possible for generated asteroids to entomb grids or players if added to an existing world.