SceneMax3D Developer Studio

A desktop 3D scene editor and game development environment built with Java, JMonkeyEngine 3, and Swing.

SceneMax3D lets you visually design 3D scenes, write game logic using a built-in scripting language, and export your projects as standalone PC executables or Android apps.

SceneMax3D was first created by Adi Barda in 2005 as a C++/DirectX game engine and scripting language for education purposes. In 2017-2018 it was rewritten in Java from scratch using JMonkeyEngine3 as the target renderer and ANTLR4 for the language parsing. In Mar-22, 2026 the entire solution was uploaded to GitHub as an open source (MIT license) project.

Product Website

SceneMax3D

Documentation

SceneMax3D includes project documentation in the docs/ folder, covering the scripting language, control flow, and other engine concepts.

For IDE extension development, see the enhanced plugin system guide in docs/plugin-system.md. It covers plugin discovery, lifecycle, toolbar/menu actions, views, asset providers, settings, model import/preview, packaging, and a minimal plugin example.

For a real-world enhanced plugin reference, see the Meshy AI plugin guide in docs/meshy-ai-plugin.md, which explains the Meshy integration, community search, rig/animation filters, static model imports, preview/import flow, and source-code map.

For AI-assisted workflows, see the built-in MCP and Local Gemma guide in docs/built-in-mcp-server.md, which explains setup for Claude, Codex, Claude Desktop, and local Gemma-powered assistance.

For a tool-by-tool reference covering purpose, common inputs, outputs, and agent-facing usage patterns, see docs/mcp-tools-reference.md.

For weapon authoring and runtime equip/posture examples, see docs/weapons-designer.md.

For throw motion authoring, projectile/return motion setup, and runtime examples, see docs/throw-motion.md.

For inverse-kinematics authoring, joint setup, preview simulation, and runtime IK commands, see docs/ik-designer.md.

For Effekseer particle-effect scripting and runtime examples, see docs/effects.md.

For hands-on examples, see the demo projects guide in projects/readme.md, which walks through the sample games and explains how they are structured.

Ready-to-Use Binaries

If you want to try SceneMax3D without building from source, download the Windows setup binaries from the latest GitHub release.

Features

• Visual 3D Scene Designer -- drag-and-drop scene composition with real-time preview
• Custom Scripting Language -- purpose-built DSL (ANTLR4-based parser) for game logic and interactivity
• Code Editor -- syntax-highlighted editor with code folding
• Effekseer Particle Effects -- create and play advanced real-time particle effects integrated into scenes and gameplay
• Video Rendering -- import FFmpeg-supported video files and render them onto scene objects at runtime
• Physics Engine -- integrated Minie / Bullet physics
• 3D Model Import -- load models into your scenes
• Cinematic Camera System -- build dynamic camera moves, chase cameras, and dramatic gameplay cutaways
• Weapons Designer -- author .smweapon assets with equip postures, attachment points, preview models, runtime equip/unequip commands, and weapon collider support
• Throw Motion Designer -- author .smmotion assets for throws, projectiles, boomerang-style returns, homing behavior, and reusable motion runtime commands
• IK Designer -- author .smik inverse-kinematics assets with armature scanning, solver templates, skeleton preview, animation blending tests, and runtime layer commands
• Multi-Project Support -- manage multiple projects from a single workspace
• Enhanced Plugin System -- extend the IDE with Java plugins that add toolbar/menu actions, Swing views, asset providers, settings, and model import/preview workflows
• Built-in MCP Server & AI Console -- connect Claude Code, Codex, Claude Desktop, and Local Gemma to live SceneMax project tools
• Classroom Mode -- collaborative features for educational settings
• Export Targets -- package as desktop builds or generate a Web Start bundle (JNLP + landing page)

Requirements

• Java 11 or later
• Windows (primary platform)
• No separate ffmpeg.exe install is required for normal builds; SceneMax uses the JavaCV / Bytedeco FFmpeg runtime libraries declared in Gradle.

Building from Source

SceneMax3D uses Gradle as its build system.

# Clone the repository
git clone https://github.com/scenemax3d/scenemax3d-desktop.git
cd scenemax_desktop

# OPTIONAL - Copy the example config and fill in your values
cp config.properties.example config.properties
# Edit config.properties with your credentials (FTP, API keys, etc.)

# Build the project
./gradlew build

Notes:

• The Gradle wrapper (gradlew, gradlew.bat, and gradle/wrapper/*) is the supported build entry point and is included in the repository.
• The build automatically generates the SceneMax parser jar from scenemax3d_parser/SceneMax.g4 before compiling the compiler and projector modules.
• Parser generation is implemented in Gradle and works from the root wrapper on Windows, Linux, and macOS.
• The ANTLR tool is resolved automatically from Maven Central during the build; the local parser convenience script is not required for a clean clone build.
• scenemax3d_parser/build.bat is kept as a Windows convenience script and is non-interactive. It uses JAVA_HOME when available, otherwise it falls back to java, javac, and jar from PATH.

Configuration

Application credentials and service endpoints are stored in config.properties (git-ignored). Copy config.properties.example to config.properties and fill in your values before running.

See config.properties.example for all available settings.

Video Rendering

SceneMax can import video files and render them directly inside a running scene. The feature is backed by JavaCV and FFmpeg: the designer uses FFmpeg to probe and preview video assets, and the runtime decodes frames on a background thread and applies them as a texture to a target object.

Use this for in-world screens, animated billboards, cutscene panels, portal surfaces, UI-like scene props, or other places where a movie should appear on a 3D object.

Importing A Video

1. Open or create a SceneMax project.
2. Choose Assets -> Import Video....
3. Select an MP4, MOV, MKV, AVI, WebM, MPEG, or another FFmpeg-supported video file.
4. Review the detected dimensions, duration, frame rate, format, and live preview.
5. Optionally edit the asset name and choose a preview shape: Pane, Box, or Sphere.
6. Click Import Video.

Imported videos are copied into the active project under:

resources/videos/<assetId>/

SceneMax also updates:

resources/videos/videos-ext.json

That index stores the asset id, video path, original import path, preview shape, dimensions, duration, frame rate, and format metadata.

Rendering A Video In Code

Declare a video resource with videos.<assetId>, create a renderable target object, then play the video on that target:

screen => quad : size (16,9), pos (0,3,8)
intro_video => videos.intro_clip

intro_video.play : target screen

The target can be any renderable scene object. At playback time, SceneMax replaces the target object's material with an unshaded video texture and updates that texture as FFmpeg decodes frames.

You can also render only part of a clip, reverse it, or loop it:

screen => quad : size (16,9), pos (0,3,8)
intro_video => videos.intro_clip

intro_video.play : target screen, start "00:01:00", end "00:02:59", loop

screen => quad : size (16,9), pos (0,3,8)
countdown => videos.countdown_clip

countdown.play : target screen, start "00:00:05", end "00:00:15", reverse

Supported play options:

Option	Meaning
target <object>	Required. The scene object that receives the video texture.
start "<time>"	Optional start timestamp. Colon-separated values are supported, such as "00:10" or "00:01:30".
end "<time>"	Optional end timestamp. Playback stops when this point is reached.
reverse	Plays frames from the end timestamp back toward the start timestamp.
loop	Restarts playback when the selected range ends.

When a script declares videos.<assetId>, SceneMax marks that video as used so desktop packaging/export can include the referenced video file and metadata automatically.

Visual Effects With Effekseer

SceneMax now includes an Effekseer-based visual-effects stack for imported particle systems. Effekseer assets stay in their native format, are stored under resources/effects/<assetId>/, and can be declared in scripts with effects.effekseer.<assetId>.

Import effects from Assets -> Import Effekseer Effect.... SceneMax accepts .efkefc, .efkproj, and .efk files and copies related texture, model, sound, material, and curve assets into the project effect folder. If you work with .efkproj files, configure effekseer_tool_path in config.properties or choose the Effekseer executable from the effect designer so SceneMax can launch the external Effekseer tool and export runtime .efkefc files.

Basic effect usage:

fire_burst => effects.effekseer.fire_burst
fire_burst.play pos (0,0,0)

Effect objects support placement, show/hide/delete, attachment, look-at behavior, looping playback, and runtime attributes such as playback speed and Effekseer dynamic input channels. See docs/effects.md for complete examples.

Project Structure

scenemax_desktop/            -- Main desktop application (Swing UI)
scenemax_designer/           -- 3D scene designer/editor module
scenemax_win_projector/      -- 3D runtime/playback engine
scenemax_effekseer_runtime/  -- Effekseer JNI/native runtime bridge
scenemax3d_compiler/         -- Script compilation engine
scenemax3d_parser/           -- ANTLR4 grammar & parser for SceneMax scripting language
scenemax3d_common_types/     -- Shared type definitions across modules
scenemax3d_plugins/          -- Plugin system with WebSocket support
scenemax3d_plugins_ide/      -- IDE for plugin development
assets/                      -- UI resources, images, code templates
third_party/Effekseer/       -- Local Effekseer source/sample corpus used by the native bridge workflow

Technology Stack

Component	Technology
Graphics Engine	JMonkeyEngine 3
Physics	Minie (Bullet)
Visual Effects	Effekseer native runtime integration
Video Decoding / Rendering	JavaCV with FFmpeg platform bindings
UI Framework	Swing + FlatLaf (dark theme)
Scripting	Custom DSL via ANTLR4
Build System	Gradle
Code Editor	RSyntaxTextArea
Packaging	Shadow JAR, Launch4J, Web Start bundle generation

Third-Party Libraries

• JMonkeyEngine 3 -- 3D engine
• Minie -- physics library
• JME-Vehicles -- vehicle physics
• ANTLR4 -- parser generator
• Effekseer -- native particle-effect authoring and runtime stack
• JavaCV / FFmpeg -- video probing, preview, decoding, and runtime frame rendering
• FlatLaf -- modern Swing look-and-feel
• RSyntaxTextArea -- code editor component
• Socket.IO -- real-time communication
• NanoHTTPD -- embedded HTTP server

Contributing

Contributions are welcome! Please open an issue to discuss your idea before submitting a pull request.

License

This project is licensed under the MIT License. See LICENSE for details.

Roadmap

A product roadmap is a high-level view of the capabilities and improvements planned for future versions of SceneMax3D. It helps communicate the direction of the product and the areas that are expected to evolve over time.

The items below are planned for future delivery, but they will not necessarily be implemented in the order they are listed:

• Messaging System -- display in-game and runtime messages - done
• Health Bar System -- built-in support for health bar setup and management
• Weapons Designer and Runtime Equip System -- easy authoring, previewing, and runtime use of weapons - done
• Inventory System -- item storage, pickup rules, and inventory UI workflows
• Throw Motion Designer -- reusable thrown-object and projectile motion authoring - done
• IK Designer -- inverse-kinematics authoring and runtime layer controls - done
• Climbing System -- easy definition of climbable objects and a climbing game state machine
• Leaderboard System -- support for game leaderboards
• UI Frames -- show messages inside frames - done
• MiniMap System - Customized minimap system
• Itch.io Integration -- upload and maintain your game on Itch.io - done
• Gallery -- a shared place for presenting SceneMax3D projects
• Terrain Builder -- tools for creating and editing terrain
• Material Builder -- tools for defining and tuning materials - done
• Lighting System -- improved lighting authoring and control
• Physics System -- manipulate object rigs and test physical effects
• Audio System -- built-in audio workflow and tooling
• Android Package & Deployment -- streamlined Android build packaging and deployment
• Move to Jolt Physics -- transition from the current physics backend to the Jolt physics engine
• Debugger -- easier runtime breakpoints and debugging information
• Multiplayer Support -- support for multiplayer game experiences
• Web Browser Projector -- run exported projects directly in the browser
• Java Extensibility
• Scene Sharing