AstraTerra replaces Vintage Story's night sky with a catalog of 5,044 stars, 50 deep-sky objects, five planets, nine annual meteor showers, and four returning comets. The sky turns with the hour, changes with the season, and tilts as you travel north or south. Vintage Story 1.22+.
The instruments are the actual game. Mark a year of sunrises on a Sky Disc. Measure a light above the horizon with a Sextant, write the reading down, and work out what moved. Draw constellations into a book through a telescope. Cut an astrolabe plate for your latitude and use your own records to plan another observation.
AstraTerra is still alpha. Some models, recipes, and bits of UI are placeholders. If a borrowed asset is missing from the third-party notices, please open an issue so we can fix it.
- World X now acts as longitude. Travel east or west and the sun, daylight, and star field shift together.
- The server still keeps one universal clock.
displayedClockTimecan showlocalsolar time,universaltime, or whole-hourzonesin the character panel and instruments. - Set
longitudeAwareSuntofalseinModConfig/astraterra.jsonif the server should keep Vintage Story's single time zone. - The star field now stays aligned with the visible sun on worlds with custom year lengths.
- The moon can use AstraTerra pixel art, photographic textures, or Vintage Story's original disc.
The catalog is generated from HYG v4.2, with required figure stars retained past the usual magnitude cutoff. Apparent magnitude controls their brightness and size. Fifty Stellarium deep-sky plates appear as faint smudges until a telescope resolves them. The Milky Way sits behind the catalog.
Mercury, Venus, Mars, Jupiter, and Saturn move on Keplerian orbits. Nine meteor showers return at fixed parts of the world year. Four comets have their own apparition schedules and tails that point away from the sun. Miss Halley's first pass and the next one is in world year 78. Plan accordingly.
Form a clay disc and fire it, or craft one from copper or bronze. Under open sky at sunrise or sunset, sneak and hold right click to scratch the sun's place on the horizon. Keep marking until the band reaches an edge and turns back. The finished band gives the year length, latitude, east or west, and the next solstice.
Right click reads the disc. Scroll turns it. Sneak-right-click the ground to set it down. Clay uses five-degree notches. Metal uses two-and-a-half-degree notches. The first mark binds the disc to that latitude.
Hold the disc up at night and left-drag between stars to cut one connected constellation. Keep loose flint or a knife in the hotbar. Raw clay takes the figure before firing. A fired clay disc will not.
Hold right click to use the scope. Scroll changes zoom. Middle click cycles Observe, Create Constellation, Inspect Constellation, and Remove Segment. Drawing or editing needs a writable book in the left hand plus ink and quill in the inventory. The lines and names live in that book, so another player can use it.
Planets become discs under magnification. Mars changes apparent size, Saturn has rings, and Jupiter's four Galilean moons move independently. Five of Saturn's moons are also modeled. A moon hidden behind its planet disappears until it comes out the other side.
Hold right click and center the sight on the sun, moon, a star, a planet, a comet, or a near body supplied by another mod. The readout gives altitude above the horizon. Middle click cycles the equatorial and horizontal grids.
Sneak while sighting to write the observation into a book in the left hand. Ink and quill are required. The entry records the angle, bearing, brightness, position, and time, but not the identity of the target. .stars sightings groups repeated observations. .stars classify <set> star|wanderer|comet [name] records your conclusion.
Sighting the sun currently costs you nothing. A real navigator would use a shade glass.
Recover a ruined astrolabe and fit it with a brass plate. After dusk, stand under open sky and sneak-hold right click to cut the plate for that latitude. Travel far enough and it asks to be recut.
With a written book in the left hand, hold right click to plan an observation. Middle click changes target. Scroll moves the forecast by an hour. Sneak-scroll moves it by seven days. The readout gives direction, altitude, rising or setting, and next transit. It also says what the answer rests on: your sightings, the stars in a recorded figure, or the comet almanac.
Press Z to lie on your back. Move, jump, or press Z again to stand. The binding is remappable under Controls > Lie down, and the instruments still work while you are on the ground.
Pixel art is the default for planets and the moon. Use .stars solar-system photo for photographic planet textures. Use .stars moon pixel|photo|vanilla for the moon. These settings change pictures, not positions, phases, or orbits.
AstraTerra also exposes a near-body API for worlds that orbit something larger. A companion mod can place a parent planet and sibling moons in the sky, shade them from the real sun direction, and make them valid Sextant targets. AstraExtera uses that API.
.stars calendar full|clock|nonecontrols how much of Vintage Story's date and hour appears in the character panel. Hide the date if the Sky Disc should earn its keep..stars starfield astraterra|both|vanillaselects the catalog sky, both skies for comparison, or Vintage Story's cubemap..stars sky-grid none|horizontal|equatorial|bothcontrols the coordinate grid..stars solar-system pixel|photochanges planet art..stars moon pixel|photo|vanillachanges moon art..stars render stars|constellations|deepsky|meteors|comets|milkyway|all on|offtoggles individual render paths.
See the command reference for constellation, sighting, admin, and diagnostic commands.
Every change goes through tests for the astronomy math, catalogs, instruments, and saved data. CI builds against Vintage Story 1.22.2, packages the same ZIP players install, and builds the docs. Before a release, we deploy that ZIP and work through the in-game checklist after a full restart. The tests catch logic errors. They cannot tell us whether a telescope, moon, animation, or item model actually looks right.
That is why I also test each release manually on a 24 GB M3 MacBook Air with a mostly vanilla-plus set of mods I regularly use: Carry On, Butchering, Better Ruins, Blood Trail, QP Chisel, Buzzwords, Terra Pretty, Watershed, D.E.A.D., Farseer, Footsteps, Food Shelves, Hydrate or Diedrate, RealSmoke, Place On Slabs, Terrain Slabs, Tankards, Vanilla More Molds, Waterfall, and others.
I wish Vintage Story offered an easier way to automate this kind of compatibility testing. If the developers provide one, I intend to add it to this process.
Build and test:
make test
make build
make package
make docs-buildFor an in-game smoke test, run make deploy, enable AstraTerra, and follow Manual Verification.
Models, code, documentation, translations, and screenshots are welcome. Rough edges are tracked in the issue list rather than repeated here.
AstraTerra is licensed under the GNU Affero General Public License, version 3 only (AGPL-3.0-only). Third-party assets retain the licenses and attribution listed in THIRD_PARTY_NOTICES.md.
Inspired by Minecraft's Spyglass Astronomy.
The Brass Telescope model is adapted from Fuami's MIT-licensed Spyglass mod. Modern IAU constellation lines and selected deep-sky assets come from Stellarium. The Sextant model transforms and recipe are adapted from the Realistic Surveying package. Full licenses and asset notes are in THIRD_PARTY_NOTICES.md.
Thanks to LadyLioness of AdAstra, and to Rythillian, Bin, Fey_Shadow, nuwabi, itsDuskie, Dannyftm, ffish, pollo_frito_22, and LaurieIAU for testing and arguing with the sky.