| name | starsector-tech-stack |
| description | Information about the required technology stack, environment JVM flags, and build plugins. |
Starsector Ship Editor — Technology Stack
Skill Directory Structure
This skill is organized as follows:
SKILL.md: Main instructions (this file).resources/: Configurations and templates.
examples/: Code references.
scripts/: Tooling.
Core Language & Runtime
| Component | Version | Notes |
|---|
| Java | Source target 17 (maven.compiler.release=17) | Requires JDK 17–21 to compile. Lombok 1.18.36 crashes on JDK 25 with TypeTag :: UNKNOWN ExceptionInInitializerError. |
| Maven | 3.x | Build tool. Fedora quirk: Fedora's mvn wrapper ignores update-alternatives and reads /etc/java/maven.conf. Set JAVA_HOME=/usr/lib/jvm/java-17-temurin-jdk in ~/.mavenrc to force Java 17. |
JVM Flags (Production)
-Xmx512m -XX:+UseG1GC -XX:+UseStringDeduplication
-XX:MinHeapFreeRatio=10 -XX:MaxHeapFreeRatio=20
Configured via exec-maven-plugin for development and the launcher scripts for production.
JVM Self-Relaunch (Quirk)
Main.java contains checkAndRelaunch() which detects if the JVM was launched with >1.1 GB max heap (e.g., by a system default) and relaunches itself with -Xmx1g to prevent excessive memory usage. The relaunched process is marked with -Dshipeditor.relaunched=true to prevent infinite relaunch loops.
Java2D Suppression
System.setProperty("sun.java2d.opengl", "false");
System.setProperty("sun.java2d.d3d", "false");
System.setProperty("sun.java2d.noddraw", "true");
Java2D's OpenGL and Direct3D pipelines are explicitly disabled because they conflict with the LWJGL GL context sharing through AWTGLCanvas. Without these flags, some drivers produce black canvases or segfaults.
GUI Framework
| Component | Version | Purpose |
|---|
| Swing/AWT | JDK built-in | Core UI framework |
| FlatLaf | 3.1.1 | Modern look-and-feel with dark mode, scalable DPI, and IntelliJ themes |
| Ikonli | 12.3.1 | Vector icon packs: FontAwesome5, FluentUI, Boxicons |
FlatLaf Configuration (Quirks)
JPopupMenu.setDefaultLightWeightPopupEnabled(false) — Required because lightweight popups render behind the AWTGLCanvas heavyweight component.ToolTipManager.sharedInstance().setLightWeightPopupEnabled(false) — Same issue for tooltips.UIManager.put("FileChooser.readOnly", true) — Prevents users from creating/deleting folders in the file chooser.- Early JToolTip initialization:
new JToolTip().updateUI() is called during startup to force the classloader to eagerly load ToolTip UI classes. Without this, the first tooltip display on EDT can trigger lazy classloading that causes a visible UI freeze.
- Shell Folder Filtering: A custom function removes the
:: pseudo-path (SHELL_FOLDER_0_X_12) from the file chooser shortcuts on Windows.
Graphics & Rendering Pipeline
| Component | Version | Purpose |
|---|
| LWJGL 3 (BOM) | 3.3.3 | Core library, OpenGL bindings, GLFW, JAWT |
| lwjgl3-awt | 0.2.3 | AWTGLCanvas bridge between Swing and OpenGL |
| JOML | 1.10.8 | Matrix4f, Vector2f, Vector3f, Vector4f math |
Native Classifiers
Both Linux and Windows natives are included in the POM:
natives-linux for lwjgl, lwjgl-opengl, lwjgl-glfwnatives-windows for the same
macOS is not supported (no native classifiers declared).
Data Handling & Persistence
| Component | Version | Purpose |
|---|
| Jackson Core | 2.18.7 | JSON parsing with extensive relaxed-mode features |
| Jackson Databind | 2.18.7 | Object mapping with custom coercion rules |
| Jackson CSV | 2.18.7 | CSV parsing/writing with custom serializers |
| Jackson Annotations | 2.18.7 | @JsonProperty, @JsonIgnoreProperties, etc. |
| SQLite JDBC | 3.45.2.0 | Embedded database for file indexing |
Utilities
| Component | Version | Purpose |
|---|
| Lombok | 1.18.36 | @Getter, @Setter, @Builder, @Log4j2, @ToString |
| Log4j2 | 2.25.4 | log4j-api, log4j-core, log4j-slf4j-impl |
| Apache Commons Collections 4 | 4.4 | Advanced collection utilities |
| JHLabs Filters | 2.0.235-1 | Image manipulation filters |
Lombok Inheritance Trap (Quirk)
When extending classes that use Lombok @Getter (e.g., LayerPainter), be careful of field shadowing. Always use polymorphic getter methods (getSprite()) in the base class rather than direct field access (this.sprite). Subclasses that override the getter will function correctly; direct field access bypasses the override and hits uninitialized base-class fields, causing NullPointerExceptions.
Build Plugins
| Plugin | Version | Purpose |
|---|
maven-compiler-plugin | 3.11.0 | Java 17 target, Lombok + Log4j2 annotation processors |
maven-surefire-plugin | 3.2.5 | Test execution (JUnit Jupiter + jqwik) |
spotbugs-maven-plugin | 4.8.3.1 | Static analysis: Max effort, Low threshold |
maven-jar-plugin | 3.4.2 | JAR packaging |
exec-maven-plugin | 3.1.0 | Launch via mvn exec:exec with custom JVM flags |
maven-shade-plugin | 3.6.0 | Uber-JAR generation |
Shade Plugin Configuration (Quirks)
Log4j2PluginCacheFileTransformer: Merges Log4j2 plugin caches from multiple JARs. Without this, Log4j2 fails to discover its appenders at runtime.ServicesResourceTransformer: Merges META-INF/services files. Required for JDBC driver auto-discovery and Ikonli icon pack loading.- Exclusion Filters: Strips
module-info.class, signature files (*.SF, *.DSA, *.RSA), and duplicate metadata to prevent SecurityException and classloading conflicts.
- Output: The shaded JAR is written to
${project.basedir}/ship_editor.jar (project root), not target/.
Module System (JPMS)
module-info.java declares a full JPMS module named shipeditor.
Key Observations
requires static lombok: Lombok is compile-time only (no runtime dependency).requires static com.github.spotbugs.annotations: SpotBugs annotations are retained in source but not needed at runtime.- Extensive
opens directives: Many packages are opened to com.fasterxml.jackson.databind for reflection-based deserialization. Without these, Jackson fails with InaccessibleObjectException on Java 17+.
requires transitive java.desktop: Exposes AWT/Swing to downstream modules.- Compiler warnings suppressed:
@SuppressWarnings("module") on the module declaration, and -Xlint:-requires-automatic -Xlint:-module compiler args suppress warnings about automatic modules (LWJGL, Ikonli, etc. that lack proper module-info).
- IDE Access Diagnostics: Be sure to
exports any internal packages (like shipeditor.utility.graphics.opengl) and use requires transitive for external libraries (like org.joml) if their classes are exposed in public method signatures. Without these, strict IDEs (like Eclipse/VSCode) will mass-report "not exported from this module" or "may not be accessible to clients" errors even if Maven compiles fine.
