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.

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

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

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.

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

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):

The following commands are not yet implemented:

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:

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:

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

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


The ring texture also suggests an area of lower density

Zone 1:

The ring around this planet has zero inclination (it is on the planet's equator), and has two notable gaps.


Zone 1:
Zone 2:
Zone 3:

The ring around this planet is a smaller version of the one around Bylen.


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.


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.

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

With a planet diameter of 350km as requested by silver.talon, the following values should work:

Some ring parameters probably deserve a more detailed description.


This mod measures distances in metres and angles in degrees.


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.


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.


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.


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.


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


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


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

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

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.