Orx - Portable Game Engine (Version 1.13)

Email iarwain [at] orx-project.org to contact the author; or, better,
check orx's homepage for the most up-to-date contact information.
You can also come chat with us
if you have any questions or comments.

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

Changes

• IMPORTANT: Added support for VS2022 and retired support for VS2015

• IMPORTANT: Added config-driven command execution for objects with OnPrepare (can optionally reject object creation), OnCreate & OnDelete (can optionally reject object deletion and remove itself) & Object.SetOnDelete command (which can be called from inside OnDelete for cascading effect)

• IMPORTANT: orxObject_Delete() now only returns orxSTATUS_SUCCESS if the object was actually deleted

• IMPORTANT: Added support for position literals with optional offset (which honors UseParentSpace and supports regular/stepped randomization) and temporary pivot override (for flexible parent/child) alignment to objects

• IMPORTANT: Added support for pivot literals to objects & graphics

• IMPORTANT: Added native arm64 support for MacOS 11/XCode 12.x

• IMPORTANT: Added orxMovie (MPEG1/MP2) init extension, based on the PL_MPEG library, that adds config-driven movie support to objects & command Object.GetMovieDuration

• IMPORTANT: Added compressed texture/icon/cursor support for desktop versions (GLFW display plugin) using Basis Universal (UASTC -> ASTC/BC7)

• IMPORTANT: Added support for the QOI image format to all plugins/platforms

• IMPORTANT: Added orxMod (ProTracker MOD) init extension, based on the pocketmod library, that adds config-driven MOD support to objects

• IMPORTANT: The OpenAL, Android & iOS SoundSystem plugins and their external dependencies (OpenAL/OpenAL-Soft, Tremolo & linsndfile) have been removed

• IMPORTANT: Added a new SoundSystem plugin based on MiniAudio that covers all target platforms: all platforms now support loading OGG, WAV & MP3 files as well as writing WAV files, on Windows the audio backend will now update on-the-fly to the one selected by the user

• IMPORTANT: Removed orxSoundSystem_SetSampleData() and replace stream packet payload's as16SampleList with afSampleList (samples are now 32bit floats)

• IMPORTANT: Added support for config-driven filters for both sounds and buses, including commands: supports internal filters (biquad, low|high|band pass, low|high shelf, notch, peaking & delay) and user-defined custom filters (code only) + orxSOUND_EVENT_SET_PARAM event

• IMPORTANT: Added support for multiple sound listeners (none by default, deactivating sound spatialization globally)

• IMPORTANT: Added support for sound panning (including commands), sound spatialization has been entirely revamped and is now data-driven & independent of the channel count (off by default with no listeners)

• IMPORTANT: Removed obsolete SoundSystem config properties StreamBufferSize & StreamBufferNumber, sounds can now optionally be muted when the application is sent to background (on by default)

• IMPORTANT: Pitch FXs are now multiplicative instead of additive (neutral value is now 1 instead of 0)

• IMPORTANT: The sound itself is now part of the payload of all sound events (ie. not bus/recording ones), including stream packets

• IMPORTANT: The stream name of a stream event is now part of the stInfo substructure

• IMPORTANT: The send of a stream packet is now the object, consistent with other non-recording/non-bus sound events

• IMPORTANT: Added the concept of group to orxLocale: text, texture & sound can now be optionally localized independently (as well as user-defined custom groups)

• IMPORTANT: Config property Object.FXDelayList has been removed & orxObject_Add[Unique]FXRecursive() now take a propagation delay parameter

• IMPORTANT: GLFW display plugin now sets max shader version to 410 as 'varying' has been removed in 420

• IMPORTANT: orxInput_EnableSet() now creates the set if it wasn't already present

• IMPORTANT: orxArchive now accepts root paths in storage definitions, using : as separator (eg. Texture = data.zip:texture)

• IMPORTANT: The C locale is now enforce upon initialization to prevent any conversion issues if the locale was modified by an external library such as GTK

• IMPORTANT: Object name is now available from inside orxOBJECT_EVENT_PREPARE event handlers

• IMPORTANT: Spawners with UseSelfAsParent will now detach spawned objects upon deletion to maintain their location with respect to the world

• IMPORTANT: Renamed orxAnim_GetNextEvent() -> orxAnim_GetEventAfter() & Added newer version of orxAnim_GetNextEvent() to support multiple 0-length frames in a row or events associated to a 0-length frame

• IMPORTANT: orxResource_Seek() & orxResource_Tell() now returns -1 upon failure

• IMPORTANT: Added config property Display.DebugOutput to enable OpenGL debug output when available (OpenGL 4.3+)

• Migrated init & setup utilities from Ren-C to Oldes Rebol3 for better future proofing and better platforms support

• Setup will not create .bash_profile anymore on Linux/MacOS if it didn't already exist

• Added UNC paths support to orxFile on Windows

• Added convenience helpers orxCOMMAND_REGISTER() & orxCOMMAND_UNREGISTER()

• Added read-only config property Display.MaxTextureSize, filled during display's initialization

• orxColor_ToRGBA() now rounds RGB components during conversion (was flooring before)

• Color literals aliases now inherits from local section: this permits to derive the Color section for local overrides while maintaining alias consistency

• orxDisplay_SetVideoMode() now accepts zero-ed values for width, height, depth & refresh rate and will use current desktop values instead

• orxSpawner_GetWaveSize() will now always return the spawner's wave size value, even when not in wave mode

• orxSpawner_Spawn() can now accept orxU32_UNDEFINED as count to use the spawner's internal wave size

• orxConfig_ReloadHistory() will not clear sections that were not originating from a file anymore (such as [Color])

• Added command Config.RenameSection

• Added orxRemote init extension to access remote resource over HTTP/1.1 (mostly intended as proof-of-concept/dev feature)

• Added orxTexture_Get() to replace orxTexture_CreateFromFile()/orxTexture_Delete() calls when dealing with known existing textures

• Fixed frame children hierarchy not being correctly re-processed when a frame was deleted

• orxResource_ClearCache() can now take an optional group as parameter & added command Resource.ClearCache

• orxResource_RemoveStorage() (and command Resource.RemoveStorage) can now target all groups and/or all storages in a single call

• Added orxResource_Sync() to update all cached resource based on current group/storage definitions and command Resource.Sync

• orxArchive now reads/decompresses inside Read() (previously inside Open()) so as to not block calling thread

• Added bLast field to stream packets to allow stream termination from an event handler

• The number of channels and the sample rate of an empty music stream can now be defined in config

• Added orxInput_RemoveSet(), orxINPUT_EVENT_REMOVE_SET event & Input.RemoveSet command

• Added support for HTML web colors to viewport's BackgroundColor property

• Better handling of web literals/vector values mixes (ie. list-based randoms) for object, viewport, FX and graphic color properties

• Added commands Object.GetActiveTime, Object.ApplyTorque, Object.ApplyForce & Object.ApplyImpulse

• Added orxObject_[Get|Set][Literal]IgnoreFlags() and commands Object.SetIgnoreFlags & Object.GetIgnoreFlags

• Publicly exposed orxObject_SetLiteralLifeTime()

• Added orxObject_SetClockRecursive() & optional recursive argument to Object.SetClock

• Added FX config property Stagger to add an FX after all current existing ones, along with an optional signed time offset (which doesn't require Stagger) and orxFX_[Get|Set]Stagger()

• Added FX slot config property Stagger to add an FX slot after all current existing ones

• Added orx[Object|FXPointer]_[Get|Set]Frequency(), orxObject_SetFXFrequencyRecursive(), commands Object.[Get|Set]FXFrequency & config property Object.FXFrequency

• Added config property Object.FXRecursiveList to recursively apply FXs from the FXList property

• FX slots will now default to a linear curve when none is provided in config

• Better ANSI terminal detection on mac/XCode

• Non-config backed texts are not considered during config hot-reload anymore

• Updated orxStructure_LogAll & Command.LogAllStructures/Structure.LogAll to optionally log private structures

• Added orxGraphic_GetAlignFlags() & orxGraphic_AlignVector()

• Added Viewport.GetCorrectionRatio command

• Default stream sample rate if now 48kHz (previously 44.1kHz)

• Fixed NvOptimus/AmdPowerExpress exports in init template for non-MSVC Windows builds

• Better support for multiple partial init/exit of orx (ie. only specific modules) during a single life cycle of the application

• 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.13. 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 (+SOIL) plugins for display, joystick, keyboard and mouse for all non-iOS/non-Android platforms
• OpenAL-based (+libsndfile/stb_vorbis/tremor) plugins for sound for all platforms
• Box2D-based plugin for physics
• homemade plugin for 2D rendering
• OpenGL ES plugins for display on iOS and Android
• Touch/MultiTouch-based plugin for mouse on iOS and Android
• Accelerometer-based plugin for joystick on iOS and Android

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

NB: The debug version is far slower than the release one, but will output all the warning
and error messages useful during development.

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.

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 either
post them on orx's forum,
come chat with us
or send them directly by email to iarwain [at] orx-project.org

Enjoy!