Skip to main content

Create New Project

Create your first UrhoApp project

You need an installed Urho3D library for the desired target platform to proceed. If you have been following along the previous section to install the library then you should be able to create a new project using the library in no time. The most commonly encountered issue by newbie in the past was figuring out how to tell the build script where to find the correct Urho3D library to use. The new rake tasks have been designed to address this issue by providing opinionated sane default for most of the use cases, but without sacrificing the possibility to override the default when necessary.

Project Scaffolding#

All you need is to execute the following command to create a new UrhoApp project.

rake new[UrhoApp,demo]

By default, this task creates a new project named UrhoApp in the ~/projects/ directory. You can override that by specifying explicitly the name of the new project as well as the parent directory where it should be created, as shown in the example above. Next, change directory to the project root of the newly created project and build it. You can build using CLI or IDE too.

info

The UrhoApp project is cross-platform out of the box!

Build UrhoApp project#

Using CLI#

Simply invoke rake build or just rake (as build is the default task). In order to target a specific platform, set the PLATFORM environment variable just before invoking the task. By default, the build task assumes to target native platform of the host machine.

# When using Rake task
PLATFORM=android rake
# When using Gradle wrapper on Linux or Mac
./gradlew build
# When using Gradle wrapper on Windows
gradlew.bat build

Except for Android platform, the task generates the initial build tree under build/<platform>/ relative to the project root. Assuming it was built successfully for Linux platform, you could then run the UrhoApp executable like so:

build/linux/bin/UrhoApp

For Android platform, you would have to use other gradle task (e.g., installDebug) to deploy the UrhoApp to an Android Emulator or actual device.

UrhoApp screenshot on Android platform

Using IDE#

Similar to Urho3D project, the UrhoApp project can be opened directly in the IDE that supports CMake or Gradle build system or by opening the generated project file in the build tree.

caution

Do not update the Android Gradle Plugin when being prompted, unless you know what you are doing.

  • Choose "Open an Existing Project" to open the new project.
  • After Gradle sync is completed, select "UrhoApp" from the "Edit Run/Debug Configurations" drop down list, and press "Ctrl+F9" to build the UrhoApp.
  • To run the UrhoApp, press "Shift+F10".

Project Structure#

In order to reuse the same build system for Urho3D project to successfully build your own UrhoApp project, the UrhoApp project must be structured similarly to Urho3D project. Assuming you chose to use the rake new to create the UrhoApp project, you will have the following project structure under a new app directory:

UrhoApp
├─ app
│ ├─ build.gradle.kts
│ ├─ CMakeLists.txt
│ ├─ proguard-rules.pro
│ └─ src
│ ├─ cpp
│ │ ├─ UrhoApp.cpp
│ │ └─ UrhoApp.h
│ ├─ java
│ │ └─ io/urho3d/urhoapp
│ │ └─ MainActivity.kt
│ ├─ res
│ | └─ (truncated)
│ └─ AndroidManifest.xml
├─ bin
│ ├─ CoreData
│ │ └─ (as in Urho3D)
│ └─ Data
│ ├─ Materials
│ │ └─ Mushroom.xml
│ ├─ Models
│ │ └─ Mushroom.mdl
│ ├─ Music
│ │ └─ Ninja Gods.ogg
│ └─ Textures
│ ├─ Mushroom.dds
│ ├─ UrhoIcon.icns
│ └─ UrhoIcon.png
├─ build.gradle.kts
├─ cmake
│ └─ (as in Urho3D)
├─ CMakeLists.txt
├─ gradle/wrapper
│ ├─ gradle-wrapper.jar
│ └─ gradle-wrapper.properties
├─ gradle.properties
├─ gradlew
├─ gradlew.bat
├─ rakefile
├─ scripts
│ └─ (as in Urho3D)
├─ settings.gradle.kts
├─ .clang-format
├─ .clang-tidy
├─ .gitattributes
└─ .gitignore

At the root of the project there are a few build scripts which can be grouped as follows:

  • CMake - consist of CMakeLists.txt and all the CMake modules and toolchains in the cmake/ directory.
  • Gradle - consist of build.gradle.kts, settings.gradle.kts, gradle.properties, and the Gradle wrapper scripts.
  • Shell - consist of convenience *nix bash shell script and Windows batch files in the script/ directory.
  • Rake - one rakefile that defines all the common tasks with opinionated default options.

If you are very familiar with CMake then you can directly invoke cmake, ccmake, or cmake-gui to generate a build tree for all the supported platforms, except for Android platform. For the latter case you need to use gradle, or via its wrapper script if you don't have Gradle installed globally. For the most cases though, you will probably find it useful to use the convenience shell scripts or to use them as reference for your own convenience scripts. Finally, the rake command can be used to execute rake tasks for building the project and more.

All the above are for the build system, the actual meat of the UrhoApp project are only residing in the following two directories:

  • app/ - mainly contains the C++ source code in src/cpp/ and Kotlin/Java source code in src/java/.
  • bin/ - contains the assets used by the Urho3D game engine, at the very least it should have CoreData/ and Data/.