AstraTerra Command Reference
AstraTerra registers a stars command group on both sides, and Vintage Story's own prefixes decide
which one you get.
| Prefix | Runs on | Commands |
|---|---|---|
.stars |
your own client | everything about the book in your hand, the sky you are looking at, and the client's own settings |
/stars |
the server | debug, goto-lat, give-catalog, give-zodiac, give-wanderers |
.stars debug and /stars debug both exist and report the same kind of thing from their own side.
Everything else appears under one prefix only, so a command that answers no such command is
usually being typed with the wrong one.
The server commands need privileges: chat for the group, tp for goto-lat, and give for the
three book commands.
Player Commands
.stars list
.stars info <id|name|selected>
.stars name <id|selected> <name>
.stars select <id|name>
.stars delete <id|selected>
.stars credit <constellation|wanderer> <id|selected|name> [discoverer]
All of these read and write the constellation book you are holding in either hand — off-hand first, then main hand; without one they say so. Mutating commands also need ink and quill in your inventory.
.stars info selected, run after drawing or selecting a constellation, gives its star count, segment
count, best visibility window, season summary, and current state.
Sightings
.stars sightings lists every sighting written down in the book you are holding, then gathers them
into the sets it thinks are the same body and says what comparing each set shows — whether it held
its place, or how far and how fast it moved.
The book does the arithmetic and stops there. .stars classify is where you say what a set was:
Calling a set a wanderer does one more thing. Your own entries are looked up against the wandering bodies, and if exactly one of them was in all of those places on all of those nights, the conclusion binds to it: your name for it is what the Sextant and the Astrolabe call it from then on. If two bodies fit, or none do, the conclusion still stands but nothing is bound — sight it again and the record will settle.
A bound wanderer is written down with the name of whoever found it, and the book's page says so:
- Oakchild — found by Astra. The credit stays with the first observer to pin that body, so a book
that is handed on, and renamed by its new owner, still says whose work it was. Books written before
this, and prepared books nobody in the world discovered, simply have no line to show.
The same is true of a figure you draw: the book records who drew it, .stars info reports it, and
the page reads - Lantern: stars=6; segments=5; drawn by Astra. Joining two existing figures with
one segment leaves the credit with whoever drew the older of them, and splitting a figure leaves
every part credited to the same person, so no single line can take somebody else's work.
Credit
.stars credit constellation 3 Astra
.stars credit constellation selected The Sanguine Expedition
.stars credit wanderer Oakchild Astra
.stars credit wanderer Oakchild
.stars credit writes down who found something, in your own words. Any name is allowed: a friend
who has stopped playing, a whole expedition, somebody who never existed. Nothing is checked against
who is on the server, because the book is a record of what its writer believes rather than of what
the game observed. Leave the name off to credit nobody and clear the line.
A constellation is addressed the way it is everywhere else — by id, by name, or as selected. A
wanderer is addressed by the name you gave it, which is the only name the book ever shows for one.
The discoverer runs to the end of the line, so a name with spaces in it needs no quotes.
Nothing checks your answer against the sky, and that is deliberate: a classification the game has already graded is a quiz, not a discovery. Being wrong is allowed, and you find out the way an observer does — by sighting it again and watching your own numbers stop making sense. Changing your mind rewrites the conclusion and leaves every sighting it rested on untouched.
Authored Constellations
Examples:
The current authored set includes all 88 Modern IAU constellations. Built constellations are saved into the held constellation book like hand-drawn constellations.
See the Constellation Build Cheat Sheet for every supported code and a copyable command list.
Administrators with the Vintage Story give privilege can create a ready-made test book containing all 88 patterns:
The same Star Catalog and The Zodiac books also appear on the AstraTerra creative inventory tab, so creative-mode players can drag them without using a command.
The command adds a written book titled Star Catalog to the caller's inventory. Hold it in either hand to show every authored constellation or use it with the Calibrated Astrolabe. This admin setup command does not require ink and quill.
To create a smaller book titled The Zodiac containing the traditional twelve zodiac constellations in sign order, run:
This book contains Aries, Taurus, Gemini, Cancer, Leo, Virgo, Libra, Scorpius, Sagittarius, Capricornus, Aquarius, and Pisces. Ophiuchus is not included in the traditional twelve-sign set.
To create a book titled The Wanderers, which already names all five planets the way our own sky culture named them, run:
Planets are otherwise anonymous: without a book that names them, every instrument calls a planet a wandering star, because that is all it looks like from the ground. This book is somebody else's finished work — handy for testing and for creative play, and a shortcut past identifying each planet yourself. Hold it in either hand and the Sextant and Astrolabe will use its names.
The Vanilla Calendar
Vintage Story writes the day, the month, the year and the hour into the Environment box of the character panel. That is every single thing the Sky Disc spends a world year measuring, available free from your first night — which makes the disc decoration rather than an instrument.
calendar decides how much of it stays. full is the default and changes nothing. clock drops the
date and keeps the hour, which the sun gives away anyway. none gives neither, and the sky becomes
the only calendar you have. In place of the date the panel says unreckoned, so it is clear that
nothing is broken — nobody is keeping the count for you. Reopen the character panel to see a change,
and the choice is saved in ModConfig/astraterra.json.
This only touches what your own client displays. An administrator asking the server the time with
/time still gets a straight answer.
The Hour, And Where You Stand
There is no command for this one — it is two settings in ModConfig/astraterra.json, because on a
server the sun is not a per-player choice.
LongitudeAwareSun decides whether world X acts as longitude at all. Left on, the sun, the daylight,
the star field and every instrument shift east and west together, about one hour of sky per 8,300
blocks. Set to false, the world keeps Vintage Story's single time zone and the whole sky falls back
with it. The server's copy of this setting wins and is sent to every client.
DisplayedClockTime decides which hour you are shown: local (continuous local solar time, the
default), universal (the world's own clock), or zones (rounded to whole clock hours, so a world
day divides into even time zones). The world's internal clock is universal either way — this changes
the reading, not the world.
Both keys take effect when the mod loads them, so change them with the game closed and restart. The mod rewrites the file on every start, which is how it fills in keys you have not set; a key it does not recognise is dropped when it does.
.stars debug reports the latitude AstraTerra is using and how far the sky has turned, which already
includes the longitude term.
See Longitude and the local hour in the player guide for what this changes in play, and the Configuration Reference for every other key in the file.
The Solar System's Pictures
The planets and their moons are drawn from pictures, and the mod ships two sets of them. pixel is
the default: pixel art, drawn to sit with the game's own. photo is the older set, photographs of
the real surfaces — Jupiter's belts, Saturn's rings edge-on.
Only the pictures change. Where a body is, how wide it draws, which of its moons are out and which has slipped behind it are the same either way, because both sets are cut to the same square. The one thing the photographs alone carry is a planet's phase as its own picture: they draw Venus and Mars crescent, half and full as the geometry demands, while the pixel art draws each planet the one way it is drawn.
The moon overhead is a separate setting.
The choice takes effect at once and is saved in ModConfig/astraterra.json.
The Moon Overhead
The moon you see in the sky is its own picture, independent of the planets. pixel is the default:
one surface portrait held upright while a curved shadow follows the phase and turns toward the sun.
photo uses a photograph of the real surface, so a telescope shows craters rather than a larger
smooth disc. vanilla puts Vintage Story's own moon back.
Position, phase, moonlight and the length of the night stay the calendar's in every case. Only the picture changes, or is left alone.
The choice takes effect at once and is saved as MoonArt in ModConfig/astraterra.json.
Recovery And Debug Commands
.stars comets
.stars connect <hipA> <hipB>
.stars debug
/stars goto-lat <degrees>
.stars daylight-stars on
.stars daylight-stars off
.stars starfield astraterra
.stars starfield both
.stars starfield vanilla
.stars sky-grid none
.stars sky-grid horizontal
.stars sky-grid equatorial
.stars sky-grid both
.stars render
.stars render stars|constellations|deepsky|meteors|comets|milkyway|all on
.stars render stars|constellations|deepsky|meteors|comets|milkyway|all off
connect is a recovery path for creating a segment from known HIP star IDs. debug shows latitude and sky-orientation diagnostics, including the sky-exposure verdict behind a sky that will not draw. goto-lat is a server command (tp privilege) that teleports you to a Z giving that latitude, for testing different skies in one world. daylight-stars is intended for testing and should be turned off for normal play.
starfield changes the active sky immediately and saves the choice in ModConfig/astraterra.json:
astraterrashows only AstraTerra's catalog-driven stars and is the default.bothshows AstraTerra and the original Vintage Story cubemap together for alignment comparisons.vanillashows only the original Vintage Story starfield.
comets reports every comet in the catalog: whether it is up now — with its phase through the apparition, magnitude, tail length and position — or how many days until its next one begins. A comet is the one thing in the mod you cannot check by looking up, since the rarest is due about once every seventy-five world years, so this turns the whole catalog into four lines.
render switches one part of the sky off so you can see what it costs. If the mod is making your game stutter, this is the fastest way to say which part: turn one path off, play for half a minute, and see whether it helps. .stars render on its own lists what is drawing.
Unlike starfield and sky-grid, this is not saved — everything comes back when you restart the client, because it is a measuring tool rather than a setting. The paths are stars (including planets), constellations, deepsky (the telescope's photographic plates), meteors, comets and milkyway (the galaxy's own glow behind everything else), plus all.
Every 30 seconds, AstraTerra writes what the sky cost into client-debug.log — time per frame, worst frame, draw calls, and which paths were on. If you are reporting a performance problem, that line and the path you found is exactly what makes the report actionable.
sky-grid projects debug coordinate lines over the visible sky and saves the choice in ModConfig/astraterra.json. horizontal draws the observer-local altitude-azimuth grid in cyan. equatorial draws the right-ascension/declination grid in rose and rotates it with local sidereal time. both overlays the two systems; none is the default. While using the Sextant, middle click cycles its temporary display through angle only, equatorial, azimuthal, and both without changing the saved mode.