RangeCircle 1.2.6 - Calibration Guide
=====================================

This guide is for the projection-only version of RangeCircle.

1. What calibration does

RangeCircle projects a real horizontal circle from world coordinates to screen coordinates. It is not a 3D decal, but it should follow camera angle and zoom much better than the old 2D ellipse mode.

The most important value is the ground/Z offset. This controls the height of the plane used to project the circle.

Recommended starting value:

/rangecircle zoffset 4

2. Why Z offset matters

If the circle is projected too high or too low, it will suffer from parallax. The character may stay still, but when you rotate or tilt the camera, the ring will appear to move over the floor tiles.

That means the problem is not horizontal centering. It is the projection height.

3. Calibration method

1. Go to a flat floor with a visible grid or tile pattern.
2. Use a visible preset, for example:

/rangecircle preset 20

or

/rangecircle preset 30

3. Use a top-down camera and observe which floor tiles the ring touches.
4. Without moving the character, lower the camera to your normal gameplay angle.
5. If the ring no longer touches the same tiles, adjust zoffset.
6. Start with:

/rangecircle zoffset 4

7. If needed, compare nearby values:

/rangecircle zoffset 3
/rangecircle zoffset 4
/rangecircle zoffset 5

4. When to use nudge

Use nudge only after zoffset is stable.

Use zoffset when:

- The ring shifts when the camera angle changes.
- The ring does not stay on the same floor tiles between top-down and normal camera.
- The circle appears to float above or sink below the floor.

Use nudge when:

- The ring is consistently offset in the same direction in all camera angles.
- The ring needs a small screen-space correction to align with your character model.

Useful nudge commands:

/rangecircle nudge 10 0
/rangecircle nudge -10 0
/rangecircle nudge 0 10
/rangecircle nudge 0 -10

Reset nudge offset:

/rangecircle center

5. Recommended workflow

1. Set quality to high while testing:

/rangecircle quality high

2. Set point size large enough to see clearly:

/rangecircle pointsize 20

3. Set a useful range preset:

/rangecircle preset 20

4. Set the recommended ground height:

/rangecircle zoffset 4

5. Compare top-down and normal camera angles.
6. Adjust zoffset first.
7. Adjust nudge second.
8. Once calibrated, reduce point size or opacity if the ring is too intrusive.

6. Tested note

During in-game testing on a flat tiled floor, /rangecircle zoffset 4 produced a good match between top-down and normal camera views. This is now the recommended starting point.


Version 1.2.6 calibration update:
- Projected range presets were recalibrated using War Quarters floor tiles, treating each tile as 5 ft.
- The projected world scale now uses 14 internal units per foot for 10/20/25/30/45 ft rings.
- Dot placement now uses adaptive screen-space spacing, so large rings have more uniform point distribution and fewer empty edges.


Version 1.2.6 notes:
- Added the 40 ft preset.
- PROJECTED_UNITS_PER_FOOT is now calibrated to 16.
- Added custom projected radius commands: /rangecircle range <feet>, /rangecircle feet <feet>, /rangecircle radius <feet>.
- Added menu buttons Range -1 ft and Range +1 ft for active ring custom sizes.


Version 1.2.6: added a Default ranges button and /rangecircle defaultranges command to restore the default Ring 1/2/3 preset ranges.
