Aukio 3D engine demos

This is the "Hello World" of Aukio 3D - the minimal boilerplate needed to render any 3D geometry.

eu.svjatoslav.aukio.e3d.examples.essentials.MinimalExample

Brief tutorial:

Here we guide you through creating your first 3D scene with Aukio 3D engine.

Prerequisites:

• Java 21 or later installed
• Maven 3.x
• Basic Java knowledge

eu.svjatoslav.aukio.e3d.examples.essentials.CoordinateSystemDemo

Visual reference for the Aukio 3D coordinate system using three colored arrows originating from (0,0,0):

A wireframe grid on the Y=0 plane provides spatial context and scale. Text labels (X, Y, Z) appear at each arrow tip.

This demo is essential for understanding Aukio 3D's coordinate system where:

• Positive Y goes down (screen coordinates convention)
• Positive Z goes into the screen (away from camera)
• Positive X goes to the right

See the Coordinate System section in the Aukio 3D documentation for a detailed explanation of the axis conventions and coordinate math.

eu.svjatoslav.aukio.e3d.examples.essentials.WindingOrderDemo

This demo demonstrates polygon winding order and backface culling - fundamental concepts for efficient 3D rendering.

The green triangle uses counter-clockwise (CCW) vertex ordering:

1. Upper-center vertex
2. Lower-left vertex
3. Lower-right vertex

With backface culling enabled:

• CCW winding (negative signed area) = front-facing = visible
• CW winding (positive signed area) = back-facing = culled (not rendered)

This optimization prevents rendering polygons facing away from the camera, improving performance by roughly 50% for closed meshes. Navigate around the scene and observe that the triangle becomes invisible when viewed from behind, demonstrating the culling effect.

See the Winding Order & Backface Culling section in the Aukio 3D documentation for a detailed explanation with diagrams.

eu.svjatoslav.aukio.e3d.examples.essentials.ShapeGalleryDemo

Comprehensive showcase of all primitive 3D shapes available in Aukio 3D, organized in a 7×2 grid:

Top row: Wireframe versions - edges only, no surfaces Bottom row: Solid polygon versions - filled surfaces with lighting

Additional features demonstrated:

• Dynamic lighting from 10 orbiting colored light sources (visible as small glowing dots)
• Per-shape color assignment for visual distinction
• Grid floor showing spatial layout and alignment
• Text labels identifying each shape type
• Shading enabled on solid shapes to show lighting effects

See the Mesh section in the Aukio 3D documentation for an explanation of 3D mesh fundamentals and how shapes are constructed.

eu.svjatoslav.aukio.e3d.examples.essentials.CSGDemo

Constructive Solid Geometry (CSG) boolean operations on 3D meshes. Three operations displayed left to right:

1. Subtract (Cube - Sphere) - A red cube with a spherical cavity carved out where a blue sphere intersects it. Shows the cube's interior surfaces.
2. Union (Cube + Sphere) - A merged shape combining both volumes. Red surfaces from the cube, blue surfaces from the sphere, seamlessly joined.
3. Intersect (Cube ∩ Sphere) - Only the volume shared by both shapes remains. Shows which parts of space were occupied by both the cube and sphere simultaneously.

Color scheme:

• Red = geometry from the first operand (cube)
• Blue = geometry from the second operand (sphere)

Each operation includes a text description panel below the shape. The demo uses:

• SolidPolygonCube (red)
• SolidPolygonSphere (blue)
• CSGSolid.subtract(), union(), intersect() methods
• toMesh() conversion for rendering
• Backface culling and shading enabled

CSG is powerful for procedural modeling, allowing complex shapes to be built from simple primitives through boolean combinations.

See the CSG documentation for a detailed explanation of the boolean operations.

eu.svjatoslav.aukio.e3d.examples.essentials.LightSourceDemo

Demonstrates how multiple light sources illuminate a 3D surface and how their contributions combine to create complex lighting effects. A white sphere serves as the canvas, allowing light colors to mix visibly on its surface.

The white base color is crucial: colored lights tint the surface based on their own color. A yellow light creates warm yellow highlights, while a blue light adds cool blue tones. Where both lights influence the same surface area, their contributions add together, creating blended colors.

Light configuration:

The yellow light positioned directly above creates strong top-down illumination with high intensity (2.0). The blue light from the left-front side provides softer fill lighting at lower intensity (0.5). Low ambient light (30, 30, 30) ensures dramatic contrast between lit and shadowed areas.

Creating light sources:

import eu.svjatoslav.aukio.e3d.renderer.raster.lighting.LightSource;
import eu.svjatoslav.aukio.e3d.geometry.Point3D;
import eu.svjatoslav.aukio.e3d.renderer.raster.Color;

// Create a bright yellow light above the sphere
LightSource yellowLight = new LightSource(
    new Point3D(0, -300, 0),  // position: directly above
    Color.YELLOW,             // color
    2.0                       // intensity: extra bright
);

// Create a dim blue light from the left-front
LightSource blueLight = new LightSource(
    new Point3D(-200, 50, -200),
    Color.BLUE,
    0.5                       // intensity: dim
);

Each light source has three properties:

Multiple light sources add their contributions together, allowing for complex lighting setups like the screenshot above showing a sphere lit by two lights.

Key concepts demonstrated:

• LightSource creation with position, color, and intensity
• LightSourceMarker for visualizing light positions in the scene
• setShadingEnabled(true) on shapes to enable lighting response
• Ambient light configuration for base illumination
• Multiple lights contributing to surface shading simultaneously

Small glowing dots mark each light source position, making it easy to understand where the illumination originates. These markers use the same color as their associated light source.

See the Shading & Lighting documentation for a detailed explanation of the Lambert cosine law, distance attenuation, and ambient light.

eu.svjatoslav.aukio.e3d.examples.life_demo.Main

The Game of Life, also known simply as Life, is a cellular automaton devised by the British mathematician John Horton Conway in 1970.

• https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life
  • Game rules:
    • 2 cell states: alive / dead
    • Each cell sees 8 neighboring cells.
    • If alive cell neighbors count is 2 or 3, then cell survives, otherwise it dies.
    • Dead cell becomes alive if neighbors count is exactly 3.

This demo projects the 2D game grid onto three-dimensional space. The extra dimension (height) visualizes history (previous iterations) using glowing dots suspended in space.

Usage:

eu.svjatoslav.aukio.e3d.examples.TextEditorDemo

Initial test for creating user interfaces in 3D, demonstrating:

• window focus handling
• picking objects using the mouse
• redirecting keyboard input to the focused window

Window focus acts like a stack.

When a window is clicked with the mouse, the previously focused window (if any) is pushed to the focus stack and the new window receives focus. A red frame appears around the window to indicate this.

When the ESC key is pressed, focus is returned to the previous window (if any).

When any window is focused, all keyboard input is redirected to that window, including cursor keys. To navigate around the world again, the window must be unfocused first by pressing the ESC key.

eu.svjatoslav.aukio.e3d.examples.TextEditorDemo2

Quite a lot of text editors can be rendered:

See also this similar-looking web-based demo!

eu.svjatoslav.aukio.e3d.examples.graph_demo.MathGraphsDemo

eu.svjatoslav.aukio.e3d.examples.SineHeightmap

Simple test scene. Easy to implement and looks nice.

eu.svjatoslav.aukio.e3d.examples.OctreeDemo

Test scene that is generated simultaneously using:

• conventional polygons
  • for realtime navigation, and
• voxels
  • for on-demand raytracing

Instead of storing voxels in a naive [X × Y × Z] array, a dynamically partitioned octree compresses the data. Press the "r" key anywhere in the scene to raytrace the current view through the compressed voxel data structure.

eu.svjatoslav.aukio.e3d.examples.galaxy_demo.PointCloudDemo

Spiral galaxy simulation composed of 10,000 glowing points rendered as GlowingPoint primitives. The galaxy features:

Optimization technique:

Colors are drawn from a pre-computed palette of 30 semi-bright colors (RGB values 0.5-1.5 with alpha 255). This enables texture caching - all stars of the same color share the same glow texture, reducing memory usage and improving rendering performance.

This demo showcases the engine's ability to efficiently render large numbers of billboard-style particles with per-point coloring.

eu.svjatoslav.aukio.e3d.examples.RainingNumbersDemo

Animated "digital rain" effect. Creates 1000 randomly positioned TextCanvas objects displaying digits 0-9 that continuously fall through 3D space.

Animation mechanics:

The demo implements the FrameListener interface to update positions each frame:

1. All text canvases translate downward by millisecondsSinceLastFrame / 50 units
2. Numbers falling below Y = +300 wrap around to Y = -300
3. Creates an infinite, seamless animation loop
4. Frame-rate independent movement via delta-time calculation

Visual characteristics:

Each digit is rendered with:

• Random position within a 600×600×600 cube
• Random RGBA color (fully opaque to semi-transparent)
• Random digit value (0-9)

This demo demonstrates:

• Real-time animation using frame listeners
• Efficient handling of many dynamic text objects
• World wrapping for infinite effects
• Per-instance color randomization

eu.svjatoslav.aukio.e3d.examples.RGBCubeDemo

Volumetric RGB color cube visualization composed of 10×10×10 square plates (1,000 total) arranged as flat XY planes along the Z axis. Each plate is built from two textured triangles using a solid-color texture with a black border.

Color mapping:

Each square's color is determined by its 3D grid position:

Visual characteristics:

• 10 parallel Z-layers, each containing a 10×10 grid of square plates
• Each plate: two textured triangles with a 32×32 pixel solid-color texture
• Black border (3 pixels) around each plate for visual separation
• Square size: 40×40 world units
• Cube extends ±200 units from origin in each axis
• Colors range from black (0,0,0) at one corner to white (255,255,255) at opposite corner

Usage:

Navigate around and through the cube to explore color relationships:

• Outer faces show primary/secondary color gradients
• Interior reveals color mixing in 3D space
• Fly through layers to see how blue component changes with depth

This demo demonstrates:

• Textured triangle rendering with per-cell color assignment
• 3D color space visualization
• Systematic grid-based geometry generation

eu.svjatoslav.aukio.e3d.examples.terrain_demo.TerrainDemo

Demonstrates procedurally generated mountain terrain with an animated fractal tree. The scene features:

Terrain generation:

The terrain uses the DiamondSquare algorithm to generate a heightmap with realistic mountain-like features.

Fractal tree:

The tree at the terrain center demonstrates hierarchical transforms in Aukio 3D:

• Trunk: Single vertical cylinder
• Level 0: 3 branches extending from trunk top (120° apart)
• Level 1: 9 sub-branches (3 per level-0 branch)
• Level 2: 27 fine branches (3 per level-1 branch)
• …

Each branch is an AbstractCompositeShape containing:

• SolidPolygonCylinder for the branch geometry
• Child branches positioned at the tip (recursive structure)

Animation system:

Branches sway using the FrameListener interface:

1. Each branch has unique random phase offsets for X and Z axes
2. Wobble calculated as: sin(frame × frequency + phase) × amplitude
3. Parent rotation automatically propagates to children via TransformStack
4. Creates cascading motion where sub-branches inherit parent wobble + add their own

Key classes:

• TerrainDemo - Main entry point and scene setup
• DiamondSquareTerrain - Procedural heightmap mesh generation
• FractalTree - Tree trunk with recursive branch hierarchy
• Branch - Individual branch with animation and child branches

Usage examples:

This demo showcases techniques useful for:

• Open world terrain generation
• Procedural vegetation (trees, plants)
• Hierarchical animation (character rigging, mechanical systems)

See also:

• Diamond-square algorithm on Wikipedia

eu.svjatoslav.aukio.e3d.examples.obj_loader_demo.ObjLoaderDemo

Loads a Wavefront OBJ model with its MTL material library using the engine's ObjLoader and renders it with flat shading.

Two city models are bundled with the demo as classpath resources together with their shared material library result.mtl; on startup the demo asks which one to load (a dialog with one button per city, or --city=1|2 on the command line). "city1" is a small city block of four high-rise buildings with window strips, octagonal rooftop structures and cars parked on the ground and up on the roofs — 79,372 vertices and 27,224 faces; "city2" is a larger district of cylindrical towers — 411,724 vertices and 210,900 faces. Both were generated by the "3D Synthezier" QBasic program (a 1990s DOS scene-description compiler) running under the crtbasic interpreter.

Key concepts demonstrated:

• ObjLoader.load() turning an OBJ file + MTL library into an ObjModel composite of SolidPolygon faces
• Per-face material colors taken from MTL Kd, translucency from d
• Uprighting a +Y-up export in the engine's -Y-up world with a 180° rotation around X (a proper rotation preserves winding and normals)
• Resizing a model whose source units are too small for the scene with Transform.setScale — uniform scale about the local origin, folded into the composed transform stack so per-vertex cost is unchanged
• Self-framing scene setup: the model's bounding box is recentered on the world origin via the transform's translation, and the camera and sun are placed relative to the bounding radius — any bundled city is framed and lit the same way, with no per-model magic numbers
• Flat-shaded lighting of a loaded model with a sun light source
• City lighting beyond the sun: city1 drops the sun entirely and is lit ONLY by its hero light south-east above the rooftops (a clean single-source showcase for verifying shadows); city2 keeps the sun and adds its hero light high east
• The model's upright/scale transform is baked into the vertices at load: engine lighting and GI read geometry in local space while lights live in world space, so a transformed model would show a phantom light position (mirrored below ground). Baking keeps local and world space identical — the marker glow always matches the real light direction
• Light indicators that explain the shadows: every hero light shows a large glow at its position — shadows extend radially away from that point (the source is omnidirectional)
• Baked global illumination (ViewPanel.enableGlobalIllumination): the city's polygons render as lightmapped triangles (ObjModel is a LightmappedCompositeShape), so GI bakes them in bounce generations — direct light first, one more bounce per generation after that — over the first seconds, then frees the per-texel state (golden images stay lightmapping- and GI-free for determinism)