Java 21 Migration
The game now builds and runs using Java 21. This means that the old v1, v2, and v3 launchers will no longer function. You must use the new v4 Launcher available here.
For Server Owners / Providers
There are updated launch scripts included in the game files. Additionally, there is a full docker setup available here.
The game now also requires special JVM arguments to run as well. Without these, the game cannot launch!
--add-opens=java.base/jdk.internal.ref=ALL-UNNAMED
--add-opens=java.base/java.nio=ALL-UNNAMED
--add-opens=java.base/jdk.internal.misc=ALL-UNNAMED
-javaagent:StarMade.jar
For example, your server's launch args might look like:
-Xmx8g
--add-opens=java.base/jdk.internal.ref=ALL-UNNAMED
--add-opens=java.base/java.nio=ALL-UNNAMED
--add-opens=java.base/jdk.internal.misc=ALL-UNNAMED
-javaagent:StarMade.jar
-jar StarMade.jar
-server -autoupdatemods
Additionally, for server hosters using -Xincgc: You must remove this argument as it is no longer valid in Java 21!
Instead, we recommend trying -XX:+UseZGC for constrained / shared CPU setups. It requires a bit more memory headroom, but can reduce GC related stalls.
Fleets & AI
Fleet Reconnaissance
A new RECON fleet command state enables fleets to scout sectors and generate detailed reports:
- Fleets can be given a RECON command with a list of target sectors and an entity filter (all / root-only / docked).
- The fleet moves through each sector, dwells to scan, and records FleetReconLog entries, while avoiding direct combat.
- Completed recon runs produce saved reports viewable from the Fleet Options GUI via a new View Reports button.
- Patrol missions now also generate recon-style logs when engagements occur and produce a summary report at cycle end.
AI Collision Avoidance & Sector Arrival
- AI ships now actively avoid collisions with other ships during travel using a dedicated avoidance steering layer.
- Sector arrival detection was fixed to prevent ships from overshooting their destination.
- Ship AI braking behavior corrected: ships now smoothly decelerate when approaching targets instead of ramming.
- Ships with at least one warhead block and no weapons will now attempt to ram enemies with their warhead, after which, they will automatically disable their ai module to prevent continued ramming with no warhead.
Patrol & Trade Improvements
- Patrol state bug fixes including integrated fleet logging for patrol reports.
- Player trade fleet movement target assignment streamlined; cargo deep-copied on fleet clone operations.
AI Changes
- Fleet membership is now cleared from an entity after a reboot to prevent automatic order reassignment.
- Sector coordinate validation added to fleet movement commands.
- AI config constants centralized into VoidElementManager for easier tuning.
- Default AI aiming accuracy raised to 3000 (improved targeting at range).
Fleet Stealth Commands
- Fleet Stealth command calls have been fixed, so players should now be able to have their fleets jam / unjam, and cloak / uncloak properly.
Graphics & Rendering
Improved Graphics Presets
- Added more options to existing graphics presets, and a new "auto" setting that will automatically detect the user's system specs. Scores the system (0-100) based on VRAM (40pts), system RAM (25pts), CPU cores (25pts), available OpenGL version (10pts), etc., and maps the score to: Ultra (85+), VeryHigh (73+), High (60+), Medium (45+), Low (30+), VeryLow (<30)
Block Model Visual-State Framework
A new Block Visual State system allows mods to assign multiple model visual states to blocks:
- BlockVisualStateDef: data class defining a visual state with versioning.
- BlockVisualStateAPI: API surface with state versioning, cache invalidation, and authoritative token management via LodStateTokenStore.
- BlockVisualStateDefDialog: in-editor dialog for creating and editing model visual state definitions.
Framebuffer & Resource Improvements
- FBO depth buffers are now reset on re-creation to prevent stale state artifacts.
- Non-critical GL errors from framebuffer operations are logged rather than thrown, improving resilience.
- Shader unloading methods converted to use unloadWithoutExit for safer resource cleanup.
Segment Upload Throttling and Lighting System Improvements
- GPU segment uploads are now throttled per frame (default: 15 uploads/frame) to prevent single-frame CPU/GPU spikes (stuttering) when large entities enter render range. Configurable via a new G_SEGMENT_UPLOADS_PER_FRAME engine setting.
- Added a new setting G_LIGHTING_THREAD_COUNT to configure how many CPU threads to use for calculating segment lighting (default: 4 threads).
- Overhauled internal lighting calculation resource usage to alleviate GC pressure.
Modding API
StarLoader Mixin Integration
Full Mixin support is now available for mods:
- StarMixinService, StarMixinServiceBootstrap, and StarMixinGlobalPropertyService implement the SpongePowered Mixin service interfaces.
- StarMixinAgent, StarMixinAuditTrail, and MixinClassTransformer wire Mixin class transformations into the launch class loader with full diagnostics.
- Mods can declare Mixin configuration JSON files that are automatically registered and applied at load time.
- SMModLoader propagates mixin configs from virtual mods into their ModSkeleton.
- The old class replacement system has been removed entirely.
Per-Block Custom JSON Metadata
Blocks can now carry arbitrary JSON metadata:
- SegmentController stores block custom data in a deduplicated pool (blockCustomDataPool) indexed per block, with full save/load serialization.
- EditableSendableSegmentController accepts pendingBlockCustomData and applies it on block placement (including symmetry mirrors).
- /give_item_data gives a player an item with specified custom data.
- /set_item_data allows modifying the custom data of the player's current item.
- /set_item_slot_data allows modifying the custom data of a specific inventory slot.
- ManagerContainer can read custom block data tags for use in factory/refinery logic.
Inventory System Extensions
- inventoryType and inventorySlotsLimit fields added to block configuration and ElementInformation, enabling mods to define custom inventory-capable blocks.
- SavedInventory: new class for persisting custom item storage per-player in creative mode, with panel UI.
- Custom data preserved when updating inventory slots; InventorySlotContainer interface introduced for improved modularity.
Factory / Refinery API
- registerRefinery(...) and registerFactory(...) methods added to the public API.
- Legacy newRefinery and newFactory methods deprecated.
- factoryStandardControlledBy and factoryStandardControlling fields made public for broader API access.
Mod Loading Improvements
- Dependencies are now loaded before mod instantiation, preventing class-not-found errors at mod init.
- Loading screen now shows detailed per-phase progress during mod loading and initialization.
- Mods are now properly reloaded on relog, so players no longer have to restart their client when relogging.
Build Mode & UI
Control Scheme Presets & Key Remapping
- New CONTROL_SCHEME_PRESET engine setting with New and Classic options.
- KeyboardMappings.applyControlSchemePreset(...) remaps ship controls to match the selected scheme when settings are committed.
Build Mode Help
- Build mode help text is now only shown in advanced mode to reduce HUD clutter for new players.
Catalog Upload and Template Selection Dropdown Improvements
- Added a search bar for the catalog upload and template selection dropdown, to make finding a particular blueprint or template easier. Additionally, the catalog system now uses Java's parallel streams API for faster loading.
Markdown Renderer
Added a GUI markdown renderer with support for:
- Lists: both ordered and unordered with proper indentation and bullet styles.
- Code Blocks: fenced code blocks.
- Tables: full grid layout with header rows.
- Blockquotes: indented/styled quote blocks.
- Block Sprites (![block:BlockName]): renders an inline 3D block icon.
- SVG fenced code blocks: rendered via JSVG into a GL texture (graceful fallback to plain code block on failure).
- Images: .png images can be displayed from local storage or online.
- Links ((url)), strikethrough (~~text~~), inline code, and all 6 heading levels.
In-Game Guides
- Added an in-game guide system to replace the old video tutorials, compiled from https://github.com/StarMade-Community/StarMade-Guides. Players are encouraged to contribute to these guides via PR, as not all the documentation is up-to-date or completed yet.
Gameplay & Mechanics
New Display Module Features
- Display Modules can now have multiple tags to change style properties for different text sections.
- Added a new rot option to rotate display module text in degrees.
- Display modules can now be used to override Rail Rotators to specific angles in degrees. Simply place the display module with the desired angle adjacent to the activation module that activates the rotation.
- Sensor Output: Connect a sensor to one display module and one probed block (e.g. shields, power, rail rotator). The sensor will write the probed value to the display module.
- For rail rotators/turrets, the current rotation angle in degrees (0-360) is the output.
- For other blocks, the sensor's measured value is the output.
- For rail rotators/turrets, the current rotation angle in degrees (0-360) is the output.
Logic Beams
- Added Logic Beams - A new block that can be used to quickly transmit logic signals across entities using an activation beam.
Faction Map Color Picker
- Factions can now select what color they want their territory to appear as on the map, and the bug causing the colors to slowly revert has been fixed.
Tractor Beam Improvements
- Ships being tractored now have their state synced to clients; the server temporarily takes position authority while the beam is active to prevent jitter.
- Tractor beam config now uses thrust ratio instead of mass ratio.
Weapon Damage Performance Overhaul
- Updated code paths in all three weapon types to reuse objects and optimize code to avoid unnecessary allocations and paths. In particular, explosion and acid calculations were causing significant GC pressure by allocating large numbers of temporary objects every tick.
- In the acid damage propagation code specifically, toPropagate.removeLong(0) on every iteration was shifting the entire array, making the propagation loop O(n^2). By reading entries by index (getLong(i)) during the loop, then bulk-removing all processed entries with a single removeElements(0, count) at the end, we were able to reduce the removal cost from O(n) per iteration to O(n) total. For a propagation wave hitting 500 blocks with 2000 entries in the queue, the old code would perform roughly 1,000,000 element shifts. The new code should perform only around 2000 total for the same scenario.
Targeting Display Changes
- Added an additional display underneath the target distance indicator that displays the distance the projectile (cannons and missiles only) will have to travel to hit the target, based on the target's current heading and velocity.
Astrotech System Fixes
- Astrotech systems can now properly repair links between blocks.
- Implemented substantial performance improvements and optimizations for repair handling code to heavily reduce object allocation and relieve GC pressure.
- Improved Repair command handling for AI Fleets.
Shield System
- Major shield hits are now broadcast more often to nearby clients for visual feedback, reducing shield desync.
- Client-side shield recalculation disabled for remote ships to prevent overwriting network-synced values.
Warhead Changes
- Warheads will now explode as a single group rather than many smaller explosions, and explosion calculations in general should now be far more performant.
Fixes for Build Shape Tools Radial Menu ( ` )
- Several fixes have been implemented for the Build Shape Tools Radial Menu ( ` ), so the tools should now be more visually and functionally consistent.
Thrust Sharing Bug Fix
- The long-standing docked thrust sharing bug has finally been fixed, so docked thrusters no longer provide huge amounts of thrust.
Mod Mappings Fix
- Some ships with modded blocks were having their mappings incorrectly parsed, causing blocks to randomly swap between different worlds and mod installations. This should now be fixed.
Server & Stability
Crash Detection & Reporting
- CrashLogger atomically captures the first unhandled server exception and writes a detailed crash report to ./logs/crash-report-{timestamp}.log.
- Report includes system info, JVM arguments, graphics info, full stack trace, cause chain, and a thread dump.
- Subsequent cascading exceptions after the first are suppressed to keep the log readable.
- New ServerCrashEvent fired via StarLoader so mods can react to crashes.
Player Spawn Distance Check
- Added a maximum distance check when spawning players in; clients should no longer stall waiting for distant controller loads.
Performance Improvements
- Object allocation and CPU pressure significantly reduced in many hot-paths.
- Diagonal neighbor handling and neighbor counting logic optimized for segment processing in ElementCollectionMesh.
- BlockBuffer and RepairBeamHandler refactored for improved clarity and reduced overhead.
- Segment Updates (when not caused by player action) and Element Collection processing are now done using batch processing rather than as soon as possible. This will improve performance on both client and server at the cost of slightly delayed lighting and segment updates. By default, both are set to process every 1000ms (1 second), and can be tuned as needed in configs.
Platform / OS Fixes
- Linux: Fixed saved credentials not persisting across computer restarts.
- Intel Mac: Fixed crash where NSWindow.setStyleMask was called off the AppKit main thread when exiting fullscreen.
- Intel Mac: Fixed startup crash when loading AquaLookAndFeel fails (graceful fallback).
- All platforms: Fixed NPE in getCurrentDisplay() when a monitor's name does not match any known display entry.
Known Issues
- Unfortunately, the reported shadow issues have proven difficult to fix on certain GPUs, so they have been temporarily disabled until a proper solution can be found. Expect a follow up fix for these.
- ARM Macs are not supported by this build currently due to the limitations of LWJGL2. We hope to be able to support them in a future update however.
If you find any issues, please report them in the issue tracker here.
And, as always, thank you for playing StarMade!
