Orx - Portable Game Engine (Version 1.15)

If you have any questions or comments, come chat with us on Discord.

This engine is licensed under the very permissive zlib license, see the LICENSE file for details.

Changes

• IMPORTANT: Added support for internal memory-based resources, including: orxResource_SetMemoryResource(), hotreload support, WEBP-encoded orx:font:default & orx:texture:logo textures

• IMPORTANT: Added Trigger module to enable per-object hierarchical/cascaded event handling in config, using commands (new ScrollObject's input system relies on Triggers), added internal triggers to handle object's creation, deletion and physics collisions

• IMPORTANT: Added support for headless mode, using embedded plugins + __orxHEADLESS__ define

• IMPORTANT: Added support for manual parents for Animation & Frame sections

• IMPORTANT: Using a single float value as an object/camera/spawner Position will only set its Z component, e.g. Position = -1 <=> Position = (0, 0, -1)

• IMPORTANT: FX module overhaul, including: Bezier curves support, web easing curves (30) and user-defined float/vector FXs

• IMPORTANT: Added orxObject_FindChild()/orxObject_FindOwnedChild (and commands) to find objects inside a hierarchy based on their name/index

• IMPORTANT: Languages can now be added on-the-fly to the Locale module, Locale.LanguageList has been replaced by Local.Language to define the default language

• IMPORTANT: Invalid animation sets will not stop execution anymore, using an unknown current/target anim name will be ignored (useful for recursive calls on hierarchies with diverging animation sets)

• IMPORTANT: Init-ed projects can now be re-init-ed to add/remove/update extensions

• IMPORTANT: Added tailored ExtensionTemplate.ini to init-ed projects, describing all config properties used by enabled extensions

• IMPORTANT: An optional wrap around and FX can now be applied to shader time parameters

• IMPORTANT: Bundle & Scroll extensions are now enabled by default for newly created projects using init

• IMPORTANT: Literal positions & pivot overrides will now work properly, no matter the IgnoreFromParent settings

• IMPORTANT: Min deployment OS version for MacOS is now 10.10

• IMPORTANT: Removed redundant orxClock_GetNext()

• IMPORTANT: default debug64 configurations has been replaced by debuguniv64 on MacOS

• IMPORTANT: Added typo detector for config values, using the Damerau-Levenshtein edit distance calculation algorithm (can be disabled)

• IMPORTANT: Added support for white, pink & brownian noises and sine, square, triangle & sawtooth (A-440 Hz) audio wave streams

• IMPORTANT: @ is now supported as the self-section identifier for config lazy commands

• IMPORTANT: Added orxInput_PushSet()/_PopSet() (+ associated commands) to handle input sets in a similar fashion to config sections

• IMPORTANT: The [Color] section can now be extended/overridden in the main config file

• New Mod init extension (based on ibxm) has replaced the former pocketmod-based one: FastTracker 2 .XM & Scream Tracker 3 .S3M formats are now supported

• Added SNDH init extension (based on AtariAudio) to play Atari ST sound files

• Added Cheat code (pass phrases/input sequences) init extension

• Added Inspector init extension (to inspect objects & associated config at runtime)

• Added support for new mouse cursors (hresize -> resize_ew, vresize -> resize_ns, resize_nesw, resize_nwse, resize_all & not_allowed)

• Improved clock's internal sleep accuracy to prevent oversleeping and micro-stuttering

• FPS counter isn't rendered on debug viewports anymore

• Objects with bodies can now age (but collisions won't be resolved during aging)

• Color literals can now be used in numeric random expressions, with or without steps

• Color literals are now supported through exposed config API and can be used for all available color spaces

• Added orxREMAP(), orxVector_Remap() & orxVector_Mod() (+ associated commands/aliases)

• Fixed auto-resize behavior of multiple viewports linked to the same texture

• Improved orxFontGen's log output

• Muted many unessential warning messages that spam logs in some valid use cases

• Added Input.Load, Input.Save and Input.ClearSet commands (+ orxInput_ClearSet()), orx:input:console & orx:input:profiler as internal input sets

• Added orxConfig_GetDefaultParent() & commands Config.SetDefaultParent/Config.GetDefaultParent

• Added Clock.Pause & Clock.IsPaused commands

• Added Object.(Add|Remove)BodyPart & Object.SetBody commands

• Physics simulation will now be ignored for objects linked to a paused clock

• Objects linked to a paused clock will not be updated

• Commands *ToSPherical & *ToCartesian now use degrees instead of radians

• Command.Evaluate can now take an optional GUID parameter

• Added orxObject_SetFXTime[Recursive]()/_GetFXTime() (+ associated commands)

• Added orxObject_ResetActiveTime[Recursive]() & command Object.ResetActiveTime

• Updated to latest Scroll (headers-only, OnFX* methods, ScrollObject::Find[Owned]Child/Get[Owned]Child, ScrollObject inputs & triggers support, etc.)

• Many misc fixes, optimizations and additions

Summary

Orx is a 2D-oriented, data-driven, portable game engine focused primarily on ease of use and powerful features.
See below for a list of supported platforms.

This is a release candidate for orx v1.15. If you find any bugs,
please report them on the forum, in the "Bug report - Feature request" board,
or via orx's issue page/tracker.

Some notable features of the engine are:

• powerful config system that makes orx data-driven and provides an easy to use load/save system
• hardware-accelerated rendering that provides: translation, anisotropic scale, rotation,
  transparency (alpha blending), different blending modes, coloring, tiling and mirroring
• advanced rendering features such as MRT (Multiple Render Targets), offscreen rendering, flexible pipeline & easy compositing
• advanced resource management allowing for easy multi-platform data support and patching
• automatic hotloading of resources upon modification on disk drastically shortens iteration times
• timelines and commands modules allow for config-driven scripting-like features
• interactive console can execute commands at runtime (very useful for tweaking/debugging purposes)
• advanced animation engine (including a chaining graph & custom animation events for synchronization)
• fragment (pixel) shader support
• visual FXs based on curve combinations
• integrated runtime profiler (with graphical display) to easily spot which parts of your game need to be optimized
• collision handling and rigid body physics
• camera/viewport scheme allowing multiple views displayed with camera translation, zoom and rotation
• generic input system that abstracts keyboard, mouse, joystick, touch and accelerometer inputs
• powerful localization module (for localized texts, audio, graphics, etc.)
• spawners (provides an easy way to create particles or projectiles)
• 3D positioning using "scene nodes"
• custom bitmap font support
• automatic differential scrolling and depth scaling upon request
• fully featured and extensible sound system (WAV/MP3/OGG support, streams, hierarchical buses, filters, spatialization, etc.)
• clock system that provides time consistency and allows time stretching + high precision timers
• event manager
• unicode support with UTF-8 encoding
• plugin system
• screenshot capture tool (supports bmp, png, jpg, qoi, tga and dds)

See orx's wiki for detailed information, including:

• initial setup
• beginner's guide
• tools
• samples
• detailed tutorials (both official and community-made ones)

See the doc/html directory for the doxygen documentation of orx's API.
The documentation for the latest release version is available here at orx's homepage.

Supported Platforms

The engine compiles and is tested for:

• Linux (x86/x86-64 with codelite, codeblocks and GNU makefile)
• Windows (x86/x86-64 with vs2017, vs2019 & vs2022, x86/x86-64 mingw-w64 (8.1.0) with codelite, codeblocks and GNU makefile)
• MacOS X (x86/x86-64 with xcode or x86/x86-64 with codelite, codeblocks and GNU makefile), version 10.6+
• iOS (iPhone/iPod Touch/iPad, simulator & device with xcode)
• Android (NDK build files, simulator & device)

Versions

Those are not revision versions but link/run versions.
Orx library can be compiled as a static or a dynamic library.
In addition to these modes, orx can be compiled as an embedded version or not.

Orx's core is basically platform-independent. All the platform/OS-dependent features
are implemented via plugins. These plugins can be loaded at runtime (hotplug) or
they can be embedded at linktime.

If you use the non-embedded versions, you'll have to specify which plugins to use.
This is more flexible but also requires additional files (the plugins themselves).
The embedded version will store everything in orx's library, meaning you won't be able
to choose which plugin to use at runtime, but will also be more compact. This will
also make orx run considerably faster.

From the download page you'll find precompiled binaries for Windows (x86), Linux (x86/x86-64), MacOS X (ppc/x86/x86-64),
iOS and Android, using the dynamic embedded versions only.
If you want to use the non-embedded versions (to use with your own plugins), you'll need to compile orx yourself from the source.
Everything compiles out-of-the-box for the hardware platforms cited above.

The embedded versions currently use:

• GLFW-based (+stb_image/webp/qoi/BasisU) display, joystick, keyboard and mouse plugins for all non-iOS/non-Android platforms
• miniaudio (+stb_vorbis) sound plugin for all platforms
• LiquidFun-based physics plugin
• Homemade rendering plugin (2D)
• OpenGL ES display plugins for iOS and Android
• Touch/MultiTouch-based mouse plugin for iOS and Android
• Accelerometer-based joystick plugin for iOS and Android

If the headless variants of the embedded versions are requested, dummy plugins will be used for the display, joystick, mouse, keyboard and soundsystem plugins.
The render & physics plugins will be the same as the ones used for the non-headless versions.

All the 11 basic and advanced official tutorials are shipped with the dev packages, including precompiled release binaries.

Some tools (precompiled binaries only) are also shipped with the dev packages:

• orxCrypt : command line tool to encrypt/decrypt/merge multiple config files
• orxFontGen: command line tool (based on FreeType2) to generate custom bitmap fonts (.png texture & .ini config file) from TrueType fonts

Packages

You can download all the packages from SourceForge or GitHub.
Here is a list with a small description for each package.

• orx-doc-1.15.zip : orx's API doxygen documentation
• orx-src-1.15.zip : orx's source code, ready for compile after running the setup script
• orx-dev-linux32-1.15.tar.bz2 : dynamic embedded binaries for Linux (x86), release/profile/debug + tools.
• orx-dev-linux64-1.15.tar.bz2 : dynamic embedded binaries for Linux (x86-64), release/profile/debug + tools.
• orx-dev-mac-1.15.zip : dynamic embedded binaries for MacOS X (x86/x86-64), release/profile/debug + tools.
• orx-dev-mingw-32-1.15.zip : dynamic embedded binaries for Windows (mingw/x86), release/profile/debug + tools.
• orx-dev-mingw-64-1.15.zip : dynamic embedded binaries for Windows (mingw/x86-64), release/profile/debug + tools.
• orx-dev-vs2017-32-1.15.zip : dynamic embedded binaries for Windows (Visual Studio 2017, x86), release/profile/debug + tools.
• orx-dev-vs2017-64-1.15.zip : dynamic embedded binaries for Windows (Visual Studio 2017, x86-64), release/profile/debug + tools.
• orx-dev-vs2019-32-1.15.zip : dynamic embedded binaries for Windows (Visual Studio 2019, x86), release/profile/debug + tools.
• orx-dev-vs2019-64-1.15.zip : dynamic embedded binaries for Windows (Visual Studio 2019, x86-64), release/profile/debug + tools.
• orx-dev-vs2022-32-1.15.zip : dynamic embedded binaries for Windows (Visual Studio 2022, x86), release/profile/debug + tools.
• orx-dev-vs2022-64-1.15.zip : dynamic embedded binaries for Windows (Visual Studio 2022, x86-64), release/profile/debug + tools.
• orx-full-ios-1.15.zip : static embedded binaries for iOS, release/profile/debug, simulator/device + doc + source + XCode project file.
• orx-dev-android-1.15.zip : static embedded binaries for Android, release/profile/debug (device).
• orx-tutorial-linux32-1.15.tar.bz2 : tutorials for Linux (x86)
• orx-tutorial-linux64-1.15.tar.bz2 : tutorials for Linux (x86-64)
• orx-tutorial-mac-1.15.zip : tutorials for MacOS X (x86/x86-64)
• orx-tutorial-mingw-32-1.15.zip : tutorials for Windows (mingw/x86)
• orx-tutorial-mingw-64-1.15.zip : tutorials for Windows (mingw/x86-64)
• orx-tutorial-vs2017-32-1.15.zip : tutorials for Windows (Visual Studio 2017, x86)
• orx-tutorial-vs2017-64-1.15.zip : tutorials for Windows (Visual Studio 2017, x86-64)
• orx-tutorial-vs2019-32-1.15.zip : tutorials for Windows (Visual Studio 2019, x86)
• orx-tutorial-vs2019-64-1.15.zip : tutorials for Windows (Visual Studio 2019, x86-64)
• orx-tutorial-vs2022-32-1.15.zip : tutorials for Windows (Visual Studio 2022, x86)
• orx-tutorial-vs2022-64-1.15.zip : tutorials for Windows (Visual Studio 2022, x86-64)

All the *-dev-* packages above include:

• orx release/profile/debug libraries used for linking
• runtime release/profile/debug orx libraries
• headers to include at compile time
• template files exposing which properties can be accessed using the config system (for user reference only, not needed by orx)

All the *-tutorial-* packages above include:

• heavily commented source code for 11 basic and advanced tutorials
• precompiled binaries (orx link library, orx runtime library)
• headers to include at compile time
• template files exposing which properties can be accessed using the config system (for user reference only, not needed by orx)
• build/project files

Compiling

Important - first step:

If you just downloaded the src package or cloned orx with mercurial or git, you will need to run the setup.bat / setup.sh script
that's located at its root before being able to compile the engine.
This script will download all the needed dependencies and generate all the project files for your platform.
The script will then hook itself to mercurial/git and you shouldn't have to run it manually after subsequent pulls.

The easiest way to learn how to compile your project using orx for a given platform
is to check orx's wiki.

The generated project files will contain 6 different configurations to build orx: Debug, Profile & Release in both regular and Core flavors. Here's what they do:

• Debug: These configurations will build orx in debug mode. They are the only configurations that will output warning and error messages resulting from incorrect data, code and behaviors. These configurations are also much slower than the other ones but is recommended during development to catch any mistake. Note: the internal profiler is also available with these configurations.

• Profile: These configurations will build orx in optimized mode but will keep the internal profiler, slightly slowing down the execution but allowing the user to get high level profiling information which can be very useful during development.

• Release: These configurations will build orx in optimized mode, without the internal profiler. These are the configurations one should be using when shipping their project. Note: on Windows, the OS terminal will also be hidden with this configuration.

• Core: Those configurations will only build orx's core as a static library. With these configurations, no plugins will be compiled/embedded. In non-Core configurations, all the plugins are built and embedded inside orx's library, and should be the configurations used by most users. The Core configurations are typically used to build orx's tools that do not require any plugin (orxCrypt & orxFontGen).

Here's a quick list of the available compile preprocessor flags:

• __orxDEBUG__ : used to compile and link against the debug versions of orx library
  (liborxd.a / orxd.lib / liborxd.dylib), if not specified it refers to
  the release versions (liborx.a / orx.lib / liborx.dylib).
  NB: If you want to link against the debug versions of orx library, you need
  to specify it to your compiler!

• __orxPROFILER__ : used to enable the profiling push/pop macros for release builds
  It's automatically enabled for debug builds and it has been enabled to
  build liborxp.a / orxp.lib / orxp.dll / liborxp.dylib / liborxp.so
  NB: You can define it in your projects even when using regular release builds,
  but you won't be able to see orx's internal profiling markers!

• __orxSTATIC__ : used to compile and link against the static versions of orx library.
  NB: If you want to link against the static versions of orx library, you need
  to specify it to your compiler!

• __orxEMBEDDED__ : used to compile the embedded versions of orx library.
  NB: this flag is ONLY needed when compiling orx library, not when linking
  against it.

• __orxHEADLESS__ : used to embed plugins that are compatible with a headless mode.
  NB: this flag is ONLY used when compiling orx library
  and when __orxEMBEDDED__ is also defined!

There are other preprocessor flags used when compiling the orx library,
but those should be easy enough to decipher. markdo
However, you might want to specify them manually for cross-compiling or
use them so that your code will behave differently depending on the architecture
for which you're compiling. Here's a quick list of these flags:

Comments

If you have any questions, comments, ideas or reviews, feel free to come chat with us on Discord.

Enjoy!