Planetary Asteroid Rings configuration options

Configuration options for the Planetary Ring Asteroids mod, split out from its description as that was becoming too long.

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 Known issue: example config has no default
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 - beware that this could eventually cause the physics engine to run out of memory at high densities and player movements
DisableReducedSaveDistance	-	Don't clear the Save flag on asteroids - this should reduce pop-in on dedicated server at the expense of a larger save size

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

Chat Commands

Chat commands are available to configure rings.

These chat commands are introduced using /ringast, and are a command followed by one or more arguments. For example, to select Bylen for editing, one would use the chat command

/ringast select Bylen

After every command where a ring is currently selected is being edited, an .xml.editing file for the selected ring will be created or updated in the mod world storage on the local computer.

Commands are as follows (case insensitive):

Command	Description
Select {name}	Select the ring of the given planet for editing
Select @defaults	Select the ring defaults for editing
Select @nearest	Select the ring of the nearest planet to the player or spectator camera
Select @lookat	Select the ring of planet being looked at by the player or spectator camera
Deselect	Deselect the ring config being edited. Unsaved changes will be lost.
Commit	Commits the ring config. Requires at least Space Master.
LoadLocal	Loads the ring configuration from the .xml.editing file for the ring being edited from the mod world storage on the local computer.

The following commands are not yet implemented:

Command	Description
ZoneAdd {from}-{to}	Adds a new zone to the ring
ZoneSel {from}-{to}	Selects the specified zone
ZoneSel @lookat	Selects the zone being looked at by the player or spectator camera
ZoneSel @nearest	Selects the nearest zone to the player or spectator camera

Any of the options in Global Options and Per-Planet Options above are configured by using the option name as the command (case insensitive) and the value as the argument. e.g. to set the sector size, one would use the chat command:

/ringast sectorsize {size}

For options for the selected ring zone, prefix the option name from Ring zones above with Zone - e.g. to update the zone height, one would use:

/ringast ZoneRingHeight {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

Planet Salus

The ring around this planet has an inclination of a little under 7 degrees, crossing the equator slightly off the X axis. A default configuration has been defined for a planet diameter of 120km. These default values should scale if the planet diameter is different. Note that the graphical ring has zero thickness, and so the asteroids will appear around it rather than inside it.

Option name	Value
PlanetRadius	60000
RingInnerRadius	89400
RingOuterRadius	130000
RingHeight	1000
RingLongitudeAscendingNode	-6.75
RingInclination	6.785

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
  
• Salus

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.

Sector size

To reduce the number of asteroids that need to be generated in one group, rings are divided into approximately equal-area sectors.

The sector size determines the size of the bands the ring is divided into - i.e. a 10km sector size divides the ring into 10km bands.

The equal-area is implemented by having each band contain 6 more sectors than the previous band - i.e. with a 10km sector size, the band at 500km from the centre of the planet will have 50 × 6 = 300 sectors, and the band at 510km from the centre of the planet will have 51 × 6 = 306 sectors.

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 VoxelGeneratorVersion element 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).

Determining ring parameters

In the future, I hope to streamline determining ring parameters in-game using e.g. chat commands. For rings using the CloudRing model (or versions thereof), I hope to generate default parameters based on the axis and initial rotation defined in the planet's definition.

To determine the inner and outer radii of the ring, the easiest way would be to create a GPS marker for the centre of the planet, then using spectator find the distance from that marker to the inner and outer bounds of the ring. You may need to go around the planet, as different parts of the ring may be invisible at different solar angles.

To determine the ring height, look for a part of the ring where both sides of the ring are visible, away from the inner and outer edges of the ring, and find the shortest distance between these two sides. The ring height will be half this distance.

With the inner radius, outer radius, and ring height determined, one can create an initial configuration with these values set. The DebugDrawRingBounds configuration option is also useful for determining the ascending node and inclination in the next steps. At this time, it may be easiest to set the ring height to zero so the point where the ring crosses the equator can be more easily determined.

The DebugDrawRingBounds option faintly draws planes for the ring (brown if disabled or aqua if enabled), the equator / X-Z plane (blue), the meridian of the configured ascending node (red), and the meridian perpendicular to both (green). The equatorial plane is not drawn if the inclination is 0 degrees, and the plane passing through the ascending node is not drawn if the inclination is 90 or -90 degrees.

If the ring is coincident with the equator, then both inclination and longitude of ascending node will be zero.

Creating X+ (with a large positive X value of e.g. 1 billion) and Y+ (with a large positive Y value of e.g. 1 billion), and Z+ (with a large positive Z value of e.g. 1 billion) GPS markers will also assist in determining where north and zero longitude are.

To find the ascending node, find where the ring crosses the equator going north-east (where north is towards Y+). Zero longitude is taken to be the meridian coincident with the line from the centre of the planet towards X positive infinity. One can estimate and refine the longitude of the ascending node until the intersection of ring, brown, and red planes coincide as closely as desired.

With the ascending node found, find where the ring crosses the green plane, which should be at its greatest latitude. One can estimate and refine the inclination until the intersection of ring, brown, and green planes coincide as closely as desired.

Refine both ascending node and inclination as desired.

Once these parameters are sufficiently refined, disable the DebugDrawRingBounds configuration option, and set the ring height (if it was set to zero).

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.

[Bravada Cadelanne]

The latest version should fix small rings not generating asteroids.

[Stretch]

Issue identified and resolved. (2 hours of testing :D)

1) Thank you for the Max Asteroids, that helped.
2) Inner and Outer Radius was the issue.

Earthlike default on a new Solar System server.
<RingOuterRadius>134400</RingOuterRadius>
<RingInnerRadius>84000</RingInnerRadius>

Minimum required, roughly doubled the inner radius to get results.
<RingOuterRadius>190000</RingOuterRadius>
<RingInnerRadius>150000</RingInnerRadius>

Imgur Example link [imgur.com]

I tested on multiple new sessions, Empty world with custom planets and default Solar System.

Once new radius's set all other options started working.

Hope this makes sense and is helpful

[Bravada Cadelanne]

Looking at the config generated for e.g. the alien planet, it looks like MaxAsteroidsPerSector isn't properly being set in the example config, and because it has no default anywhere else, it is preventing the asteroid ring from actually being enabled.

Please try replacing
[code]
<MaxAsteroidsPerSector xsi:nil="true" />
[/code]
with e.g.
[code]
<MaxAsteroidsPerSector>50</MaxAsteroidsPerSector>
[/code]

I will fix this in a coming update.

[Stretch]

Can confirm, started Art of War mod, added Planetary Asteroid Rings, rings appeared and working. I'll continue to work this config into another server. Thanks for the taking the time.

[Stretch]

@bravada, I did get the Aqua ring up, was able to chance the size of it. Even though it might have been to do with the EntityMovementThreshold but i traveled (in space suit) for... until i ran out of energy and nothing spawned. If i have ProceduralDensity on then asteroids will appear in the usual way, in and out of ring but if ProceduralDensity disabled, nothing. Used the same config above in doco, everything appears to be applying from the config, size changes, location width etc, just no asteroids. Going to test with the Ares at War mod and predefined planet youve described.

[Bravada Cadelanne]

@Stretch The Blue, Red, and Green planes are not where the actual ring is - they are guides marking the equatorial plane, the meridian of the ascending node, and the meridian 90 degrees from the ascending node. It is the brown (if disabled) or aqua (if enabled) ring where the asteroids should spawn.

[Stretch]

@Bravada Cadelanne Thanks for the response. I started a new offline single player server using the default Solar System custom mode. I tested creating an asteroid around Earthlike and the Moon on different occasions. I was able to see the debugdrawring so i travelled to the ring locations but no asteroids appeared. Red/Green/Blue rings, i tried each location.

I'll start up another instance and publish the config

[Bravada Cadelanne]

@Stretch what planet from which mod were you trying to put asteroid rings around?
Note that DebugDrawRingBounds currently only works in single player or for the host.
Asteroids are only spawned in within the server render distance (default 15km) of the player character, and unless DisableReducedSaveDistance is enabled, only asteroids within sync distance (default 3km) of the player character will pop in.

[Stretch]

Assuming I'm doing something wrong or its working and I just cant find the asteroid belt. 1) new Server, 2) Add Asteroid Belt Mod (only) 3) Load, Save, Exit, Load, Save, Exit 4) Config .xml files to enable Asteroids, Enable DebugDrawRingBounds. 5) Load. 6) travelled to visible ring area but no asteroids. What am I missing?

[darinreynolds90]

does this generate automatically or do i have to altar something this looks really cool i mean is there like chat commands that need to be used?