AstraTerra Manual Verification

Setup

Build and deploy release output: make deploy.
Load AstraTerra in Vintage Story 1.22.2 with the mod enabled.
Create or open a test world.
Spawn or craft the Brass Telescope, Precision Telescope, Sextant, and Calibrated Astrolabe.
Set time/weather as needed so the sky is dark and clear.
For daytime sky checks, run .stars daylight-stars on; turn it back off with .stars daylight-stars off before normal play validation.

Lying Down

Load any world and check client-main.log; expected result: no Shape … has mixed animation versions error. An animation added to a vanilla shape must not declare a version of its own, and must be authored in version 0 — version 1 turns a bone about its cube's corner instead of its joint. See docs/dev/data-pipeline.md.
Stand still on solid ground and press Z; expected result: the seraph crouches, sits, and lowers itself onto its back over about half a second — it does not pivot at the hips with its feet planted, and it does not arch into a bridge on the way down.
Watch it in third person once it is down; expected result: it lies on its back (not its side), the hips, back, and both legs rest on the ground rather than floating or sinking, one knee is drawn up, the chest rises and falls, and empty hands are folded behind the head with the elbows resting on the ground — the arms stay attached at the shoulder and the elbows do not come apart from the forearms.
Expected result: the first-person camera drops close to the ground and the view looks straight up.
Preview any pose change without launching the game with make pose-preview CLIP=stargaze-down, which draws the clip frame by frame and reports anything sunk into the ground or pulled apart at a joint.
Expected result: the sky, stars, and meteor streaks fill the view. The body stays on the ground and does not block the sky. The camera does not clip into the block below.
Switch to third person, then to the fixed overhead camera, and press Z; expected result: the body lies down on the ground, but the camera does not snap to the sky.
Look around while lying in third person; expected result: the camera/head turns and the body stays planted.
Hold right click with the Brass Telescope while lying down; expected result: scoped view still opens, zoom still works, and the arms follow the telescope instead of staying behind the head.
Press W or Space; expected result: the player stands up straight away and walks or jumps normally — no half-second of gliding while an animation finishes — and the camera returns to standing height.
Press Z again while lying; expected result: the seraph sits up, tucks its legs under, and stands, over about half a second — it does not snap upright or reverse through a bridge — and the camera rises with it.
Press Z twice quickly to lie down again mid-rise; expected result: it goes back down from wherever it is, without a jump.
Press X; expected result: vanilla off-hand swap still runs, and the player does not lie down.
Remap Lie down in Controls and confirm the new key toggles the pose.

Core Smoke Test

Confirm telescope and sextant items use visible non-placeholder models/textures.
Hold right click with the Brass Telescope and confirm normal item interaction is suppressed while scoped.
Confirm the fixed-star sky is visible at night and does not crash with the generated catalog.
In a default 108-day world, move to about 32.5° north with .stars goto-lat 32.5, set the calendar to month 12 day 4 at about 02:00 — mid-December, where the Geminids really fall — and watch open sky for several minutes. Confirm Geminid streaks appear, travel away from one common radiant, and vary from short near the radiant to longer farther away. A bright moon may make the shower sparse but must not eliminate every meteor.
For a shorter development check, set DebugMeteorRateMultiplier to 30.0 in ModConfig/astraterra.json and restart the client. This reproduces the original accelerated test rate. Restore the default value of 1.0 before evaluating normal player-visible frequency.
Move the time into daylight and confirm new meteors stop spawning. Move indoors and confirm no stale streak remains frozen overhead; return outdoors at night and confirm spawning resumes.
Move away from the shower's activity window and confirm no meteor streaks appear during the same observation interval.
Run .stars comets; expected result: four comets are listed, each either up with a phase, magnitude, tail length and position, or away with a day count and the world year its next window opens. This is the only practical way to find an apparition — Machholz is the frequent one, and Halley is due once in about seventy-five world years.
Set the calendar to a world day inside an apparition (take it from .stars comets) and watch open sky at night; expected result: the comet is up, with a visible coma and a tail, and it is dimmer and shorter-tailed near the edges of its window than at perihelion.
Watch across the apparition — a few world days at a time — and confirm it moves against the stars along its own track, brightens toward perihelion, and fades again, rather than appearing and vanishing at full strength.
Check the tail direction against the sun: expected result: it points directly away from where the sun is, not along the direction the comet is travelling, and it swings around as the comet passes perihelion. Comparing an evening apparition with a pre-dawn one is the clearest test.
Sight the comet with the Sextant; expected result: it reads as <name> · comet with an altitude, and it keeps its name with no book in the left hand.
Hold the Astrolabe and middle click past the planets; expected result: every comet is listed, one that is away reads away, returns in N days, and scrolling the forecast past that point turns the line into a real compass bearing and altitude.
Run .stars render comets off during an apparition; expected result: the comet and its tail stop drawing while the stars, planets and meteors keep going, and .stars render lists comets=off.
Confirm the coma and the tail stay joined while the sky turns: watch for several minutes without moving; expected result: the tail stays attached to the comet rather than drifting off it.
Put a blank normal book in the left hand and keep ink and quill in inventory.
Use .stars list before drawing; expected result: no saved constellations for the held book.
Scope with the Brass Telescope, switch to Draw mode, and drag from one visible star to another; expected result: a constellation segment is written into the held book and the naming dialog opens.
Build a known authored sky-culture constellation with .stars build Ori.
Run .stars list and .stars info selected.
Confirm .stars info includes ID, star count, segment count, month window, season summary, and state.
If the constellation state is not below horizon, look toward its stars while holding the written book in the left hand and confirm saved segments render in the sky.
Rename and delete the constellation with .stars name <id> <text> and .stars delete <id>.
Watch the sky for several in-game hours and confirm stars rise in the east and set in the west, in the same direction the vanilla sun travels.

Seasons And Sky Exposure

Set the calendar to about the 19th of December at midnight and sight Betelgeuse (Orion's shoulder); expected result: it is due south, high on the meridian, as it is in the real December sky. On the equivalent late-September night it must be nowhere near the meridian at midnight.
Set the calendar to the equinoxes and solstices and confirm the constellations overhead at midnight match the season the game itself reports, not one a quarter of a year away.
At night, stand outdoors under open sky and confirm stars, the coordinate grid and constellation lines all draw.
Step under a tree, a porch, or an overhang; expected result: the sky still draws.
Stand indoors, well back from a window or an open door, and look out at the sky through it; expected result: the stars are visible through the opening and nowhere else. This is the case that has broken twice — once by a rain-map check, once by a light-level threshold.
Look at the walls, floor and roof from that same spot; expected result: no stars through any of them.
Go deep into a cave with a torch; expected result: no stars in any direction, and .stars debug reports skyExposure=blocked with sunlightAtEye=0.
Run .stars debug in each of those spots; expected result: the reported verdict matches what you can actually see, and is what to quote in a bug report.

Performance

Watch the frame time (F3) at night under open sky with the full star catalog, then sprint through unloaded chunks for a minute; expected result: no repeating stutter tied to the sky pass and no lag spikes as chunks load.
Play a full night, then check the client's memory in the task manager the next in-game day; expected result: it settles rather than climbing all night.
Check client-main.log after several minutes of play; expected result: no recurring AstraTerra sky step lines (those belong in the debug log now), and no OpenAL or sound-loading errors appearing alongside them.
Hold a written constellation book in the off-hand at night and compare frame time with and without it; expected result: no measurable difference, and the lines look exactly as they did — same dot spacing, same colours, same fade near the horizon.
Scope the telescope while the book is held; expected result: the constellation lines stay a fine trail of dots rather than swelling into blobs as the view magnifies.
Draw a new constellation segment while lines are on screen; expected result: it appears immediately, without the existing lines flickering.
Compare star colour against the previous build, side by side on the same night and latitude: batching applies a star's tint once where the old path applied it twice, so warm stars (Betelgeuse, Antares) should read slightly more saturated. Confirm the sky still looks like the mod's sky rather than a christmas tree; this is the one part of the batching work that numbers cannot judge.
Sight a planet with the telescope; expected result: it still resolves into a disc, and Venus still outshines everything around it.
Put a Star Catalog book in the off-hand; expected result: the slot accepts it. If it does not, check client-main.log for journal books allowed in the off-hand and for the mod loading at all.
Run .stars render at night; expected result: it lists every path as on.
Run .stars render constellations off; expected result: the lines vanish, the stars, planets, meteors and any scoped deep-sky plates keep drawing, and the next AstraTerra sky cost line in the debug log shows constellations=off with fewer draw calls per frame.
Switch stars off as well; expected result: an empty sky, and the reported milliseconds per frame fall to near zero — that is the projection being skipped, not just the draw.
Run .stars render all on; expected result: everything returns.
Restart the client; expected result: every path is on again, because the toggles are a diagnostic and are deliberately not saved.
Set .stars sky-grid none, hold right click with the Sextant, and confirm the on-screen angle above horizon updates for a centered visible star with no grid initially. Middle click repeatedly and confirm the display cycles through rose equatorial, cyan azimuthal, both, and angle-only. Release right click and confirm the saved no-grid setting is restored.
In daylight, hold right click with the Sextant and sight the sun; expected result: the readout names Sun and shows its angle above the horizon, with no star reading offered.
With a daytime lit moon above the horizon, sight it and confirm the readout names Moon and reports a plausible angle.
At new moon while the moon is above the horizon, aim at its position and confirm the Sextant does not offer a Moon reading; repeat at full moon and confirm that it does.
Sight the sun near sunrise or sunset and confirm the reported angle approaches zero as it meets the horizon.
Point away from every body and confirm the readout lists what is available to aim at rather than reporting stars are not visible.
With the star catalog asset missing or failing to load, confirm the Sextant still sights the sun and any lit moon, and offers only whichever of those two are available.
Hold the Astrolabe steady for a minute of world time and confirm the clock line advances without the frame rate dropping; the sky clock is cached per world minute rather than recomputed each frame.
Hold a freshly crafted Calibrated Astrolabe and hold right click; expected result: it reads no plate and refuses to place anything, whatever book is in the left hand.
Sneak and hold right click under open sky at night; expected result: a bar fills over about three seconds and the readout then shows a plate at your latitude.
Repeat indoors, and again in daylight; expected result: the bar stays empty and the readout names the obstacle — cover in one case, a too-bright sky in the other. Step out from under the roof without releasing the button; expected result: the bar starts filling from empty rather than jumping.
Release the button halfway through; expected result: no plate is cut and the next attempt starts from zero.
On a dedicated server, cut a plate and then rejoin; expected result: the plate survives, because the server wrote it to the itemstack.
Drop a cut astrolabe and pick it up, or hand it to another player; expected result: the plate is unchanged and still reads the latitude it was cut at, not the new holder's.
Hold the written constellation book in the left hand and the Calibrated Astrolabe in the main hand.
Hold right click and confirm the astrolabe shows latitude, world day, compass direction, altitude, motion state, and time until transit for a recorded constellation.
Confirm the astrolabe's clock line shows the hour, the phase of the day, the sun's angle, and the time to the next sunrise or sunset, and that the hour agrees with the game's own clock.
Scroll the forecast forward and confirm the clock line advances with it, and that the phase changes from day to dusk to night at the appropriate hours.
Hold the astrolabe with no book and confirm the clock line still shows.
Middle click and confirm the astrolabe cycles through only the constellations in the held book.
Scroll and confirm the forecast moves by one hour; sneak-scroll and confirm it moves by seven days, never earlier than now or later than one world year.
Repeat the astrolabe check indoors or during daylight and confirm planning remains available.
At a high latitude, confirm the astrolabe distinguishes a circumpolar constellation from one that never rises.
At an extreme latitude during a polar day or night, confirm the astrolabe reports that the sun does not set or does not rise instead of showing an hour.
Travel a few degrees of latitude from where the plate was cut; expected result: the readout says how far north or south of the plate you are, and the altitudes and transit times still answer for the plate rather than for where you stand.
Travel more than eight degrees; expected result: the readout asks you to recut the plate, and still reads rather than going blank.
Recut the plate there; expected result: the drift note disappears and the readings change to the new latitude.
Confirm the clock line does not drift with the plate: at a longitude far from where the plate was cut, the hour still agrees with the game's own clock.

Creative Inventory

Open the creative inventory and select the AstraTerra tab.
Confirm Brass Telescope, Precision Telescope, Sextant, and Calibrated Astrolabe are present and can be dragged into the player inventory.
Confirm Star Catalog and The Zodiac appear on the same tab and can be dragged without using /stars give-catalog or /stars give-zodiac.

Authored Constellation Build

As an administrator with the give privilege, run /stars give-catalog; expected result: a written book titled Star Catalog is added to the inventory with 88 named constellation entries.
Put Star Catalog in the left hand, run .stars list, and confirm all 88 authored constellation names are present. Confirm the sky overlay and Calibrated Astrolabe can use the catalog without ink and quill.
Run /stars give-zodiac; expected result: a written book titled The Zodiac is added to the inventory with 12 entries ordered Aries, Taurus, Gemini, Cancer, Leo, Virgo, Libra, Scorpius, Sagittarius, Capricornus, Aquarius, and Pisces.
Put The Zodiac in the left hand and confirm .stars list, the sky overlay, and the Calibrated Astrolabe use only those 12 constellations. Confirm Ophiuchus is not included.
Run .stars build Ori; expected result: a selected constellation named Orion.
Run .stars build UMa; expected result: a selected constellation named Ursa Major.
Run .stars build UMi; expected result: a selected constellation named Ursa Minor.
Run .stars build Vir, .stars build Sgr, or another zodiac IAU code; expected result: a selected named constellation using authored sky-culture segments.
Run .stars build Missing; expected result: command reports that the authored constellation was not found and does not mutate the journal.
Confirm visible authored constellation segments fade out near the visual horizon and do not end in a hard line above terrain.

Latitude Scenarios

Use .stars debug after each teleport to confirm the mapped latitude.
If the latitude target is under 24-hour daylight, use .stars daylight-stars on.
Vintage Story controls latitude from world climate settings. Do not assume fixed /tp coordinates are equator or pole in every save.
Use .stars goto-lat <degrees> to move to the nearest map position matching the requested latitude.
Equator target: debug latitude near lat=0.
Mid-latitude north target: debug latitude near lat=45.
Near-polar north target: debug latitude near lat=80 to lat=90.
Mid-latitude south target: debug latitude near lat=-45.
Equator: confirm both hemispheres become available as the player crosses latitude zero.
Mid-latitude north: confirm circumpolar behavior and expected seasonal drift.
Mid-latitude south: confirm southern sky inversion and season labels.
Near-polar: confirm low-elevation dimming and below-horizon classification.

Persistence

Save and reload after selecting a constellation and changing telescope mode/zoom.
Confirm the constellation journal persists.
Confirm selected constellation, last mode, and zoom are restored from the per-world client state file.
Put invalid JSON in a written book's astraterraJournalJson attribute, then try to draw a segment. Expected result: the edit is refused with an overwrite-protection message, the attribute is unchanged, and the server log identifies the book title and JSON length without printing its contents.

Multiplayer

Observation state (telescope scope, sextant reading, astrolabe planner) lives in process-wide statics that drive the local HUD, so it must never be set by another player's interaction. The hosted-world case is the one that catches regressions, because a hosted world runs its server inside the host's own client process — a dedicated server hides the bug, since nothing in that process draws.

Host a world from the game client ("open to LAN" / uPnP) and have a second player join.
As the joining player, hold right click with a Brass Telescope; expected result: the host sees no scope overlay and no field-of-view change. Repeat with the host scoping and the guest observing.
Repeat both directions with the Sextant; expected result: the other player gets no angle readout.
Repeat both directions with the Calibrated Astrolabe; expected result: the other player gets no planning readout.
With both players scoped at once, confirm each sees only their own zoom level and mode, and that scrolling zoom on one does not move the other.
Repeat the telescope check on a dedicated server with the two players standing next to each other, to confirm a nearby player's interaction does not open the local overlay.

Vanilla Calendar Suppression

With the default settings, open the character panel (C); expected result: the Environment box reads Date: <day>. <month>, Year <n>, <hh>:<mm>, exactly as vanilla writes it.
Run .stars calendar clock, close and reopen the character panel; expected result: the date line reads Date: unreckoned, <hh>:<mm> — the hour survives, the day, month and year do not.
Run .stars calendar none and reopen it; expected result: Date: unreckoned, with no time at all.
Confirm ModConfig/astraterra.json has CalendarDisplay set to the chosen value, restart the client, and reopen the panel; expected result: the setting held.
In a single-player world with cheats on, run /time while the display is set to none; expected result: the server still answers with the real date. Only the client's own display is redacted.
Run .stars calendar full; expected result: the vanilla date comes straight back.

Identifying A Wanderer

Scope in with a telescope in Observe mode, centre a planet, and press sneak; expected result: nothing happens — no chat message, no journal entry, no name prompt. The old one-press identification is gone, and sneak in Observe mode is inert.
Sight the same planet with the Sextant on two different nights (sneak while sighting, book in the left hand, ink and quill carried); expected result: two dated entries, neither naming a body.
Run .stars sightings; expected result: the two entries are gathered into one set with the distance between the nights reported.
Run .stars classify set wanderer with no name; expected result: the conclusion is written down, the response says your instruments call it that from now on, and the name dialog opens.
Name it, then check the Astrolabe lists it under that name with provenance from 2 sightings.
Run .stars classify set wanderer Ares on the same entries; expected result: the claim is replaced rather than duplicated, and the name changes everywhere.
Load a save made before this change that has planets identified the old way; expected result: they still name and aim, reported as recorded without sightings — low confidence until re-observed.

Result Log

Equator: pass in manual in-game check; starfield and authored constellation orientation looked correct.
Starfield comparison: use .stars starfield both to inspect alignment, then verify vanilla hides AstraTerra stars and astraterra hides the vanilla cubemap without restarting.
Star size comparison: with .stars starfield both, confirm typical AstraTerra stars are similarly compact to the vanilla points and that only the brightest catalog stars have a modest outer glow rather than a dominant disc.
Polaris comparison: with .stars starfield both, compare Polaris to a similarly bright vanilla point; confirm its core is no longer undersized while magnitude-six stars remain compact.
Deep-sky registration: scope a Stellarium-backed object such as M42 and confirm catalog stars embedded in the image coincide with AstraTerra stars across the full image, including its rotation and non-square footprint.
Coordinate grids: use .stars sky-grid horizontal and confirm the cyan horizon stays at altitude 0° while its cardinal meridians meet at the zenith. Use equatorial and confirm the rose celestial equator and hour circles rotate with time while remaining aligned with catalog stars. Use both to compare the frames, then restore none.
Mid-latitude north: not run in this automated pass.
Mid-latitude south: not run in this automated pass.
Near-polar: not run in this automated pass.