Astral Skies — Zephyrfit

An animated astronomical sky for Valheim: catalogue stars, identifiable planets, lunar phases, a structured Milky Way and regular meteor showers. A nocturnal raid brings a full copper blood Moon, with a 15× reference-disc diameter setting by default.

0.5.6 — public beta. Nighttime ray suppression and F5 previews require in-game validation. Built for skywatching, from subtle astronomy-inspired nights to a spectacular fantasy sky. Open F8 to make it yours.

Installation

Install AstralSkies by Zephyrfit from the Valheim catalogue in Gale, then launch the modded game. BepInEx is the only declared dependency; players do not need the .NET SDK or the source kit.

For manual installation, extract the package's BepInEx folder into your existing BepInEx game installation. Keep only one AstralSkies DLL. If you previously used a local development copy, remove its mod entry before installing the catalogue release; retain BepInEx/config/com.zephyrfit.astralskies.cfg for your preferences. Dedicated-server instructions are included in SERVER_INSTALL.md.

New in 0.5.6 — console permission fix

Fix the false “enable devcommands” rejection introduced in 0.5.5. Its extra permission check incorrectly treated Terminal.m_terminalInstance as static; it is an instance property. The command now checks its actual ConsoleEventArgs.Context, and active previews check the real Console singleton. IsCheatsEnabled still runs through the game's native method, including installed permission patches. Cheat and admin flags remain enabled; no permission bypass or extra dependency is added. A regression test with the correct instance-property API fails on the old code and passes after this fix. Runtime verification in Valheim remains necessary. Install on the client; a 0.5.4+ server remains sufficient for the unchanged storm sea.

New in 0.5.5 — nighttime rays and console previews

The native SunShafts effect is now suppressed on ordinary nights too, with a smooth dawn/dusk transition; daytime solar rays return normally. Total solar eclipse coverage also suppresses it. This targets the long cones reported around bright planets and the Pleiades. Planet brightness, colors and compact halos are retained. The screenshot is consistent with radial post-processing, but the specific cause and this fix still require native-renderer confirmation. Blood-moon sea/wind code is unchanged; the user reports the 0.5.4 storm waves work well in game.

With the console enabled and native devcommands permission, use:

Duration defaults to 60 seconds, range 5–600. Commands respect Valheim's native cheat/admin checks; they do not enable cheats or bypass multiplayer permissions. On a dedicated server, your existing command tooling/permissions must allow native cheat commands. No AstralSkies remote administration RPC is added.

These are local render previews, not shared server events: no raid is spawned, no storm waves are triggered, and world time, calendar and saved settings are not changed. Keep Moon/coherent cycle enabled, and enable eclipses for solar/lunar or local blood visuals for blood. Wait for sky loading. Test away from the horizon; solar requires daytime, lunar/blood require nighttime. A real raid blood moon wins over eclipse previews. Previews stop on timeout, day/night mismatch, world change, permission loss, feature disable or plugin disposal. A localized banner identifies the test. They hold a forced alignment, not an entire eclipse contact sequence.

Install 0.5.5 on clients for these changes. A 0.5.4 server remains sufficient for shared blood-moon storm sea. Four languages include command help and test messages.

New in 0.5.4 — precise reticle picking

Replace the large 2.5-degree identification cone with screen-space hit testing. Star selection follows the visible core plus a small pixel margin; guide lines have their own narrow tolerance. Sizes account for viewport resolution, camera projection and configured star size. A line away from a stellar core identifies its constellation or asterism instead of a nearby star.

At the Summer Triangle's corners, Vega focuses Lyra, Deneb Cygnus and Altair Aquila. Member-star captions also show their actual constellation when guide names are enabled. Big Dipper stars belong to Ursa Major; shared Alpheratz belongs to Andromeda. Galaxy labels remain single object names. Catalogue positions, lunar lighting and the astronomical calendar are retained.

Storm sea during blood moons is enabled by default. The server option BloodMoonStormSea uses the native maximum wind target, retaining the weather's wind direction and Valheim's normal transitions, waves and buoyancy. This also affects sailing wind. It does not force rain, clouds or a storm weather preset. The most recent natural wind target is restored when the nocturnal blood moon ends, on disabling the option, or on leaving the world. Explicit admin debug wind has priority. Hiding the blood Moon locally does not disable shared wind.

Install 0.5.4 or later on the server and all clients for this feature. Older servers remain compatible with the sky changes but do not enable storm sea. To disable it, stop the server, set BloodMoonStormSea = false under [6 - Server] in BepInEx/config/com.zephyrfit.astralskies.cfg, then restart. Local hosts can also use the F8 toggle. No eclipse-forcing console command is included.

New in 0.5.3 — clearer identification and blood-moon rays

Reticle labels distinguish Star, Constellation and Asterism in all four languages. Orion's main stars show their familiar names and Bayer aliases, e.g. Alnitak (ζ Orionis); Aldebaran shows α Tauri. French Bayer-only labels use Greek symbols and French constellation names consistently. Highlighting the whole figure still helps locate it; it does not turn an individual star into a constellation.

During a local blood moon, the native SunShafts image effect fades to zero to address the large white cones seen in the reported raid screenshot. The scope surrounds the image-effect call and restores its intensity even on errors, preserving later writes by other mods. Normal sky, lunar texture, circular halo and saved graphics preferences are retained. This targets a plausible source of the artifact; disappearance of the reported cones has not yet been confirmed in a live renderer. No server update is required from 0.4.4 for these client changes.

New in 0.5.2 — completed figures and eclipse rendering

Orion, Cygnus, Gemini, Aquila, Draco, Cepheus, Lyra and Leo now include their missing chart branches. Orion also gains a three-star sword guide. The original BSC5P positions remain unchanged; 178 stars can be identified in EN/FR/RU/ZH. The Grand Chariot remains the seven-star asterism, not the entire Ursa Major.

Solar eclipses use an opaque foreground silhouette without a bright lunar-surface overlay. Ordinary glare fades with coverage; totality also dims the cached ambient probe and available native environment shader globals. Settings and orbital timing are preserved. These changes are offline-tested; native Unity validation is pending.

Chart accuracy and clear identification (0.5.1)

Taurus, Pegasus and Andromeda now include the missing branches from the IAU / Sky & Telescope charts. Measured star positions and angular separations stay unchanged. Figures are chart conventions, not official constellation boundaries. M31 is labelled Andromeda Galaxy (M31), without repeating the constellation. See THIRD_PARTY_NOTICES.md for the CC BY 4.0 chart-derived data credits.

Sky guides and four languages (introduced in 0.5.0)

• Fixed Cygnus: the wing now reaches Epsilon Cygni; Eta Cygni follows the neck.
• 14 figures: Big Dipper, Cassiopeia, Orion, Cygnus, Ursa Minor, Draco, Cepheus, Lyra, Aquila, Taurus, Gemini, Leo, Pegasus and Andromeda.
• Optional Summer Triangle, separately enabled; it is an asterism, as is the Big Dipper. These are simplified teaching figures, not constellation boundaries.
• 178 identifiable stars, using proper names, Bayer or Flamsteed designations.
• Background guides default to 25% brightness. Aim for one second to highlight a whole figure; at 0%, only the targeted figure is shown. Requires guide display, reticle identification and highlighting. Anchor-only mode remains available.
• English, French, Russian and Simplified Chinese, selected exclusively via Valheim's Localization.GetSelectedLanguage(), including changes while playing.
• External UTF-8 dictionaries beside the DLL in Translations/AstralSkies/: English.json, French.json, Russian.json, Chinese.json. All four are also embedded in the DLL. No additional translation plugin is required.
• Missing files use embedded dictionaries; invalid files and missing/empty keys fall back to English. Embedded English remains the final safety net. Format parameters and colour tags are validated. User-authored text is not translated.
• Fonts prefer compatible loaded game fonts, with installed Unicode/CJK font fallbacks. Buttons, descriptions, labels and banners wrap to their content.

These changes are client-side and do not change the raid network protocol. Install this version on each client that wants the new guides/languages. Live Valheim font rendering and visual appearance still require in-game checks.

Introduced in 0.4.4 — copper raids

Raid darkness now has gentler limits, including for saved 0.4.3 values. Copper colouring preserves RGB luminance, recolours cached ambient lighting, and temporarily warms the GPU Milky Way, its radiance and particles. The original palette returns after the raid. The classic Moon surface and star/planet colours are unchanged.

In F8 → Details, use Apply coherent copper atmosphere to set copper on, strength 65%, darkening 20%, leaving Moon size, palettes and local opt-out unchanged. Existing preferences are otherwise retained. New profiles default to 20% darkening; 0% keeps normal exposure/intensity. The slider represents effect strength, not the percentage of total light removed. At maximum, raid multipliers retain 80% ambient lighting, 70% directional intensity and 45% sky exposure. This is not a guarantee of scene brightness in every biome/weather or other mod. Runtime visual verification remains necessary; no server update is required.

Introduced in 0.4.3 — blood Moon controls (darkness revised in 0.4.4)

F8 → Sky → Show blood Moon for me disables the raid Moon, copper tint, darkening and raid notice for this player, with a smooth visual transition. The server still controls raids and their shared blood-Moon signal; no server update is needed for these local controls.

F8 → Details → Blood Moon darkening ranges from 0–100%, default 20% for new profiles. It dims sky exposure, ambient light/fog and the main directional light, separately from copper colouring. 0% retains normal lighting. The normal Moon asset, local point lights and game clock are unchanged. Scoped changes are restored after each camera; engine compatibility still requires in-game verification.

Show blood Moon notice enables the banner. Mythic wording: Hati’s shadow chooses its text; it does not enable the notice itself. Both require local raid visuals to be enabled. Observation explains the current signal and any local raid differing from the server event.

Nighttime raids only: a daytime raid does not trigger a blood Moon or force night. A daytime screenshot therefore cannot validate copper blood-Moon effects. Settings persist after restart and in both favorites. UI languages: English, French, Russian and Simplified Chinese; other game languages use English.

New in 0.4.2

Milky Way brightness and Dawn / dusk warmth now both range from 0 to 3. Changes apply live in the GPU renderer, persist automatically and are included in both favorites. Existing settings and defaults are preserved. Dawn/dusk warmth requires Enhanced daytime sky and a compatible native sky shader. These are local visual controls; no server update is needed for the two expanded limits.

Introduced in 0.4.1

Milky Way width ×0.5–5, radiance 0–300%, particle strength 0–5, and Andromeda/Pleiades glow ×0.2–5. New saturation 0–300% changes Milky Way colours, radiance and particles; 100% preserves the original palette. Brightness changes light intensity; width changes the band's extent. Diffuse-object glow affects only Andromeda and the Pleiades, visible at night above the horizon. These live GPU settings persist locally and in both favorites. The existing Language selection now supports EN/FR/RU/ZH as described above. No server update is required for these 0.4.1 visual controls. In-game visual checks remain pending.

Introduced in 0.4.0 (initial ranges)

• Astral Panorama / Panorama astral: a built-in preset based on the author's demonstrated settings: Sun 6.2, Moon 15, halo 10.2, daytime brightness 0.6, Amethyst galaxy and clear panorama. Quality, UI and unshown values stay independent.
• Milky Way controls: width 0.5–3, structure contrast 0.3–3, diffuse radiance 0–200%, extra faint stars and optional slow fantasy particles. GPU only; stored in both favorite slots. New effects default to off and width/contrast to 1.
• Opt-in eclipses: linked Sun/Moon apparent size 1–15 with lunar variation ±5.5%; independent classic sizes are retained and return when disabled. Larger sizes prolong/widen contacts. This is a fictional equinoctial calendar.
• Solar eclipses: actual disc overlap, dark lunar silhouette, dimmed atmosphere and light, corona near total coverage, some star visibility near totality.
• Lunar eclipses: a moving curved umbra and copper shading on the existing lunar surface. No replacement of the classic Moon asset or its normal shading.
• Observation: eclipse coverage, approximate upcoming alignment windows and an optional local start banner. Windows are not a guarantee of visibility: horizon, weather, personal sizes and time overrides matter.
• Raids retain priority: eclipse effects pause through raid transitions; the raid Moon keeps its separate 1–40 diameter. No raid or clock changes.

Enable eclipses in F8 → Details with Coherent Sun/Moon and Moon enabled. The shared-size slider is separate from your classic Sun/Moon sliders. A server with 0.4.0 shares 6 - Server / EclipseOrbitCycles (2–24, default 6): this controls fictional nodal precession, not an exact interval between eclipses. Use matching versions for the shared calendar. Visible contacts still depend on local sizes. The new rendering has been compiled and checked offline, not certified in Unity.

Features

• 8,404 catalogue stars, rotating sky, subtle stellar colours and scintillation.
• Five moving planets with larger steady halos and distinct tints.
• Milky Way, procedural cloud/dust structure, Andromeda and Pleiades glow.
• Direct spherical sky: removes the intermediate six-face projection used by earlier releases; the Milky Way fades to zero at its outer edges.
• 14 constellation/asterism guides plus an optional Summer Triangle. Lines reveal progressively; aim at a member star or line for one second to see the name. No permanent labels. Anchors-only mode is available.
• Reticle identification: aim for one second at supported bright stars, planets, deep-sky objects or the coherent Sun/Moon. Names follow the panel theme. Solid obstacles and horizon are checked; clouds can still hide a labelled position.
• Coherent Sun/Moon cycle: a simplified equinoctial reference follows the local day clock and lunar phase. Full Moon is opposite the Sun; quarter/crescent timing shifts. The illuminated lunar side is oriented toward the Sun. Native discs are retained if the custom pass is unavailable or the option is disabled.
• Daytime sky: adjustable solar disc/halo, richer native atmospheric tint and warm dawn/dusk colours. Native biome weather, rain and clouds remain in control.
• NASA-derived lunar surface up to 2048², phase shading and faint earthshine.
• Blood Moon: synchronized raid state, 15× reference diameter default, copper halo and optional sky/fog/ambient tint. The fantasy raid Moon moves toward opposition.
• Regular meteors, softer shower onset/decay and occasional brighter gold trails.
• Personal composition: independently hide Yggdrasil/clouds, choose three themes, move/resize the F8 panel, and set visual style and graphics quality separately.

Controls and language

Click −/+ for one step, or hold: repeats start after 0.4 seconds, then one step per 0.08 seconds. Each control keeps its own step (0.1, 0.05, etc.). Leaving the button cancels the hold; release and press again to resume. Closing F8, losing focus, scrolling or changing tabs cancels it. Sliders also work directly.

Only the game-selected language is used: English, French, Russian or Simplified Chinese. Other or unavailable game languages use English. Windows language and keyboard layout are ignored. See TRANSLATIONS.md for contribution and fallback details.

Appearance controls — F8 → Details

• Sun diameter 1–15, default 3; Moon 1–15, default 3.3. Linked by default at +10%; changing the Moon slider adjusts that ratio. Unlink for independent size.
• Blood Moon 1–40, default 15, on the same reference scale as Sun and Moon. It is not multiplied by the normal lunar diameter. Sun halo 2–15, default 2.
• Daytime brightness 0.1–3 and tint saturation 0–3 are independent, with neutral values of 1. Requires Enhanced daytime sky and native shader support. Saturation changes the atmospheric tint, not a full-screen colour grade.
• Five artistic Milky Way palettes: Neutral, Boreal Blue, Copper, Amethyst, Emerald. Live GPU controls; catalogue star colours stay independent.
• Planet colour emphasis 0–2: white / natural-inspired / enhanced. Copper Mars, ivory Venus, pale golden Saturn; restrained coloured outer halos around bright cores. These are display tints, not calibrated photometry or resolved planets.
• Favorite 1 / Favorite 2: Save, Load or Overwrite visual settings including palettes and planet colours. Stored locally across game/PC restarts. Quality, interface and server parameters stay independent.

The new disc scale uses new configuration keys, so upgrading adopts the requested 3 / 3.3 / 15 defaults and halo 2 once; other preferences are preserved. Subsequent edits persist. Legacy size keys no longer drive these controls.

Local preferences and quality

F8 → Details offers Subtle / Immersive / Spectacular / Astral Panorama visual presets. All values remain editable. Presets preserve quality, interface and blood-Moon diameter. Settings save automatically to the local Gale/BepInEx profile and survive game and PC restarts. Different players can choose different looks. Characters sharing one local profile share its settings; there is no per-character cloud sync.

Select a level, then Apply quality — reload sky in F8 → Details. A brief loading pause is possible. F8 distinguishes the active and selected levels. Selection is saved and also takes effect on the next launch.

The GPU field now draws spherical geometry directly at the game's rendering resolution. There is no intermediate six-face sky texture or 4K cube allocation. Quality changes actual mesh detail and Moon sampling, not the game resolution. High and Ultra deliberately share the same 2048² Moon; a small lunar disc may show little visible resolution difference. No FPS or VRAM promise is made. The static CPU emergency fallback still uses a cube capped at 1024².

At default server rate and local density, base meteors launch every 10 world seconds at night. Additional shower launches occur during 40-second windows in 120-second cycles. Tracks can be outside the camera view. Server rate zero disables all streams; matching local densities are needed for matching client schedules.

Build from source / local Gale installation

The separate source kit includes INSTALLER_AstralSkies.cmd. Extract the whole kit, close Valheim and run it to rebuild against your installed Unity/BepInEx libraries and register a local mod in Gale. Building requires .NET SDK 8+. Game and BepInEx libraries are not redistributed.

Realism and compatibility

Star data and lunar source imagery are real; brightness, sizes, galactic structures, halos and event density are artistic enhancements. The solar/lunar cycle is an adaptation to Valheim, not a full terrestrial ephemeris. Optional eclipses add a simplified inclined lunar orbit and apparent-size variation; no libration or seasonal day-length simulation. Planet calculations use an approximate JPL model and a fictional world calendar. North alignment still needs verification in game. The blood Moon's size and orbital shift are fantasy.

The native atmosphere is retained. Custom sky/cloud shaders, reflections, indoor occlusion, shadows and compatibility with Seasonality need in-game checks. The new Sun/Moon pass uses the built-in rendering pipeline; disable its option to return to native disc trajectories. Stars/planets/guides remain hidden at midday except for the optional near-total solar eclipse effect. No enemy spawns, raids, time progression or weather presets are rewritten.

See LISEZMOI_FR.md, TEST_PLAN.md, VALIDATION.md and THIRD_PARTY_NOTICES.md. The icon is promotional artwork; the lunar asset preview is an offline data check, not a gameplay screenshot.

Assistance — Zephyrfit

Available on Discord — zephyrfit for installation help, troubleshooting, bug reports, improvement suggestions and help from external contributors. Include mod/game versions, reproduction steps, BepInEx/LogOutput.log, and installer logs when relevant.

Présentation française

Astral Skies 0.5.4 enrichit les journées et les nuits de Valheim : étoiles réelles, planètes identifiables, Voie lactée, constellations progressives, phases lunaires et étoiles filantes. Le cycle Soleil/Lune proposé suit l’horloge du jeu : pleine lune opposée au Soleil et horaires décalés pour les autres phases. Lors d’un raid nocturne synchronisé, une lune de sang de taille 15 et une ambiance rouge cuivrée réglable donnent un signal commun aux joueurs équipés.

L’apparence reste personnelle : préréglages Sobre, Immersif, Spectaculaire, quatre qualités graphiques applicables en jeu, ciel sphérique direct, interface F8 déplaçable et réglages sauvegardés automatiquement dans le profil local. La Lune utilise une surface NASA recalculée jusqu’à 2048². La résolution maximale ne garantit pas un gain perceptible ni un niveau de performances donné.

Bêta publique. Dans Gale, chercher AstralSkies — Zephyrfit, installer puis lancer le jeu moddé. Aucun SDK nécessaire pour jouer. Pour la lune de sang commune, installer aussi la même version sur le serveur. Les joueurs sans le mod gardent leur ciel d’origine. La compatibilité avec les autres modifications de ciel et les performances selon les configurations restent à évaluer.

Je suis disponible sur Discord — zephyrfit pour l’assistance, la résolution de bugs, vos suggestions d’amélioration et les propositions d’aide tierce : code, tests, traductions ou compatibilité.

Développé par Zephyrfit.