991 lines
93 KiB
Plaintext
991 lines
93 KiB
Plaintext
namespace Urho3D
|
|
{
|
|
|
|
/**
|
|
\page Building Building Urho3D library
|
|
|
|
\tableofcontents
|
|
|
|
\section Building_Prerequisites Building prerequisites
|
|
|
|
Although all required third-party libraries are included as source code, there are system-level dependencies that must be satisfied before Urho3D can be built successfully:
|
|
|
|
- For Windows, the June 2010 DirectX SDK needs to be installed. This is not necessary if building on Visual Studio 2012 or newer, which install the Windows SDK with the necessary DirectX files.
|
|
|
|
- For Linux, install one or more of the development packages from each software component category below. Building as 32-bit on a 64-bit system requires installing also the 32-bit versions of the development libraries.
|
|
+ %Database server (optional). Disabled by default even when the development package is installed, use URHO3D_DATABASE_ODBC=1 to enable. The two packages below are mutually exclusive. The ODBC driver manager is the recommended package.
|
|
- libiodbc2-dev (Debian-based) or libiodbc-devel (RedHat-based) for iODBC driver manager.
|
|
- unixodbc-dev (Debian-based) or unixODBC-devel (RedHat-based) for ODBC driver manager.
|
|
+ Display server (essential). One or more of these can be installed at the same time. When multiple display servers are available, X11 takes precedence (overridable using SDL_VIDEODRIVER environment variable during application runtime).
|
|
- libdirectfb-dev (Debian-based only) for Direct Frame Buffer (DirectFB). Disabled by default even when installed, use VIDEO_DIRECTFB=1 to enable.
|
|
- libegl1-mesa-dev, libwayland-dev, and wayland-protocols (Debian-based) or libwayland-client-devel, libwayland-cursor-devel, libxkbcommon-devel, mesa-libEGL-devel, mesa-libwayland-egl-devel, and wayland-protocols-devel (RedHat-based) for Wayland.
|
|
- libx11-dev, libxcursor-dev, libxext-dev, libxi-dev, libxinerama-dev, libxrandr-dev, libxrender-dev, libxss-dev, and libxxf86vm-dev (Debian-based) or libX11-devel, libXcursor-devel, libXext-devel, libXi-devel, libXinerama-devel, libXrandr-devel, libXrender-devel, libXScrnSaver-devel, and libXxf86vm-devel (RedHat-based) for X11 and its extensions. Alternatively, you can use xorg-devel meta package on Debian-based system, but it would install other unneeded packages as well.
|
|
+ %Sound server (essential). One or more of these can be installed at the same time. When multiple sound servers are available, PulseAudio takes precedence (overridable using SDL_AUDIODRIVER environment variable during application runtime).
|
|
- libasound2-dev (Debian-based) or alsa-lib-devel (RedHat-based) for Advanced Linux %Sound Architecture (ALSA).
|
|
- arts-devel (RedHat-based only) for Analog Real %Time Synthesizer (aRts).
|
|
- libaudio-dev (Debian-based only) for %Network %Audio System (NAS).
|
|
- libesd0-dev (Debian-based) or esound-devel (RedHat-based) for Enlightened %Sound Daemon (ESounD).
|
|
- libfusionsound-dev (Debian-based only, not available on Ubuntu) for FusionSound. Disabled by default even when installed, use FUSIONSOUND=1 to enable.
|
|
- libpulse-dev (Debian-based) or pulseaudio-libs-devel (RedHat-based) for PulseAudio.
|
|
- libroar-dev (Debian-based only) for RoarAudio (SNDIO).
|
|
+ %Input method editor (optional). One or both of these can be installed at the same time to enable the IME support in the game engine. When both frameworks are installed on user's host system, the application uses XMODIFIFIERS environment variable to determine which one is active.
|
|
- libibus-1.0-dev (Debian-based) or ibus-devel (RedHat-based) for Intelligent %Input Bus (ibus).
|
|
- fcitx-libs-dev (Debian-based) or fcitx-devel (RedHat-based) for Flexible %Input Method Framework (fcitx).
|
|
+ Miscellaneous (optional).
|
|
- libdbus-1-dev (Debian-based) or dbus-devel (Redhat-based) for system-wide messaging (e.g. inhibiting screen-saver).
|
|
- libreadline6-dev (Debian-based) or readline-devel (Redhat-based) for easy editing of command lines in interactive standalone host tools, e.g. isql and lua interpreter.
|
|
- libts-dev (Debian-based) or tslib-devel (RedHat-based) for resistive, single-touch touchscreen input for embedded Linux device, e.g. Pandora and Wiz. Modern multi-touch touchscreen does not need this.
|
|
- libudev-dev (Debian-based) or systemd-devel (Redhat-based) for input device hot-plugging.
|
|
+ HTTPS support (optional).
|
|
- libssl-dev (Debian-based)
|
|
- openssl (OS X using homebrew)
|
|
|
|
- For Raspberry Pi, follow the building prerequisite for Linux above, with the exception for display server. Raspberry Pi operating system usually already comes with Broadcom Video Core display server preinstalled. On top of that, you must also install this package: libevdev2 (Raspbian) or libevdev (Pidora).
|
|
|
|
- For macOS, iOS, and tvOS, the Xcode developer tools package should include everything necessary. Make sure that the Xcode command line tools are also installed. Homebrew is required to install 'cmake' and some of the optional development packages, such as ccache, doxygen, graphviz, and readline.
|
|
|
|
- For Android, the Android Studio (version 4.0 or later) should include everything necessary. Make sure the Android NDK r21d is installed with the Android SDK Manager and CMake version 3.17.3 is installed on the host machine. Adjust the "buildSrc/src/main/kotlin/UrhoCommon.kt" accordingly if your host has different NDK and CMake version.
|
|
|
|
- For Web, the Emscripten SDK (version 1.39.0 or later) needs to be installed with the upstream LLVM WASM backend is activated. On Windows host also MinGW-W64 compiler toolchain is required.
|
|
|
|
To run Urho3D, the minimum system requirements are:
|
|
|
|
- Windows: CPU with SSE2 instructions support, Windows XP or newer, DirectX 9.0c, GPU with %Shader %Model 3 support.
|
|
|
|
- macOS: CPU with SSE2 instructions support, GPU with OpenGL 2.0 support, EXT_framebuffer_object and EXT_packed_depth_stencil extensions, OS version 10.9 or newer.
|
|
|
|
- Linux: any CPU (MMX, 3DNow!, and SSE/SSE2 instructions will be used if supported), GPU with OpenGL 2.0 support, EXT_framebuffer_object and EXT_packed_depth_stencil extensions.
|
|
|
|
- Raspberry Pi: %Model B revision 2.0 with at least 128 MB of 512 MB SDRAM allocated for GPU.
|
|
|
|
- Android: Jelly Bean 4.1 (API level 16) or newer, OpenGL ES 2.0 capable GPU.
|
|
|
|
- iOS: armv7, iPhone 3GS or newer including iPad, OS version 3 or newer.
|
|
|
|
- tvOS: arm64, OS version 9 or newer.
|
|
|
|
- Web: modern HTML5 browsers with fast JavaScript engine and WebGL support. Nightly built browsers are required for running WebAssembly target.
|
|
|
|
SIMD requirement can be eliminated by disabling the use of SIMD instruction set, see URHO3D_SSE build option below. For Linux platform using GCC/Clang compiler toolchain, the MMX and 3DNow! extensions can be enabled for older CPUs by using URHO3D_MMX and URHO3D_3DNOW build options when the option is available (they are disabled by default). The MMX and SSE extensions on x86_64 ABI are always enabled, so the URHO3D_MMX and URHO3D_SSE build option do not exist on x86_64 ABI (they are always on). Also note that MMX extension is effectively enabled when 3DNow! or SSE extension is enabled, so disabling URHO3D_MMX build option in this case has no effect.
|
|
|
|
The NEON instruction set will be used by default whenever it is available. See the ANDROID_ABI and RPI_ABI build options for more detail for Android and Raspberry-Pi platforms, respectively. The NEON instruction set is always used on iOS and tVOS platforms.
|
|
|
|
CMake (https://www.cmake.org) is required to configure and generate the Urho3D project build tree. The minimum required version is 3.10.2. However, it is recommended to use the latest CMake version available, especially when targeting Apple platforms using its latest Xcode version available. This is because Apple is known to change the internal working of Xcode with little regards to other third party build tools, such as CMake.
|
|
|
|
\section Build_Scripts Build scripts
|
|
|
|
As this is a cross-platform project, we have provided a number of build scripts in the "script" directory for the most common use cases, with the exception for Android platform. The shell scripts end with extension *.sh are meant for building Urho3D project in a Unix-like host system (Linux, Mac, and even Raspberry Pi), while the batch files end with *.bat are meant for Windows host system only. They only provide a convenient way to invoke CMake to process our CMakeLists.txt files. Their usage is not a must as you can also invoke CMake to do the same via cmake-gui or via your IDE when your IDE supports that.
|
|
|
|
The basic usage is as follows:
|
|
|
|
\verbatim
|
|
<script-name> /path/to/build-tree [build-options]
|
|
\endverbatim
|
|
|
|
Where the <script-name> is one of the provided build script. The /path/to/build-tree is where CMake will be generating the build tree for the project. Both out-of-source build tree and non out-of-source build tree path are now supported. The build options are described in detail in the next section below.
|
|
|
|
After the build tree has been generated, you can use the build script again to reconfigure it by passing different build options. You can do so as the basic usage above; or by first change the working directory to the already generated build tree and use the following syntax:
|
|
|
|
\verbatim
|
|
<script-name> [build-options]
|
|
\endverbatim
|
|
|
|
Naturally you have to specify a fully qualified path to the build script for this to work. Alternatively, you can add the path to the Urho3D project root to the PATH environment variable in order to make the build scripts available everywhere.
|
|
|
|
Our CMakeLists.txt files are designed to work with most of the generators supported by CMake: Makefile, Xcode, VS, and even Ninja. Which build script to use is determined by which CMake generator (and toolchain) you intend to use in your build tree. For native build, you can just use cmake_generic.sh or cmake_generic.bat to let CMake to detect and decide which generator to use automatically. CMake should default to use "Unix Makefiles" generator on Linux and Mac host systems and it should default to use 32-bit "Visual Studio" generator on Windows host system when it is installed.
|
|
|
|
Since Urho3D version 1.8 we have integrated with Gradle build system for Android platform. We have provided Gradle wrapper script and batch file at the project root directory to interface with Gradle build system. Currently it is the only platform that does not allow user to interface with CMake build system directly. See \ref Building_Android for more detail.
|
|
|
|
\section Build_Options Build options
|
|
|
|
A number of build options can be defined when invoking the build scripts or when configuring the project interactively using cmake-gui. To use one of these build options on the command line interface, pass it in this format "-DOPTION=VALUE" without the quotes. Most of the build options are boolean variables where setting their values to 0 means disabling a feature or setting an option to false, while 1 means enabling a feature or setting an option to true. The table below shows all the available build options and their default values. Non-boolean build options generally do not have any default values and are marked with '-' in the table. However, a few build options marked with '*' have their default values set differently based on the value of other variables or external factors.
|
|
|
|
|Build Option |Value|Description |
|
|
|---------------------|-----|---------------------|
|
|
|ARM |0|Configure project using ARM cross-compiler toolchain (cmake_generic.sh only), cmake-gui users need to specify ARM toolchain file for cross-compiling explicitly|
|
|
|RPI |0|Configure project using Raspberry Pi cross-compiler toolchain (cmake_generic.sh only), cmake-gui users need to specify RPI toolchain file for cross-compiling explicitly|
|
|
|MINGW |0|Configure project using MinGW (32-bit or 64-bit) cross-compiler toolchain (cmake_generic.bat and cmake_generic.sh only), cmake-gui users need to specify MinGW toolchain file for cross-compiling explicitly|
|
|
|WEB |0|Configure project using Emscripten cross-compiler toolchain (cmake_generic.bat and cmake_generic.sh only), cmake-gui users need to specify Emscripten toolchain file for cross-compiling explicitly|
|
|
|IOS |0|Configure project for targeting iOS platform (cmake_generic.sh and cmake-gui only)|
|
|
|TVOS |0|Configure project for targeting tvOS platform (cmake_generic.sh and cmake-gui only)|
|
|
|URHO3D_64BIT |*|Enable 64-bit build, the default is set based on the native ABI of the chosen compiler toolchain|
|
|
|URHO3D_ANGELSCRIPT |1|Enable AngelScript scripting support|
|
|
|URHO3D_FORCE_AS_MAX_PORTABILITY|0|Use generic calling convention for AngelScript on any platform|
|
|
|URHO3D_LUA |1|Enable Lua scripting support|
|
|
|URHO3D_LUAJIT |1|Enable Lua scripting support using LuaJIT (check LuaJIT's CMakeLists.txt for more options)|
|
|
|URHO3D_LUAJIT_AMALG |*|Enable LuaJIT amalgamated build (LuaJIT only); default to true when LuaJIT is enabled|
|
|
|URHO3D_SAFE_LUA |0|Enable Lua C++ wrapper safety checks (Lua/LuaJIT only)|
|
|
|URHO3D_LUA_RAW_SCRIPT_LOADER |0|Prefer loading raw script files from the file system before falling back on Urho3D resource cache. Useful for debugging (e.g. breakpoints), but less performant (Lua/LuaJIT only)|
|
|
|URHO3D_IK |1|Enable inverse kinematics support|
|
|
|URHO3D_NETWORK |1|Enable Networking support|
|
|
|URHO3D_SSL |0|Enable HTTPS support for HttpRequest. Requires URHO3D_NETWORK build option to be enabled|
|
|
|URHO3D_SSL_DYNAMIC |0|Enables dynamic SSL library loading, requires URHO3D_SSL build option to be enabled|
|
|
|URHO3D_PHYSICS |1|Enable Physics support|
|
|
|URHO3D_NAVIGATION |1|Enable Navigation support|
|
|
|URHO3D_URHO2D |1|Enable 2D rendering & physics support|
|
|
|URHO3D_PLAYER |1|Build Urho3D script player|
|
|
|URHO3D_SAMPLES |1|Build sample applications|
|
|
|URHO3D_TOOLS |1|Build tools (native, RPI, and ARM on Linux only)|
|
|
|URHO3D_EXTRAS |0|Build extras (native, RPI, and ARM on Linux only)|
|
|
|URHO3D_DOCS |0|Generate documentation as part of normal build (the 'doc' builtin target can be used to generate documentation regardless of this option's value)|
|
|
|URHO3D_DOCS_QUIET |0|Generate documentation as part of normal build, suppress generation process from sending anything to stdout|
|
|
|URHO3D_PCH |1|Enable PCH support|
|
|
|URHO3D_DATABASE_ODBC |0|Enable %Database support with ODBC, requires vendor-specific ODBC driver|
|
|
|URHO3D_DATABASE_SQLITE|0|Enable %Database support with SQLite embedded|
|
|
|URHO3D_WEBP |1|Enable WebP image support|
|
|
|URHO3D_MMX |0|Enable MMX instruction set (32-bit Linux platform only); the MMX is effectively enabled when 3DNow! or SSE is enabled; should only be used for older CPU with MMX support|
|
|
|URHO3D_3DNOW |0|Enable 3DNow! instruction set (Linux platform only); should only be used for older CPU with (legacy) 3DNow! support|
|
|
|URHO3D_SSE |*|Enable SIMD instruction set (32-bit Web and Intel platforms only, including Android on Intel Atom); default to true on Intel and false on Web platform; the effective SSE level could be higher, see also URHO3D_DEPLOYMENT_TARGET and CMAKE_OSX_DEPLOYMENT_TARGET build options|
|
|
|URHO3D_MINIDUMPS |1|Enable minidumps on crash (VS only)|
|
|
|URHO3D_FILEWATCHER |1|Enable filewatcher support|
|
|
|URHO3D_HASH_DEBUG |0|Enable %StringHash reversing and hash collision detection at the expense of memory and performance penalty|
|
|
|URHO3D_PACKAGING |0|Enable resources packaging support|
|
|
|URHO3D_PROFILING |1|Enable default profiling support|
|
|
|URHO3D_TRACY_PROFILING|0|Enable extended profiling support using Tracy Profiler; overrides URHO3D_PROFILING option|
|
|
|URHO3D_LOGGING |1|Enable logging support|
|
|
|URHO3D_THREADING |*|Enable thread support, on Web platform default to 0, on other platforms default to 1|
|
|
|URHO3D_TESTING |0|Enable testing support|
|
|
|URHO3D_TEST_TIMEOUT |*|Number of seconds to test run the executables (when testing support is enabled only), default to 10 on Web platform and 5 on other platforms|
|
|
|URHO3D_OPENGL |0|Use OpenGL instead of Direct3D (Windows platform only)|
|
|
|URHO3D_D3D11 |0|Use Direct3D11 instead of Direct3D9 (Windows platform only); overrides URHO3D_OPENGL option|
|
|
|URHO3D_STATIC_RUNTIME|0|Use static C/C++ runtime libraries and eliminate the need for runtime DLLs installation (VS only)|
|
|
|URHO3D_WIN32_CONSOLE |0|Use console main() instead of WinMain() as entry point when setting up Windows executable targets (Windows platform only)|
|
|
|URHO3D_MACOSX_BUNDLE |0|Use MACOSX_BUNDLE when setting up macOS executable targets (macOS platform only)|
|
|
|URHO3D_LIB_TYPE |STATIC|Specify Urho3D library type, possible values are STATIC (default) and SHARED (not available for Emscripten)|
|
|
|URHO3D_SCP_TO_TARGET |-|Use scp to transfer executables to target system (RPI and generic ARM cross-compiling build only), SSH digital key must be setup first for this to work, typical value has a pattern of usr@tgt:remote-loc|
|
|
|URHO3D_UPDATE_SOURCE_TREE|0|Enable commands to copy back some of the generated build artifacts from build tree to source tree to facilitate devs to push them as part of a commit (for library devs with push right only)|
|
|
|URHO3D_GENERATEBINDINGS|0|Enable script API binding generation|
|
|
|URHO3D_USE_LIB64_RPM |0|Enable 64-bit RPM CPack generator using /usr/lib64 and disable all other generators (Debian-based host only, which uses /usr/lib by default)|
|
|
|URHO3D_USE_LIB_DEB |0|Enable 64-bit DEB CPack generator using /usr/lib and disable all other generators (Redhat-based host only, which uses /usr/lib64 by default)|
|
|
|URHO3D_HOME |-|Path to Urho3D build tree or SDK installation location (downstream project only)|
|
|
|URHO3D_DEPLOYMENT_TARGET|native|Specify the minimum CPU type on which the target binaries are to be deployed (non-ARM platform only), see GCC/Clang's -march option for possible values; Use 'generic' for targeting a wide range of generic processors|
|
|
|CMAKE_BUILD_TYPE |Release|Specify CMake build configuration (single-configuration generator only), possible values are Release (default), RelWithDebInfo, and Debug|
|
|
|CMAKE_INSTALL_PREFIX |*|Install path prefix, prepended onto install directories; default to 'c:/Program Files/Urho3D' on Windows host and '/usr/local' on all other non-Windows hosts|
|
|
|CMAKE_OSX_DEPLOYMENT_TARGET|-|Specify macOS deployment target (macOS platform only); default to current running macOS if not specified, the minimum supported target is 10.9|
|
|
|IPHONEOS_DEPLOYMENT_TARGET|-|Specify iOS deployment target (iOS platform only); default to latest installed iOS SDK if not specified, the minimum supported target is 3.0 due to constraint from SDL library|
|
|
|APPLETVOS_DEPLOYMENT_TARGET|-|Specify AppleTV OS deployment target (tvOS platform only); default to latest installed tvOS SDK if not specified, the minimum supported target is 9.0|
|
|
|MINGW_PREFIX |-|Prefix path to MinGW cross-compiler tools (MinGW cross-compiling build only)|
|
|
|MINGW_SYSROOT |-|Path to MinGW system root (MinGW only); should only be used when the system root could not be auto-detected|
|
|
|DIRECTX_INC_SEARCH_PATHS|-|Additional search paths to find DirectX headers (MinGW only)|
|
|
|DIRECTX_LIB_SEARCH_PATHS|-|Additional search paths to find DirectX libraries (MinGW only)|
|
|
|DIRECT3D_DLL_REDIST_SEARCH_PATHS|-|Additional search paths to find DirectX runtime DLL (MinGW only); should only be used for older MinGW version that still uses 'd3dcompiler_43.dll' or 'd3dcompiler_42.dll'.|
|
|
|RPI_PREFIX |-|Prefix path to Raspberry Pi cross-compiler tools (RPI cross-compiling build only)|
|
|
|RPI_SYSROOT |-|Path to Raspberry Pi system root (RPI cross-compiling build only)|
|
|
|RPI_ABI |*|Specify target ABI (RPI platform only), possible values are RPI0, RPI1, RPI2, RPI3, RPI4|
|
|
|ARM_PREFIX |-|Prefix path to ARM cross-compiler tools (ARM on Linux cross-compiling build only)|
|
|
|ARM_SYSROOT |-|Path to ARM system root (ARM on Linux cross-compiling build only)|
|
|
|ARM_ABI_FLAGS |-|Specify ABI compiler flags (ARM on Linux platform only); e.g. Orange-Pi Mini 2 could use '-mcpu=cortex-a7 -mfpu=neon-vfpv4'|
|
|
|EMSCRIPTEN_ROOT_PATH |-|Root path to Emscripten cross-compiler tools (Emscripten only)|
|
|
|EMSCRIPTEN_SYSROOT |-|Path to Emscripten system root (Emscripten only)|
|
|
|EMSCRIPTEN_AUTO_SHELL|1|Auto adding a default HTML shell-file when it is not explicitly specified (Emscripten only)|
|
|
|EMSCRIPTEN_ALLOW_MEMORY_GROWTH|1|Enable memory growing based on application demand, default to true as there should be little or no overhead (Emscripten only)|
|
|
|EMSCRIPTEN_TOTAL_MEMORY|*|Specify the total size of memory to be used (Emscripten only); default to 128 MB, must be in multiple of 64 KB|
|
|
|EMSCRIPTEN_SHARE_DATA|0|Enable sharing data file support (Emscripten only)|
|
|
|EMSCRIPTEN_EMRUN_BROWSER|firefox|Specify the particular browser to be spawned by emrun during testing (Emscripten only), use 'emrun --list_browsers' command to get the list of possible values|
|
|
|OPENSSL_ROOT_DIR|-|Root path to OpenSSL directory|
|
|
|
|
Note that the specified build option values are cached by CMake after the initial configuration step. The cached values will be used by CMake in the subsequent configuration. The same build options are not required to be specified again and again. But once a non-default build option value is being cached, it can only be reverted back to its default value by explicitly resetting it. That is, simply by not passing the corresponding build option would not revert it back to its default. One way to revert all the build options to their default values is by clearing the CMake cache by executing cmake_clean.bat or cmake_clean.sh with the location of the build tree as the first argument or by executing it in the build tree itself.
|
|
|
|
\section Building_Native Native build process
|
|
|
|
A native build of Urho3D has two steps:
|
|
|
|
-# Run CMake in the root directory (which is also CMake's source tree) with your preferred generator and toolchain specified to generate the build tree. You can use cmake-gui or the provided batch files or shell scripts on the respective host system. All the batch files and shell scripts expect the build tree location to be passed as the first argument, or to execute them in the build tree itself when reconfiguring the existing build tree.\n
|
|
- Windows: cmake_vs20xx.bat, cmake_mingw.bat, cmake_codeblock.bat, cmake_codelite.bat cmake_ninja.bat, or cmake_generic.bat\n
|
|
- macOS: cmake_xcode.sh, cmake_codeblocks.sh, cmake_codelite.sh, cmake_ninja.sh, or cmake_generic.sh\n
|
|
- Linux: cmake_eclipse.sh, cmake_codeblocks.sh, cmake_codelite.sh, cmake_ninja.sh, or cmake_generic.sh\n
|
|
- Raspberry Pi: cmake_rpi.sh, cmake_eclipse.sh, cmake_codeblocks.sh, cmake_codelite.sh, cmake_ninja.sh, or cmake_generic.sh\n
|
|
-# Use the IDE of your choice to open the CMake's generated project file or solution file in the build tree. Change the build configuration (Debug/Release) and change the built-in target to ALL_BUILD to build all the targets.\n
|
|
- Visual Studio: open Urho3D.sln\n
|
|
- Xcode: open Urho3D.xcodeproj\n
|
|
- CodeBlocks: open Urho3D.cbp\n
|
|
- Eclipse: import project using File|Import "Existing Projects into Workspace"\n
|
|
- Alternatively, on make-based toolchains like GCC / MinGW, execute make in the build tree
|
|
|
|
Note that Eclipse requires CDT plugin to build a C/C++ project.
|
|
|
|
On Windows platform Urho3D can use either Direct3D 9 (default), Direct3D 11 or OpenGL rendering. Other platforms always use OpenGL. Use the CMake options "-DURHO3D_D3D11=1" or "-DURHO3D_OPENGL=1" to choose the non-default APIs.
|
|
|
|
If using MinGW to compile, DirectX headers may need to be acquired separately. They can be copied to the MinGW installation eg. from the following package: https://www.libsdl.org/extras/win32/common/directx-devel.tar.gz. These will be missing some of the headers related to shader compilation, so a MinGW build will use OpenGL by default. To build in Direct3D mode, the MinGW-w64 port is necessary: http://mingw-w64.sourceforge.net/. Using it, Direct3D can be enabled with the "-DURHO3D_OPENGL=0" build option.
|
|
|
|
After the build is complete, the programs can be run from the bin subdirectory in the build tree. These include the Urho3D player application, which can run application scripts, the tools, and C++ sample applications if they have been enabled.
|
|
|
|
The macOS executables can be built with all the resources bundled into a single app directory. In order to enable this, set the URHO3D_MACOSX_BUNDLE build option when configuring the build tree for the macOS platform. The bundled app can be launched just by double-clicking from the Finder without worrying about setting the 'resource prefix path'. This is because the URHO3D_PREFIX_PATH environment variable has been set internally to point to the resources directory that is already bundled in the app. Note, however, if you do not launch the app via the Apple "Launch Services" (such as when you are debugging or by calling the executable directly inside the bundled app directory via CLI) then you still need to set the 'resource prefix path' manually as described in the previous paragraph. Note that the Mach-O universal binary targets can only be built when Xcode generator is used. All the other generators only build single-arch binary targets.
|
|
|
|
The Windows executables are by default built as Windows application instead of console application. You can set the URHO3D_WIN32_CONSOLE build option to override this. As console application, the standard output and standard error streams of the executable are redirected to console.
|
|
|
|
To run the Urho3D player application from the Visual Studio debugger, set the Urho3DPlayer project as the startup project and enter its relative path and filename into Properties -> Debugging -> Command: ../../../bin/Urho3DPlayer.exe. Additionally, entering -w into Debugging -> Command Arguments is highly recommended. This enables startup in windowed mode: without it running into an exception or breakpoint will be obnoxious as the mouse cursor will likely be hidden. To actually make the Urho3DPlayer application do something useful, it must be supplied with the name of the script file it should load and run. You can try for example the following arguments:
|
|
|
|
\verbatim
|
|
Scripts/NinjaSnowWar.as -w
|
|
\endverbatim
|
|
|
|
To run from Eclipse on Linux, locate and select the Urho3DPlayer executable in the Project Explorer. From the menu, choose "Run Configurations" to create a new launch configuration for "C/C++ Application". Switch to "Arguments" tab, specify the argument required by Urho3DPlayer executable.
|
|
|
|
To run from Xcode on Mac OS X, edit the Product Scheme to set "Run" setting to execute "Urho3DPlayer" in the "Info" tab. In the "Arguments" tab, specify the arguments required by Urho3DPlayer executable. Ensure the check boxes are ticked on the argument entries that you want to be active.
|
|
|
|
\section Building_Android Android build process
|
|
|
|
First, if you are building under Windows host then after checking out the project you need to prepare the "assets" directory of both the "urho3d-lib" and "launcher-app" modules. Due to a bug in Android plugin of the version we are currently using, where it does not honor custom source set with filter setting, we are forced to use asset symlink with the default source set. So in Windows host system, the asset symlinks must be replaced with an equivalent directory link created with MKLINK command. If your account does not allow you to use MKLINK command then use copy command instead to copy the content of the linked directory directly to the "assets" directory. Ensure you have preserved the directory structure, i.e. "urho3d-lib" assets directory has one subdir called "CoreData", while "launcher-app" assets directory has two subdirs: "Data" and "Autoload".
|
|
|
|
Set the ANDROID_CCACHE environment variable to where your "ccache" build tool has been installed. It is highly recommended when it is available for your host system. Set the ANDROID_NDK environment variable to point to your Android NDK, if it is not installed in the default Android SDK location.
|
|
|
|
For CLI user, build the Gradle modules with the following command:
|
|
|
|
\verbatim
|
|
./gradlew build
|
|
\endverbatim
|
|
|
|
or on Windows host:
|
|
|
|
\verbatim
|
|
gradlew.bat build
|
|
\endverbatim
|
|
|
|
After the command finishes successfully, the AAR (Android library) and the APK (Android application) should have been generated in the "build/output" directory of the respective Gradle modules.
|
|
|
|
For Android Studio and IntelliJ IDEA users, open the project using the IDE. It should prompt you to auto-import the Gradle project, accept the default. After the “gradle sync” completes without any error (you may have to retry a few times to get the IDE sync-ed up with the Gradle), press Ctrl+F9 to build the project or Shift+F10 to run the launcher app in the Android device or emulator.
|
|
|
|
The Gradle build script has been setup to automatically pass the matching environment variable as CMake build options, e.g.: "URHO3D_LIB_TYPE=SHARED ./gradlew build". Additionally, it also supports the following Gradle properties.
|
|
|
|
|Gradle Property|Description |
|
|
|---------------|---------------|
|
|
|ANDROID_ABI|A comma-separated list of ABIs for split build configuration; when not specified defaults to universal build|
|
|
|
|
The Gradle properties can be passed by using "-P" Gradle option, e.g.: "./gradlew -P ANDROID_ABI=x86 build".
|
|
|
|
\section Building_iOS_tvOS iOS and tvOS build process (tvOS is still EXPERIMENTAL)
|
|
|
|
Run cmake_ios.sh or cmake_tvos.sh, respectively. This generates an Xcode project named Urho3D.xcodeproj.
|
|
|
|
Open the Xcode project and check the properties for the Urho3D project (topmost in the Project Navigator). In Code Signing, enter your developer identity as necessary. Also ensure you have changed the built-in target to ALL_BUILD to build all the targets. Edit its build scheme to choose debug or release mode. All the samples will be built as Application Bundle, i.e. with all the resources bundled. The library and samples will be built as Mach-O universal binary consisting of multiple archs depending on the chosen platforms.
|
|
|
|
You can choose one of the provided simulator to run the samples directly from the Xcode.
|
|
|
|
\section Building_RaspberryPi Raspberry Pi build process
|
|
|
|
For native build on Raspberry Pi itself, use the similar process for \ref Building_Native "Native build process" described above for Linux platform.
|
|
|
|
For cross-compiling build on a Linux host system, firstly set the RPI_PREFIX environment variable or build option to point to your Raspberry Pi cross-compiling tool are located. You can setup the tool using <a href="http://crosstool-ng.org/">crosstool-NG</a> or just clone one from https://github.com/raspberrypi/tools. Secondly, set the RPI_SYSROOT environment variable or build option to point to your Raspbian or Pidora system root. You must install the Urho3D prerequisites software development packages for Raspberry Pi (see \ref Building_Prerequisites) in the system root before attempting to do the Urho3D cross-compiling build. You are recommended to download the Raspbian system root with Urho3D prerequisite software installed from https://github.com/urho3d/rpi-sysroot. Alternatively, if you have a fast LAN connection then you can also opt to mount the system root on your actual Raspberry Pi device to your host system via SSHFS and set the RPI_SYSROOT to use the mount point.
|
|
|
|
Execute cmake_raspi.sh then go to the build tree to execute make command. You may pass the optional RPI_ABI build option to specifically target for the Raspberry Pi 2. After the build is complete, the ARM executables can be found in the build tree's "bin" subdirectory.
|
|
|
|
You can also build, deploy, run/debug (as C/C++ Remote %Application) using Eclipse IDE. To do that, execute cmake_eclipse.sh with "-DRPI=1" build option set. Import the CMake generated Eclipse project in the build tree into Eclipse's workspace. Build the project as usual. Optionally, use the "URHO3D_SCP_TO_TARGET" build option to automatically deploy the ARM executables to target Raspberry Pi device as part of build process; or configure Eclipse to perform a "download to target path" in the Run/Debug configuration for C/C++ Remote %Application. Either way, you have to configure the Run/Debug configuration to let it know how to reach your target Raspberry Pi device.
|
|
|
|
\section Building_GenericARM Generic ARM build process (EXPERIMENTAL)
|
|
|
|
For native build on ARM board itself, use the similar process for \ref Building_Native "Native build process" described above for Linux platform.
|
|
|
|
> At the moment we only support generic ARM on Linux platform. Other platforms/OSes are not supported yet.
|
|
|
|
For cross-compiling build on a Linux host system, firstly set the ARM_PREFIX environment variable or build option to point to your ARM cross-compiling tools are located. You can setup the tool using <a href="http://crosstool-ng.org/">crosstool-NG</a> or just download one from http://www.linaro.org/downloads/. You need to obtain the little-endian version of the armhf or aarch64 compiler toolchains for setting up a 32-bit or 64-bit build environment, respectively. Secondly, set the ARM_SYSROOT environment variable or build option to point to your generic ARM system root. Similarly you need to obtain the armhf (hard float) sysroot for 32-bit or arm64 (aarch64) sysroot for 64-bit. You must install the Urho3D prerequisites software development packages for Linux platform (see \ref Building_Prerequisites) in the system root before attempting to do the Urho3D cross-compiling build. There are a few ways to obtain and prepare the sysroots yourself but the easiest way is to download the already prepared one from https://github.com/urho3d/armhf-sysroot or https://github.com/urho3d/arm64-sysroot. Alternatively, if you have a fast LAN connection then you can also opt to mount the system root on your actual ARM board to your host system via SSHFS and set the ARM_SYSROOT to use the mount point.
|
|
|
|
Execute cmake_arm.sh then go to the build tree to execute make command. You may pass the optional ARM_ABI_FLAGS build option to specifically target the CPU and FPU on your ARM board. For example: "-mcpu=cortex-a9 -mfpu=neon-fp16" for ODROID-X2, "-mcpu=cortex-a53" for ODROID-C2, "-mcpu=cortex-a7 -mfpu=neon-vfpv4" for Orange Pi, etc. After the build is complete, the ARM executables can be found in the build tree's "bin" subdirectory.
|
|
|
|
You can also build, deploy, run/debug (as C/C++ Remote %Application) using Eclipse IDE. To do that, execute cmake_eclipse.sh with "-DARM=1" build option set. Import the CMake generated Eclipse project in the build tree into Eclipse's workspace. Build the project as usual. Optionally, use the "URHO3D_SCP_TO_TARGET" build option to automatically deploy the ARM executables to target ARM board as part of build process; or configure Eclipse to perform a "download to target path" in the Run/Debug configuration for C/C++ Remote %Application. Either way, you have to configure the Run/Debug configuration to let it know how to reach your target ARM board.
|
|
|
|
\section Building_MinGW MinGW cross-compile build process
|
|
|
|
It is possible to cross-compile Urho3D for Windows using a Linux host system. The process is largely the same as the \ref Building_Native "Linux native build" process described above.
|
|
|
|
To cross-compile, the MinGW compiler toolchain development software package ("mingw-w64" for Debian-based distro; "mingw64-gcc-c++" and "mingw64-winpthreads-static.noarch" for Redhat-based distro) needs to be installed on the system. For activating the MinGW compiler toolchain, and to allow it to find the correct compiler, the MINGW_PREFIX environment variable needs to be set. This variable should be set to the prefix of the compiler name, e.g. /usr/bin/x86_64-w64-mingw32 where it would be used to find /usr/bin/x86_64-w64-mingw32-gcc and /usr/bin/x86_64-w64-mingw32-g++, etc. Optionally you can also set MINGW_SYSROOT environment variable or build option to point to your MinGW system root, if it is not installed in a normal expected location. Adjust the software package name and the path accordingly for mingw32. It is recommended to use mingw64, when it is available for your host system, because it is multilib capable (can target both 32-bit and 64-bit).
|
|
|
|
Execute cmake_mingw.sh then go to the build tree to execute make command. After the build is complete, the Windows executables can be found in the build tree's "bin" subdirectory.
|
|
|
|
\section Building_Emscripten Emscripten build process
|
|
|
|
> WHAT DOESN'T WORK:
|
|
> - Networking. Javascript can only use http and websockets protocols and at the moment it's not supported.
|
|
|
|
This section assumes you have already updated, installed, and activated the latest Emscripten cross-compiler toolchain with upstream LLVM WASM backend on your host system as per described in https://emscripten.org/docs/getting_started/downloads.html.
|
|
|
|
Set the EMSCRIPTEN_ROOT_PATH environment variable or build option to point to the root path of Emscripten cross-compiler tools. Alternatively, call the emsdk_env script to set the EMSCRIPTEN environment variable for you. The Emscripten sysroot path will be derived from the root path, usually from 'system' subdir relative to the root path. However, you can optionally set the EMSCRIPTEN_SYSROOT environment variable or build option to point to another system root path.
|
|
|
|
On Windows host, execute cmake_emscripten.bat. On MacOS or Linux host, execute cmake_emscripten.sh. Then go to the build tree and execute the 'make' command to start the build as usual. You may want to set the URHO3D_SAMPLES build option to build all the samples. You may also optionally set the URHO3D_LUA build option to enable Lua scripting support. If you encounter "Too many open files" warning when archiving the Urho3D static library, follow by "Unresolved symbol" errors on MacOS then you have to increase the soft-limit in your host system before rebuilding the library and all the main targets.
|
|
|
|
For example, to double the limit (which normally defaults to 256 on MacOS):
|
|
\verbatim
|
|
ulimit -Sn 512
|
|
\endverbatim
|
|
|
|
After the commands finish successfully, the HTMLs and its corresponding data files should have been generated in the build tree's "bin" subdirectory, from where it can be launched in a browser.
|
|
|
|
On Windows building with Emscripten requires a MinGW toolchain. The one that can be installed through emsdk may not work correctly, but for example https://sourceforge.net/projects/mingw-w64/ with the default install settings has been known to work.
|
|
|
|
If CMake complains that emcc is not able to compile a test program, try reactivating your current Emscripten cross-compiler tools with 'emsdk activate <sdk-version>', clear all generated *.cmake files as well as the CMake cache, and retry running CMake.
|
|
|
|
\section Building_64bit Native 64bit build
|
|
|
|
When using MSVC compiler, Urho3D common CMake module configures the build tree to target a 32-bit platform by default. When using other non-MSVC compilers (like GCC or Clang), the module sets the default to 32-bit or 64-bit based on the chosen toolchain in the build tree. You can, however, use the "URHO3D_64BIT" build option to override the default, i.e. by setting the option to '0' (for 32-bit) and '1' (for 64-bit) explicitly.
|
|
|
|
\section Building_Library Library build
|
|
|
|
> This section is not applicable for Android platform, which publishes the Android library (AAR) among other artifacts using maven-publish Gradle plugin.
|
|
|
|
The build process first builds the Urho3D library target (either static or shared). The library is then linked against by other targets like tools and samples that reference Urho3D as one of the external libraries. The Urho3D library type is defaulted to static, so the build process would generate standalone executables as previous releases. The Urho3D library type can be changed using "URHO3D_LIB_TYPE" build option.
|
|
|
|
To install the Urho3D library as an SDK, use the usual 'make install' command. There is an equivalent built-in target called "install" in Visual Studio solution and Xcode project to perform the SDK installation. This could be useful when you want your application to always link against a 'stable' installed version of the Urho3D library, while keeping your Urho3D project root tree in sync with origin/master; or when you want other users in the same host system to use the installed Urho3D SDK instead of them building from source again.
|
|
|
|
The default install prefix is 'c:/Program Files/Urho3D' on Windows host and '/usr/local' on all other non-Windows hosts. You can use the CMAKE_INSTALL_PREFIX build option to alter this prefix path. However, when cross-compiling you may actually want to alter the final installation destination by supplying DESTDIR environment variable instead of altering the CMAKE_INSTALL_PREFIX variable directly, especially when using Urho3D library as shared library type because the installed executables have their RPATH adjusted relative to CMAKE_INSTALL_PREFIX. The DESTDIR environment variable is not applicable for installation on Windows host, i.e. it can only use CMAKE_INSTALL_PREFIX variable to alter the final installation destination. This is not a lost, however, because there is no RPATH adjustment for Windows platform, but as the result the Urho3D.dll will be installed in a same directory as the installed executables.
|
|
|
|
If the Urho3D SDK is installed to a system-wide default location then the Urho3D library can be found by FindUrho3D CMake module automatically without the help of URHO3D_HOME environment variable or build option. When cross-compiling, the system-wide default location is usually in the system root of the cross-compiling target. To get a corresponding system root path for a cross-compiling build tree, you can use SYSROOT internal variable stored in the CMake cache. You can then use the system root path to set the DESTDIR environment variable in order to stage the Urho3D SDK installation in the corresponding system root. For example:
|
|
|
|
\verbatim
|
|
cd /path/to/your/Urho3D/build-tree
|
|
DESTDIR=$(grep SYSROOT CMakeCache.txt |cut -d'=' -f2) make install
|
|
\endverbatim
|
|
|
|
Note that SYSROOT variable is empty when the build tree is not setup for cross-compiling.
|
|
|
|
Refer to \ref UsingLibrary on how to setup your own project to use Urho3D library.
|
|
|
|
Urho3D should be built as a shared library if your application consists of multiple modules (main executable + other shared libraries) that all link to Urho3D. The reason for this is that Urho3D contains a few sensitive static data values, such as the main thread's ID, which will not work properly if they are duplicated due to multiple static linkage.
|
|
|
|
\section Building_Docs Documentation build
|
|
|
|
If "URHO3D_DOCS" or "URHO3D_DOCS_QUIET" build option is set then a normal build would not only build Urho3D binaries but also Urho3D documentation automatically. If the option is not set then the documentation can still be built by manually invoking 'make doc' command or using its equivalent built-in target in IDE.
|
|
|
|
The additional prerequisite for documentation build is Doxygen. Also Graphviz (optional) if you wish to generate graphical diagrams in the documentation. MSVC users on Windows host system may install HTML Help Workshop (optional) in order to get the compressed help file (*.chm). When optional tool is not available in the host system, the corresponding build process is skipped accordingly. The internal host tools to dump the \ref ScriptAPI "AngelScript API" for the default \ref Script "scripting" subsystem and the \ref LuaScriptAPI "LuaScript API" (when the LuaScript subsystem is also enabled) are being built at the same time when all the native tools are built. When the build tree is being configured not to build any host tools then the 'doc' target will simply instruct Doxygen to process the existing API dump files that are already pre-generated in the repository.
|
|
|
|
\section Building_Clang_tools Clang-tools build (EXPERIMENTAL)
|
|
|
|
If "URHO3D_CLANG_TOOLS" build option is set then CMake would generate a special build tree for the purpose of developing the Clang-tools. Before doing this, the development software package of LLVM/Clang version 3.9.0 must be already installed in the host system. Alternatively, you can download LLVM/Clang source files from Clang's SVN repo, build and install it into the host system. If it is not installed in a system-wide installation location then use the LLVM_CLANG_ROOT environment variable to point to the root path of this custom location (the root is the parent directory containing the bin, lib, include and share subdirectories). You may want to follow the [Clang's Getting Started instruction](http://clang.llvm.org/get_started.html) to guide you through this.
|
|
|
|
Perhaps the easiest way to get Clang installed is by using Emscripten-SDK. If you have already built Emscripten-SDK in your host system then you can also use the SDK to install the Fastcomp/Clang by navigating to the Fastcomp/Clang build tree (e.g. emsdk_portable/clang/fastcomp/build_master_64) and issuing a 'make install' command. However, Emscripten-SDK does not automatically checkout "extra Clang tools", so before issuing a 'make install' you may want to take a step back to manually checkout the "extra Clang tools" into the corresponding subdirectory in the Fastcomp/Clang source tree (e.g. emsdk_portable/clang/fastcomp/src/tools/clang/tools/extra), then rebuild and install as usual. Using Fastcomp/Clang is fine for our purpose because we are only interested in using Clang as 3rd-party library instead of as compiler.
|
|
|
|
A special note to Linux users, install the development software package for 'libedit' when you want full command line interface features like command history and command editing in clang-query tool. Install it before generating any of the LLVM/Clang or Fastcomp/Clang build tree.
|
|
|
|
Check the Source/Clang-Tools/CMakeLists.txt to get the list of targets currently available or under development. Normal build targets won't work properly in this special build tree. See also https://github.com/urho3d/Urho3D/issues/887 to find out more about the current development plan and leave a comment there if you would like to help to contribute the development.
|
|
|
|
\section Building_Shaders Compiling Direct3D shaders
|
|
|
|
When building for Direct3D9 with the Windows 8 SDK (Visual Studio 2012+), copy d3dcompiler_46.dll from "C:\Program Files (x86)\Windows Kits\8.0\bin\x86" to build tree's "bin" directory so that Urho3D executables will run correctly. When building for Direct3D11, copy d3dcompiler_47.dll from "C:\Program Files (x86)\Windows Kits\8.1\bin\x86" to the "bin" directory. In both cases, if compiling Urho3D as 64-bit, copy from the "bin\x64" directory instead.
|
|
|
|
OpenGL does not depend on a separate shader compiler DLL.
|
|
|
|
\section Dockerized_Build_Environment Dockerized build environment (EXPERIMENTAL on *nix host only)
|
|
|
|
The building prerequisites are understandably different for each target platform. If you want to target multiple platforms with a single build/host system then you have to not only install all of the prerequisites in your host system, but also have to be able to configure your build environment properly so that they do not interfere with each other. Rather than configuring the build environment manually, we have now provided a new build mechanism that we called "dockerized build environment" which addresses both hurdles above. Currently the dockerized build environment, or DBE for short, supports the following platforms: Linux, MinGW (Windows), Android, Raspberry-Pi, generic ARM, and Web.
|
|
|
|
The DBE requires podman (from repository provided by your distro, recommended) or Docker-CE (from https://docs.docker.com/install/) to be installed in the host system and that's all it needs.
|
|
|
|
To use the DBE, execute script/dockerized.sh in the project root directory, specify the platform name (linux|mingw|android|rpi|arm|web) as the mandatory parameter, and optionally followed by an alternative command to be invoked in the docker container. By default the command is to generate a build tree for the specified target platform and then build it. The Urho3D build options can be specified by using environment variables in the host system before executing the dockerized.sh. It could be done just in time as well, e.g. "URHO3D_LIB_TYPE=SHARED script/dockerized.sh mingw". The build artifact from DBE can be found in the usual location as the normal build environment. In fact the build artifacts should function and work as if they are built using conventional way too.
|
|
|
|
The DBE is designed to be used by Urho3D project and its downstream projects which reuse Urho3D build system.
|
|
|
|
|
|
\page Running Running Urho3D player application
|
|
|
|
\tableofcontents
|
|
|
|
\section Running_Description Description
|
|
The Urho3D player application in the bin directory contains all the engine runtime functionality. However, it does not contain any inbuilt logic, and therefore must be supplied with the name of the application script file it should run:
|
|
|
|
\verbatim
|
|
Urho3DPlayer <scriptfilename> [options]
|
|
\endverbatim
|
|
|
|
The scripting language supported by default is AngelScript (http://www.angelcode.com/angelscript); the script files have .as extension and need to be placed under either the bin/Data or bin/CoreData subdirectories so that Urho3DPlayer can find them. An application script is required to have the function void Start(), which will be executed before starting the engine main loop. It is this function's responsibility to initialize the application and to hook up to any necessary \ref Events "events", such as the update that happens every frame.
|
|
|
|
Lua language support can optionally be built in, see \ref Build_Options.
|
|
|
|
If Urho3DPlayer is given no command line arguments at all, it will read the command line from the file bin/Data/CommandLine.txt. This is primarily intended for mobile platforms, where the command line can not be entered. By default the NinjaSnowWar example will be run.
|
|
|
|
\section Running_Commandline Command line options
|
|
|
|
The engine can be configured using the following command line options.
|
|
|
|
\verbatim
|
|
-x <res> Horizontal resolution
|
|
-y <res> Vertical resolution
|
|
-m <level> Enable hardware multisampling
|
|
-v Enable vertical sync
|
|
-t Enable triple buffering
|
|
-w Start in windowed mode
|
|
-s Enable resizing when in windowed mode
|
|
-q Enable quiet mode which does not log to standard output stream
|
|
-b <length> Sound buffer length in milliseconds
|
|
-r <freq> Sound mixing frequency in Hz
|
|
-pp <paths> Resource prefix path(s), separated by semicolons, default to executable path
|
|
The resource prefix paths can also be defined using URHO3D_PREFIX_PATH env-var
|
|
When both are defined, the paths set by -pp takes higher precedence
|
|
-p <paths> Resource path(s) to use, separated by semicolons, default to 'Data;CoreData'
|
|
-pf <files> Resource package file to use, separated by semicolons, default to none
|
|
-ap <paths> Resource autoload path(s), separated by semicolons, default to 'AutoLoad'
|
|
-log <level> Change the log level, valid 'level' values: 'debug', 'info', 'warning', 'error'
|
|
-ds <file> Dump used shader variations to a file for precaching
|
|
-mq <level> Material quality level, default 2 (high)
|
|
-tq <level> Texture quality level, default 2 (high)
|
|
-tf <level> Texture filter mode, default 2 (trilinear)
|
|
-af <level> Texture anisotropy level, default 4. Also sets anisotropic filter mode
|
|
-gl2 Force OpenGL 2 use even if OpenGL 3 is available
|
|
-flushgpu Flush GPU command queue each frame. Effective only on Direct3D
|
|
-borderless Borderless window mode
|
|
-lowdpi Force low DPI mode on Retina display
|
|
-headless Headless mode. No application window will be created
|
|
-landscape Use landscape orientations (iOS only, default)
|
|
-portrait Use portrait orientations (iOS only)
|
|
-monitor <num> Monitor number to use
|
|
-hz <freq> Monitor refresh rate to use
|
|
-prepass Use light pre-pass rendering
|
|
-deferred Use deferred rendering
|
|
-renderpath <name> Use the named renderpath (must enter full resource name)
|
|
-lqshadows Use low-quality (1-sample) shadow filtering
|
|
-noshadows Disable shadow rendering
|
|
-nolimit Disable frame limiter
|
|
-nothreads Disable worker threads
|
|
-nosound Disable sound output
|
|
-noip Disable sound mixing interpolation
|
|
-touch Touch emulation on desktop platform
|
|
\endverbatim
|
|
|
|
|
|
\page Misc_HowTos Miscellaneous how-to's
|
|
|
|
\tableofcontents
|
|
|
|
\section Using_ccache Linux and macOS specific - How to use ccache to speed up build
|
|
|
|
ccache is a compiler cache software available on Linux and Mac OS X host systems. It speeds up the build by bypassing the actual compilation and reusing the result from previous compilation when the cache is hit. As such, this is optional in the build process. In order to enable ccache support and make it work correctly when building/using Urho3D library with GCC/Clang precompiled header enabled, the following environment variables must be set:
|
|
\verbatim
|
|
USE_CCACHE=1
|
|
CCACHE_SLOPPINESS=pch_defines,time_macros
|
|
\endverbatim
|
|
|
|
Failure to do so would cause the precompiled header cannot be used by ccache. When ccache is setup correctly and with more hits than misses then even clean build can be done as fast as incremental build. The ccache support is available for native compiler toolchains as well as all cross-compiler toolchains supported by Urho3D.
|
|
|
|
You may also want to set 'CCACHE_COMPRESS' environment variable to 1 to enable the compression of the cached objects. It is a trade-off between cache size and build time.
|
|
|
|
Ensure the ccache symlinks directory is being added as the first entry in the 'PATH' environment variable so the symlinks of the compiler toolchain is being found first by CMake rather than the actual compiler toolchain. This is especially important for native build. Usually the 'PATH' environment variable has been set correctly for ccache in RedHat-based host system such as Fedora, but it is not the case in Debian-based host system such as Ubuntu nor in Mac OS X host system with homebrew's ccache installation. For the latter case, use "whereis -b ccache" or "brew info ccache" to find out where your ccache symlinks directory is and adjust the 'PATH' environment variable accordingly.
|
|
|
|
Note that these environment variables are used by ccache itself and not by our CMake build rules, so they must remain set in the host system not only while generating the initial project file using CMake but also while building the project later.
|
|
|
|
Xcode IDE and its CLI version, xcodebuild, do not work with ccache out of the box. They probably don't need it because internally they already cache the derived build data. However, if you are performing a lot of switching between different checked out versions of the project source tree or performing a lot of clean build similar to continuous integration build then probably it is more beneficial to hack Xcode/xcodebuild to use ccache. As it is a hack, do the following at your own risk.
|
|
|
|
\verbatim
|
|
cd $(dirname $(xcodebuild -find-executable clang))
|
|
sudo cp -p $(which ccache) .
|
|
for compiler in clang clang++; do sudo mv $compiler{,.orig} && sudo ln -sf $(pwd)/clang.orig /usr/local/bin/$compiler && sudo ln -sf ccache $compiler; done
|
|
\endverbatim
|
|
|
|
Xcode has done something funky internally. It won't build unless the symlink resolves to an executable within its own rooted-'/usr/bin' in Xcode.app package. The 'ccache' executable is physically copied to this location for this reason. But as the result, you have to manually keep this copy up to date when upgrading ccache and also repeat the whole process again as necessary when upgrading Xcode.
|
|
|
|
\section Running_Xcode_AngelScript_Info macOS specific - How to view/edit AngelScript within Xcode
|
|
|
|
By default Mac OS X recognizes file having extension .as as 'AppleSingle Archive'. So, even after associating this file type to always open with Xcode, Xcode is still not able to view/edit the content of the file correctly. In order to view/edit the scripts, after launching the Urho3D project in Xcode, select the .as file(s) in the Project Navigator and then in the %File Inspector (right panel) change the file type from 'Default - AppleSingle archive' to 'C++ Source' in the %File Type drop down list. The current editor view usually does not refresh its content after this change. Selecting another file in the Project Navigator then reselecting the .as file should force the editor to reload and show the .as file correctly afterwards.
|
|
|
|
The drawback of the above approach is, Xcode does not remember it. The steps need to be carried out each time Xcode is relaunched.
|
|
|
|
To solve this permanently, we need to 'hack' the system a little bit to 'fool' Xcode to always treat .as file as one of the C++ source files. Execute the following commands in a terminal as normal user. These commands have been verified to work with Xcode 4.x on Lion and Xcode 5.x on Mountain Lion.
|
|
|
|
\code
|
|
$ cd /System/Library/CoreServices/CoreTypes.bundle/Contents
|
|
$ plutil -convert xml1 Info.plist -o /tmp/Info.plist.xml
|
|
$ sed -i.bak "s/<string>cxx<\/string>/<string>cxx<\/string>\\`echo -e '\n\r'`<string>as<\/string>/g" /tmp/Info.plist.xml
|
|
$ sudo cp -p Info.plist{,.ori}
|
|
$ sudo plutil -convert binary1 /tmp/Info.plist.xml -o Info.plist
|
|
$ find /System/Library/Frameworks -type f -name lsregister -exec {} -kill -r -domain local -domain system -domain user -domain network \;
|
|
\endcode
|
|
|
|
The last command resets the launch service database and rebuilds it, so the changes should take effect immediately when Xcode restarts.
|
|
|
|
\section symlinking_on_windows Windows specific - How to grant non-Administrator user to create symbolic links
|
|
|
|
If you are building Urho3D library or project under Windows host system then you may have seen the build system complaining about the insufficient user privilege to create symbolic links and falling back to hard-copy setup in the build tree. You should inform your Windows Administrator to grant the “Create symbolic links” (SeCreateSymbolicLinkPrivilege) to your user account to avoid this. However, if you are the Administrator of your own Home or Professional Windows host system then you could perform the following to fix the problem. Login using your Administrator account to create a new non-Administrator user account then grant the "Create symbolic links” privilege to that new account as follows:
|
|
|
|
-# Launch "secpol.msc" via Start → Run.
|
|
-# Navigate to Security Settings → Local Policies → User Rights Assignment → Create symbolic links.
|
|
-# Add the account into the security setting.
|
|
|
|
To build Urho3D you have to use the newly created account instead of your original Administrator account because for some reason Windows OS does not honor the “Create symbolic links” privilege if the account having the privilege is also a member of the Administrator group. If you must use your own original account then you have to remove your account from the Administrator group, which means you need another account to become the Administrator. Either way your host OS will have two accounts and only the non-Administrator account works!
|
|
|
|
|
|
\page Examples Examples
|
|
|
|
The examples included with Urho3D consist of two larger applications built in AngelScript, and a set of smaller sample applications provided in both C++, AngelScript and Lua, which demonstrate a specific engine feature.
|
|
|
|
\section Examples_NinjaSnowWar NinjaSnowWar
|
|
|
|
The first of the larger examples is a third-person action game. To start, run NinjaSnowWar.bat or NinjaSnowWar.sh in the bin directory, or use the command Urho3DPlayer Scripts/NinjaSnowWar.as
|
|
|
|
Key and mouse controls:
|
|
|
|
\verbatim
|
|
WSAD Move
|
|
Left mouse Attack
|
|
Space Jump
|
|
ESC Exit
|
|
F1 Toggle console
|
|
F2 Toggle profiling display
|
|
F3 Toggle physics debug geometry
|
|
F4 Toggle octree debug geometry
|
|
F5 Toggle event profiling display
|
|
\endverbatim
|
|
|
|
If a joystick is connected, it can also be used for controlling the player character.
|
|
|
|
NinjaSnowWar also supports client/server multiplayer. To start the server, run the command NinjaSnowWar.bat -server (-headless option can optionally given so that the server will not open a graphics window.) To connect to a server, specify the option -address followed by the server address (for example -address 127.0.0.1). Optionally set client username with the option -username, followed by the desired name. Use -nobgm option to switch music off.
|
|
|
|
\section Examples_Editor Editor
|
|
|
|
The second larger example is a scene and %UI layout editor application written in script. To start, run Editor.bat or Editor.sh, or use the command Urho3DPlayer Scripts/Editor.as
|
|
|
|
For details on how to use the editor, see \ref EditorInstructions.
|
|
|
|
\section Examples_Samples Sample applications
|
|
|
|
The sample applications start from the very simple (a "Hello World" program) and progress to demonstrate more complex engine features. The code is heavily commented and should be easy to follow for learning. The applications display on-screen instructions when run.
|
|
|
|
The AngelScript and Lua versions reside in the bin/Data/Scripts and bin/Data/LuaScripts directories. %Batch files to run each of them are not provided due to their large amount: instead run the player application with the script file name as the parameter, for example Urho3DPlayer Scripts/01_HelloWorld.as
|
|
|
|
The C++ versions need to be explicitly enabled in the build with the CMake option -DURHO3D_SAMPLES=1. When enabled, the executables will be produced into the bin directory and can be run from there. Their source code is in the Source/Samples directory.
|
|
|
|
The samples provide the following common key controls:
|
|
|
|
\verbatim
|
|
ESC Exit
|
|
F1 Toggle console
|
|
F2 Toggle debug HUD
|
|
1 Cycle texture quality
|
|
2 Cycle material quality
|
|
3 Toggle specular lighting
|
|
4 Toggle shadow rendering
|
|
5 Cycle shadow resolution
|
|
6 Cycle shadow filtering quality
|
|
7 Toggle occlusion culling
|
|
8 Toggle dynamic instancing
|
|
9 Take a screenshot and save to the Data directory
|
|
\endverbatim
|
|
|
|
|
|
\page UsingLibrary Using Urho3D library
|
|
|
|
\tableofcontents
|
|
|
|
\section Scaffolding Project scaffolding
|
|
|
|
This section assumes you want to reuse Urho3D build system for your own downstream project. If, however, your project already has a different build system and that you just simply want to use the Urho3D library as an external library then you may want to skip to the next section \ref Using_pkg_config instead.
|
|
|
|
First of all, structure your project similar to Urho3D project as below. Although this is not mandatory, it should increase the chance the CMake modules designed for Urho3D project also works out of the box for your project too. CMake and our CMake modules are case-sensitive. It is recommended that your project adheres to the same naming convention as Urho3D project uses, even when the filesystem in your host system is not case-sensitive.
|
|
|
|
\code
|
|
<PROJECT_ROOT>/
|
|
├ bin/
|
|
│ ├ Data/
|
|
│ └ CoreData/
|
|
├ CMake/
|
|
│ ├ Modules/
|
|
│ └ Toolchains/
|
|
├ CMakeLists.txt
|
|
├ *.cpp and *.h
|
|
└ *.bat or *.sh
|
|
\endcode
|
|
|
|
The physical project root directory is also the logical project source tree in CMake terminology where your project main CMakeLists.txt should reside. The 'bin' directory should contain the 'Data' and 'CoreData' resource subdirs for your own assets. You must copy (or symlink) the 'CMake' subdir from Urho3D project root directory (or from Urho3D SDK installation, which can be found in the 'share/Urho3D/CMake') to your project root directory. You may also want to copy (or symlink) the build scripts from Urho3D project root directory (or from Urho3D SDK installation, which can be found in the 'share/Urho3D/Scripts') to your project root directory, unless you just want to use cmake-gui for your own project configuration and generation. Alternatively, you can add the Urho3D project root directory into the PATH environment variable in your host system in order to make the build scripts available everywhere. The build scripts work together with the Urho3D CMake modules and toolchains to configure and generate your initial project build tree. Both out-of-source build tree (recommended) and non out-of-source build tree are supported. Note that when you configure your project (either via one of the build script or via cmake-gui), you can only pass the \ref Build_Options that are applicable to downstream projects. Be mindful that conflicting build options would be ignored.
|
|
|
|
In your own project root directory, create a main CMakeLists.txt file and add the following lines: (replace MyProjectName and MyExecutableName with the actual names you want)
|
|
|
|
\code
|
|
# Set CMake minimum version
|
|
cmake_minimum_required (VERSION 3.10.2)
|
|
|
|
# Set project name
|
|
project (MyProjectName)
|
|
|
|
# Set CMake modules search path
|
|
set (CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/cmake/Modules)
|
|
|
|
# Include UrhoCommon.cmake module after setting project name
|
|
include (UrhoCommon)
|
|
|
|
# Define target name
|
|
set (TARGET_NAME MyExecutableName)
|
|
|
|
# Define source files
|
|
define_source_files ()
|
|
|
|
# Setup target with resource copying
|
|
setup_main_executable ()
|
|
\endcode
|
|
|
|
The CMAKE_MODULE_PATH is setup so that CMake can find the Urho3D-specific CMake modules provided by Urho3D project inside your own project. The UrhoCommon.cmake is the module where all the reusable commands and macros are defined. It also gives your project cross-platform build capability similar to Urho3D project. It does this by automatically finding the required software library components specific for your target platform and configuring your project to use them together with the platform-specific compiler flags and definitions. It utilizes CMake-provided as well as Urho3D custom-made FindXXX modules to get the work done. So, it is important to get the CMAKE_MODULE_PATH setup correctly in your project early on.
|
|
|
|
Your own project naturally depends on Urho3D project, or to be more precise it depends on Urho3D library. The Urho3D library needs to be built first so that it can be found later by your own project. When using GCC/Clang or one of its derivatives, both Urho3D static and shared libraries could be potentially built/installed at a same location and coexist. In such cases the FindUrho3D.cmake module, the module responsible to find Urho3D software library component and is invoked automatically by the UrhoCommon.cmake module, has precedence to first find the static library type over over shared library type. However, you can use URHO3D_LIB_TYPE build option to override this precedence. When using MSVC compiler, both static and shared libraries could not be built/installed at a same location because both the static library and import library have a same file extension. However, for MSVC, it is possible to have both Release and Debug versions of either static or shared library type built/installed at a same location. In such cases the FindUrho3D.cmake module would automatically utilize both of Release and Debug versions as appropriate in your project for Release and Debug build configuration, respectively, without user intervention.
|
|
|
|
When you build Urho3D library, you have an option to install the library to a installation location in your file system as if Urho3D is an SDK or you can just leave the library where it is in its build tree. Thus, there are two approaches for your project to link against Urho3D library as external library. However, there is really no difference between the two approaches from your project's point of view. The FindUrho3D.cmake module is designed not only able to find Urho3D library from the Urho3D SDK installation, but also from any Urho3D project build tree directly. When searching in Urho3D SDK installed in a system-wide default location then no additional variable need to be set. When searching in a non-default SDK installation or when searching in any Urho3D project build tree then the actual location need to be provided via URHO3D_HOME environment variable (set in the host system) or URHO3D_HOME build option (set using -D at command line or in cmake-gui). That is, use the URHO3D_HOME to hint the build system to locate the library.
|
|
|
|
The define_source_files() and setup_main_executable() are Urho3D-specific macros. The define_source_files() macro is a shorthand to glob all the source files in the current directory. It is equivalent to these commands:
|
|
|
|
\code
|
|
file (GLOB CPP_FILES *.cpp)
|
|
file (GLOB H_FILES *.h)
|
|
set (SOURCE_FILES ${CPP_FILES} ${H_FILES})
|
|
\endcode
|
|
|
|
The setup_main_executable() macro then uses SOURCE_FILES and TARGET_NAME variables to setup a new CMake target that would work on ALL platforms supported by Urho3D. Make sure both your project name and target name are not called 'Urho3D', as this name is reserved for Urho3D project only.
|
|
|
|
If you have prepared your new project as outlined above then you can use the \ref Build_Scripts "build instructions of Urho3D project" to build your own project.
|
|
|
|
Sometimes you may want to have different resource directories to contain your assets than the one used by Urho3D project by convention. For example, you may have them arranged by scenes as follows:
|
|
|
|
\code
|
|
<PROJECT_ROOT>/
|
|
├ bin/
|
|
│ ├ Scene1/
|
|
│ ├ Scene2/
|
|
│ └ Core/
|
|
├ ...
|
|
\endcode
|
|
|
|
If that is the case then you have to tell both the build system and the Urho3D library (more specifically the Engine class) where the resource paths are. Using the above example, you have to tell the build system by calling the define_resource_dirs() macro explicitly and passing it the option to glob your resource directories. The define_resource_dirs() macro is actually being called internally with the default option which glob directory names based on Urho3D project convention, but your project can override that by making the call explicitly in your CMakeLists.txt.
|
|
|
|
\code
|
|
...
|
|
|
|
# Define source files
|
|
define_source_files ()
|
|
define_resource_dirs (GLOB_PATTERNS ${CMAKE_SOURCE_DIR}/bin/Scene* ${CMAKE_SOURCE_DIR}/bin/Core)
|
|
|
|
...
|
|
\endcode
|
|
|
|
You also need to inform the Urho3D library that you have non-conventional resource directory paths. You do that by setting the EP_RESOURCE_PATHS engine parameter, either programmatically during compile time or via '-p' \ref Running_Commandline "command line option" during runtime. In this case you would set it to "Scene1;Scene2;Core" instead of the default "Data;CoreData".
|
|
|
|
Your project may also want to store the resource directories in other location instead of the 'bin' directory where the executable binary resides. For example when creating macOS/iOS/tvOS bundle, all the assets are automatically bundled into another directory outside where the executable binary resides. In fact, you can have them in a few separate parent directories and not just one. That is where the EP_RESOURCE_PREFIX_PATHS engine parameter and '-pp' command line option come into picture. With this you can define an alternate resource prefix path where your resource path would be prepended before locating your assets.
|
|
|
|
\section Using_pkg_config Using pkg-config instead of CMake
|
|
|
|
If for some reason you could not use CMake in your project, you could configure your project to compile and link against Urho3D library from SDK installation using 'pkg-config' tool with the help of 'Urho3D.pc' configuration file (which is installed as part of the SDK installation). If the Urho3D SDK is being installed into a local location (such as /usr/local) or a non-default location, then most likely you would need to specify PKG_CONFIG_PATH environment variable to point to the location of the configuration file for this to work. The 'Urho3D.pc' file contains important information on how to configure your compiler and linker correctly. You can use that information as a reference to configure your own project even when you do not use 'pkg-config' tool.
|
|
|
|
Below are a few invocation examples on a 64-bit RedHat-based distro with local installation:
|
|
|
|
\code
|
|
# To get installed Urho3D version
|
|
PKG_CONFIG_PATH=/usr/local/lib64/pkgconfig pkg-config --modversion Urho3D
|
|
|
|
# To compile and link natively in one liner
|
|
c++ -o Urho3DPlayer Urho3DPlayer.cpp `PKG_CONFIG_PATH=/usr/local/lib64/pkgconfig pkg-config --cflags --libs Urho3D`
|
|
|
|
# To compile and link natively but in separate steps
|
|
export PKG_CONFIG_PATH=/usr/local/lib64/pkgconfig
|
|
c++ -c Urho3DPlayer.cpp `pkg-config --cflags Urho3D`
|
|
c++ -o Urho3DPlayer Urho3DPlayer.o `pkg-config --libs Urho3D`
|
|
|
|
# To cross-compile and link for Raspberry Pi platform
|
|
export CC=${RPI_PREFIX}-c++
|
|
export PKG_CONFIG_SYSROOT_DIR=${RPI_SYSROOT}
|
|
export PKG_CONFIG_PATH=${RPI_SYSROOT}/usr/local/lib/pkgconfig
|
|
$CC -o Urho3DPlayer Urho3DPlayer.cpp `pkg-config --cflags --libs Urho3D`
|
|
|
|
# To cross-compile and link for Windows platform using MinGW cross-compiler (in Debug configuration)
|
|
export CC=${MINGW_PREFIX}-c++
|
|
export PKG_CONFIG_SYSROOT_DIR=${MINGW_SYSROOT}
|
|
export PKG_CONFIG_PATH=${MINGW_SYSROOT}/usr/local/lib/pkgconfig
|
|
$CC -o Urho3DPlayer_d.exe Urho3DPlayer.cpp `pkg-config --variable CFLAGS_DEBUG Urho3D` `pkg-config --cflags --libs Urho3D`
|
|
\endcode
|
|
|
|
\section Using_Rake_Tasks Using rake tasks for project scaffolding and building
|
|
|
|
With [Rake](https://rubygems.org/gems/rake) ruby gem installed, you can quickly setup all the above by simply using the 'scaffolding' rake task.
|
|
|
|
\verbatim
|
|
rake scaffolding dir=/path/to/new/project/root [project=Scaffolding] [target=Main]
|
|
\endverbatim
|
|
|
|
As its name implies, this task just creates a basic project structure for your new project. You may also pass optional "project" and "target" parameters besides the "dir" parameter. Otherwise, you will get the default project name (Scaffolding) and target name (Main) in the main CMakeLists.txt. This task copies the Urho3DPlayer.cpp and Urho3DPlayer.h as placeholders for the source files. Normally, you should replace these two files with your own project source files before invoking one of the build scripts.
|
|
|
|
On Windows host system, this task requires privilege to create symlinks by using mklink command. The task would fail when the Windows user account does not have that privilege. We strongly advise you not to use "Administrator" account just for this purpose. Instead, grant your "normal" user account to have the privilege correctly.
|
|
|
|
WARNING: As of this writing, this rake scaffolding task does not yet create a complete new project suitable for Android platform. In future a custom Gradle scaffolding task will be added to perform this job. You need to supply the missing bits manually yourself for now.
|
|
|
|
The Ruby and Rake are not prerequisite software components for building Urho3D and your projects. However, if you are reading this section this far and that your host system actually already has them installed then you can take advantage of them by utilising the 'rake cmake' and 'rake make' tasks. The former configures and generates the build tree (by invoking one of our build scripts under the hood) and the latter builds the project in the generated build tree (by invoking 'cmake --build' command which in turns calls the respective build tools, such as 'make' or 'xcodebuild', or 'MSBuild.exe') at the convenient of your finger tips in a command line interface.
|
|
|
|
To configure and generate:
|
|
\verbatim
|
|
rake cmake [<generator>] [<platform>] [<option>=<value> [<option>=<value>]] [[<platform>_]build_tree=/path/to/build-tree] [fix_scm]
|
|
\endverbatim
|
|
|
|
To build:
|
|
\verbatim
|
|
rake make [<platform>] [<option>=<value> [<option>=<value>]] [[<platform>_]build_tree=/path/to/build-tree] [numjobs=n] [clean_first] [unfilter]
|
|
\endverbatim
|
|
|
|
The default <generator> when not specified is 'generic', which let CMake to detect and choose what generator is available in the host to use. The possible values are: 'codeblocks', 'eclipse', 'ninja', 'vs2015', 'vs2017', 'vs2019', 'xcode'.
|
|
|
|
The default <platform> when not specified is the native platform of the build host, 'linux', 'macOS', 'win'. The other possible values are: 'android', 'web', 'ios', 'tvos', 'mingw', 'rpi'. Naturally this influences the compiler toolchain being used in the generated build tree.
|
|
|
|
When using the 'rake cmake' task, the <option>=\<value> pairs are optional build options supported by our build scripts as usual. However, the format here does not expect a leading '-D' for each pair. When using the 'rake make' task, the <option>=\<value> pairs are optional build options supported by the respective build tools. For example on iOS/tvOS platform using 'xcodebuild' build tool, one could pass the '-sdk' option as follows: 'rake make ios sdk=iphonesimulator'. Note the absence of leading '-' character in the example. To build a specific built-in target in the project, use the 'target' option, e.g. 'rake make target=install'. In a multi-config project, such as Xcode project or VS solution, use the 'config' option to choose which build configuration to use, e.g. 'rake make config=Release'. For Xcode project building using 'rake make' task, you may optional install the 'xcpretty' filter to address the verbosity of the 'xcodebuild' tool from its standard output stream. On the other hand, pass the 'unfilter' option to get the output from 'xcodebuild' tool unfiltered regardless the 'xcpretty' is installed or not. You can pass the 'clean_first' option to perform a clean build. By default this task invokes the respective build tool to use all the logical CPU cores available, but you can use the 'numjobs' option to override this default.
|
|
|
|
Use the 'build_tree' option to set the path to the desired build tree location. When not specified then the build tree location would be defaulted to '../<platform>-Build', relative to the project root. To avoid repeating the customized build tree locations for each platform, you can set and export them as environment variables. The '<platform_>build_tree' option takes precedence over normal 'build_tree' option. For example with these commands below, the native and RPI build tree will be generated in the ~/custom-native-Build and ~/custom-rpi-Build, respectively, and then build from there.
|
|
|
|
\code
|
|
export native_build_tree=~/custom-native-Build rpi_build_tree=~/custom-rpi-Build
|
|
rake cmake URHO3D_LUAJIT=1 && rake make
|
|
rake cmake rpi URHO3D_LUAJIT=1 && rake make rpi
|
|
\endcode
|
|
|
|
You can in fact set and export any other key/value pair build options as environment variables to avoid repeating yourself when invoking any of our Rake tasks.
|
|
|
|
|
|
\page Structure Overall structure
|
|
|
|
The Urho3D engine compiles into one library. Conceptually it consists of several "sublibraries" that represent different subsystems or functionality. Each of these resides in a subdirectory
|
|
under the Source/Urho3D directory:
|
|
|
|
- Container. Provides STL replacement classes and shared pointers.
|
|
- Math. Provides vector, quaternion & matrix types and geometric shapes used in intersection tests.
|
|
- Core. Provides the execution Context, the base class Object for typed objects, object factories, \ref Events "event handling", threading and profiling.
|
|
- IO. Provides file system access, stream input/output and logging.
|
|
- %Resource. Provides the ResourceCache and the base resource types, including XML documents.
|
|
- %Scene. Provides Node and Component classes, from which Urho3D scenes are built.
|
|
- %Graphics. Provides application window handling and 3D rendering capabilities.
|
|
- %Input. Provides input device access in both polled and event-based mode.
|
|
- %Network. Provides client-server networking functionality.
|
|
- %Audio. Provides the audio subsystem and playback of .wav & .ogg sounds in either 2D or 3D.
|
|
- %UI. Provides graphical user interface elements.
|
|
- Physics. Provides physics simulation.
|
|
- Navigation. Provides navigation mesh generation and pathfinding.
|
|
- Urho2D. Provides 2D rendering components that integrate into the 3D scene.
|
|
- %Script. Provides scripting support using the AngelScript language.
|
|
- %Engine. Instantiates the subsystems from the modules above (except Script, which needs to be instantiated by the application) and manages the main loop iteration.
|
|
|
|
\section Structure_Context Execution context
|
|
|
|
The heart of Urho3D is the Context object, which must always be created as the first in a Urho3D application, and deleted last. All "important" objects that derive from the Object base class,
|
|
such as scene nodes, resources like textures and models, and the subsystems themselves require %Context pointer in their constructor. This avoids both the singleton pattern for subsystems,
|
|
or having to pass around several objects into constructors.
|
|
|
|
The %Context provides the following functionality (described in detail on their own pages):
|
|
|
|
- Registering and accessing \ref Subsystems "subsystems"
|
|
- Creation and reflection facilities per object type: \ref ObjectTypes "object factories" and \ref Serialization "serializable attributes".
|
|
- Sending \ref Events "events" between objects
|
|
|
|
\section Structure_ThirdParty Third-party libraries
|
|
|
|
The third-party libraries used by Urho3D and their purposes are:
|
|
|
|
- AngelScript: scripting language implementation
|
|
- Bullet: physics simulation implementation
|
|
- Civetweb: HTTP requests, use could be expanded to also provide an embedded web server
|
|
- FreeType: font rendering
|
|
- GLEW: OpenGL extensions handling
|
|
- SLikeNet: UDP networking
|
|
- libcpuid: CPU properties detection
|
|
- Lua, LuaJIT, tolua+: Lua scripting implementation and bindings
|
|
- LZ4: data compression for package files
|
|
- MojoShader: HLSL shader reflection after compiling
|
|
- Open Asset Import Library: reading various 3D file formats
|
|
- pugixml: parsing XML files
|
|
- Recast/Detour: navigation mesh and pathfinding implementation
|
|
- SDL: window and OpenGL context creation, input and sound output
|
|
- StanHull: convex hull generation from triangle meshes, used for physics collision shapes
|
|
- stb_image: image loading
|
|
- stb_vorbis: Ogg Vorbis decoding
|
|
|
|
|
|
\page Conventions Conventions
|
|
|
|
Urho3D uses the following conventions and principles:
|
|
|
|
- Left-handed coordinates. Positive X, Y & Z axes point to the right, up, and forward, and positive rotation is clockwise.
|
|
|
|
- Degrees are used for angles.
|
|
|
|
- Clockwise vertices define a front face.
|
|
|
|
- %Audio volume is specified from 0.0 (silence) to 1.0 (full volume)
|
|
|
|
- Path names use slash instead of backslash. Paths will be converted internally into the necessary format when calling into the operating system.
|
|
|
|
- In the script API, properties are used whenever appropriate instead of %Set...() and Get...() functions. If the setter and getter require index parameters, the property will use array-style indexing, and its name will be in plural. For example model->SetMaterial(0, myMaterial) in C++ would become model.materials[0] = myMaterial in script.
|
|
|
|
- Raw pointers are used whenever possible in the classes' public API. This simplifies exposing functions & classes to script, and is relatively safe, because SharedPtr & WeakPtr use intrusive reference counting.
|
|
|
|
- When an object's public API allows assigning a reference counted object to it through a %Set...() function, this implies ownership through a SharedPtr. For example assigning a Material to a StaticModel, or a Viewport to Renderer. To end
|
|
the assignment and free the reference counted object, call the Set...() function again with a null argument.
|
|
|
|
- No C++ exceptions. Error return values (false / null pointer / dummy reference) are used instead. %Script exceptions are used when there is no other sensible way, such as with out of bounds array access.
|
|
|
|
- Feeding illegal data to public API functions, such as out of bounds indices or null pointers, should not cause crashes or corruption. Instead errors are logged as appropriate.
|
|
|
|
- Third party libraries are included as source code for the build process. They are however hidden from the public API as completely as possible.
|
|
|
|
For more details related to the C++ coding style, see also \subpage CodingConventions "Coding conventions".
|
|
|
|
|
|
\page EditorInstructions Editor instructions
|
|
|
|
\tableofcontents
|
|
|
|
The Urho3D editor is a script application that can be run with the Urho3D player application. To start, execute any of these commands: (in the bin directory) Editor.bat, Editor.sh or Urho3DPlayer Scripts/Editor.as
|
|
|
|
All the \ref Running_Commandline "command line options" supported by Urho3D player application are available for Editor as well. Additionally, Editor also supports the following command line options:
|
|
|
|
\verbatim
|
|
-scene </path/to/scene.xml> Load a scene after starting up
|
|
\endverbatim
|
|
|
|
Hint: to get more content to look at, run the Physics sample application (bin/Data/Scripts/11_Physics.as), and press F5. This saves a scene file called Physics.xml into the Data/Scenes subdirectory, which can be loaded in the editor. Scenes utilized by the NinjaSnowWar and SceneAndUILoad examples also exist in the Data/Scenes subdirectory, and the NinjaSnowWar object "prefabs" are in the Data/Objects subdirectory.
|
|
|
|
\section EditorInstructions_Controls Controls (standard style hotkeys)
|
|
|
|
\verbatim
|
|
Left mouse - Select nodes or drag the node transform gizmo. Hold Shift to
|
|
select components instead. Hold Ctrl to multiselect.
|
|
Right mouse - Hold down and move mouse to look around
|
|
Middle mouse - Hold down orbits the camera
|
|
Shift+Middle mouse - Hold down pans the camera
|
|
Mouse wheel - Camera zoom in/out
|
|
WSAD or arrows - Move
|
|
Shift+WSAD - Move faster
|
|
E - Ascend
|
|
Q - Descend
|
|
Shift+E,Q - Ascend or descend faster
|
|
|
|
F/Home - Center view on currently selected
|
|
Numpad5 - Toggle orthographic/perspective camera
|
|
Numpad1 - Front view
|
|
Numpad3 - Right hand view
|
|
Numpad7/9 - Top view
|
|
|
|
Ctrl+Numpad1 - Back view
|
|
Ctrl+Numpad3 - Left view
|
|
Ctrl+Numpad7/9 - Bottom view
|
|
|
|
Ctrl+1,2,3 - Object manipulation mode: move/rotate/scale
|
|
Ctrl+4 - Object selection mode, no manipulation
|
|
Ctrl+5 - Toggle between world and local axes manipulation
|
|
Ctrl+6,7 - Cycle through components to pick: geometries, lights, zones,
|
|
collision shapes; and ui-elements
|
|
Ctrl+arrows - Manipulate node in X & Z directions
|
|
Ctrl+pgup/pgdn - Manipulate node in Y direction
|
|
Ctrl+plus/minus - Scale node uniformly (scale mode only)
|
|
Ctrl+Shift+N - New scene
|
|
Ctrl+O - Open scene
|
|
Ctrl+S - Save scene
|
|
Ctrl+Shift+S - Save scene as
|
|
Ctrl+A - Select all root level nodes
|
|
Ctrl+Shift+A - Deselect all nodes
|
|
Ctrl+X,C,V - Cut/copy/paste node or component
|
|
Ctrl+D - Duplicate node or component
|
|
Ctrl+E - Enable/disable node hierarchy or component
|
|
Ctrl+U - Unparent scene node
|
|
Ctrl+H - Open the scene hierarchy window
|
|
Ctrl+I - Open the attribute inspector window
|
|
Ctrl+P - Toggle scene update on/off
|
|
Ctrl+W - Cycle through solid, wireframe and point rendering
|
|
Ctrl+Z - Undo
|
|
Ctrl+Y - Redo
|
|
Ctrl+Space - Open quick menu
|
|
Alt+I - Toggle component debug icons
|
|
Alt+W - Open color wheel menu
|
|
ESC - Close the file selector or editor settings window
|
|
DEL - Delete node or component
|
|
F1 - Toggle console
|
|
F2 - Toggle rendering debug geometry
|
|
F3 - Toggle physics debug geometry
|
|
F4 - Toggle octree debug geometry
|
|
F5 - Toggle navigation debug geometry
|
|
F11 - Captures a screenshot
|
|
F12 - Toggle UI
|
|
\endverbatim
|
|
|
|
The editor setting "Pan using middle mouse button" switches the controls to the following:
|
|
|
|
\verbatim
|
|
Middle mouse - Hold down pans the camera
|
|
Shift+Middle mouse - Hold down orbits the camera
|
|
\endverbatim
|
|
|
|
The editor setting "Rotate around selection" controls if the camera orbits around selection or the center of the view
|
|
|
|
The PaintSelect-tool usage:
|
|
|
|
\verbatim
|
|
Key C - Enable/Disable PaintSelection-tool (circle) for selecting origins in viewport, Hold Ctrl during painting with circle to enable deselection operation
|
|
Key Space - Show/Hide name for nearly placed origins in viewport while ShowOrigins are enabled in toolbar
|
|
\endverbatim
|
|
|
|
\section EditorInstructions_Controls2 Controls (Blender style hotkeys)
|
|
|
|
Hotkeys list show only differences with standard style
|
|
|
|
\verbatim
|
|
Left mouse - Drag the node manipulator gizmo
|
|
Middle mouse - Hold down orbits the camera
|
|
Shift+middle mouse - Hold down pans the camera
|
|
Right mouse - Select objects
|
|
Shift+F - Enter/Exit camera's flying mode
|
|
G,R,S - Object manipulation mode: move/rotate/scale ( note: camera flying mode must be off to do this manipulation)
|
|
Cycle press G,R,S - Toggle between world and local axes manipulation
|
|
Shift+D - Duplicate node or component
|
|
H - Enable/disable node hierarchy or component
|
|
Alt+H - Enable all nodes hierarchy or component in scene
|
|
Alt+P - Unparent scene node
|
|
Ctrl+P - Parent all selected scene nodes to last selected node
|
|
Z - Cycle through solid, wireframe and point rendering
|
|
M - Show/Hide LayerEditor
|
|
X - Delete node or component
|
|
Alt+D - Smart Duplicate (note: select one of axises on gizmo to show direction for next instance)
|
|
Key "." or Del - Center view on currently selected
|
|
\endverbatim
|
|
|
|
Press right mouse button in the 3D view if you want to defocus the active window without changing the object selection.
|
|
|
|
The "Pan using middle mouse button" option has no effect in Blender hotkeys mode.
|
|
\endverbatim
|
|
|
|
\section EditorInstructions_Workflow Workflow
|
|
|
|
When you start with an empty scene, set the resource path first (%File -> %Set resource path). This is the base directory, under which the subdirectories Models, Materials & Textures will be created as you import assets.
|
|
|
|
Scenes should be saved either into this base directory, or into its immediate subdirectory, named for example Scenes or Levels.
|
|
|
|
Check the Editor settings window so that the camera parameters match the size of the objects you are using.
|
|
|
|
The "Remember resource path" option in the settings window controls whether the resource path you set will be remembered on the next run.
|
|
|
|
The editor settings will be saved on exit to a file Urho3D\Editor\Config.xml in the My Documents directory. Delete this file if you want to revert the settings to defaults.
|
|
|
|
\section EditorInstructions_Editing Editing
|
|
|
|
New scene nodes and components are created from the Create menu at the top. Their attributes can then be edited in the attribute inspector window. Note that the node transform shown is the local transform (offset from parent.)
|
|
|
|
As an alternative to using the transform gizmo, scene nodes can be moved/rotated/scaled by Ctrl + arrow keys and Page Up / Page Down. Press Ctrl+1,2,3 to change the manipulation mode, and Ctrl+4 to toggle between world relative and scene node relative movement.
|
|
|
|
To reparent scene nodes or UI elements, drag and drop them onto the new parent in the scene hierarchy window. Reparenting should retain the effective world transform, so check afterwards from the component window that the local transform is what you expect it to be. Components can not be dragged between nodes, but can be duplicated with cut/copy/paste operations.
|
|
|
|
To reorder nodes or UI elements within the same parent instead of reparenting, hold down Ctrl while dragging and dropping.
|
|
|
|
To locate a scene node from the scene, double-click it in the hierarchy window.
|
|
|
|
To create a user variable into the current node, or delete it, type the variable name into the edit field below the node attributes, and press New or Del buttons next to it. The New button will prompt to choose the variable type.
|
|
|
|
While editing, you can execute script files using the "Run script" item in the %File menu. These are AngelScript files that are executed in immediate mode ie. you do not need to define a function. The editor's scene will be accessible to the script as the global property "scene."
|
|
|
|
Components of same type can be multi-edited. Where attribute values differ, the attribute field will be left blank, but editing the attribute will apply the change to all components.
|
|
|
|
In addition to whole scenes, single scene nodes including all their components and child nodes can be loaded and saved (%File -> Load node, %File -> Save node as.) These can act as "prefabs" for speeding up scene construction. To save a node, it needs first to be selected in the hierarchy window.
|
|
|
|
Primitive geometries (boxes, spheres, cylinders) can be instantiated from the Create menu. Note that these are just ordinary model files in the bin/Data/Models directory; their Blender format source files are in the SourceAssets directory.
|
|
|
|
Additionally a resource browser is available to access the contents of resource directories. Whenever the editor is opened or a scene is loaded the resource browser scans for resources. If at anytime the resources change the reload button can be pressed at the top-right of the resource browser and the resource browser will rescan. Two methods are provided to find resources. A tree view of the folders and a search bar. The search box utilizes a simple string substring of the filename. Resources can also be filtered by type by opening the filter panel which is toggled by the small filter icon. There are lots of contextual options for each resource type such as dragging a resource into the hierarchy view, a %LineEdit, or in the viewport. A right click context menu on a resource in the browser will give additional options per resource type.
|
|
|
|
|
|
\section EditorInstructions_Importing Importing
|
|
|
|
The editor can import models or scenes from all the formats that the Open Asset Import Library supports, see http://assimp.sourceforge.net/main_features_formats.html
|
|
|
|
%Model and scene import work differently: model import will take everything in the source file (for example a Collada scene), and combine it into a single model, with possibly many subgeometries. %Scene import on the other hand will export each source scene node separately, creating multiple models as necessary.
|
|
|
|
When a model is imported, it will also be instantiated into the scene as a new scene node with a StaticModel component.
|
|
|
|
To do the actual importing, the editor will invoke AssetImporter from the same directory where the Urho3DPlayer application was run from, so be sure both are built.
|
|
|
|
If the imported scene has no lights, a single directional light is created, so that you can at least see something.
|
|
|
|
*/
|
|
|
|
}
|