xamarin/urho

Code to integrate with the Urho3D engine

UrhoSharp

UrhoSharp is a lightweight Game Engine suitable for using with C# and F# to create games and 3D applications. The game engine is available as a NETStandard 2.0 library, allowing your game code to be written once and shared across all platforms. UrhoSharp is powered by Urho3D, a game engine that has been under development for more than a decade. More information can be found in the UrhoSharp documentation. The bindings for Urho3D are licensed under the MIT license, as found on the LICENSE file.

Key advantages:

• Lightweight - ~10mb per platform including basic assets
• Embeddable - can be embedded into any app as a subview (UIView, NSView, Panel, etc).
• Open-source - C# bindings and the underlying C++ engine Urho3D are licensed under the MIT License
• Powerful 3rd parties - Bullet, Box2D, Recast/Detour, kNet, FreeType
• Advanced graphics using physically based rendering (PBR), Skeletal animation, Inverse Kinematics etc
• Simple code-first approach (however, it still supports native Urho3D editor)

Supported platforms:

• Windows, WPF, WinForms (net45)
• iOS (xamarin.ios10)
• macOS
• Android (monodroid81)
• UWP (uap10.0.16299)
• AR: HoloLens, ARKit, ARCore
• Mixed Reality
• Xamarin.Forms (iOS, Android, UWP)
• Ubuntu

Samples

Sample code lives in https://github.com/xamarin/urho-samples and repository has them as a git submodule. Samples use UrhoSharp via nuget.

Setup

Available on NuGet:

• UrhoSharp - the main package, contains implementations for all platforms including native binaries and basic assets
• UrhoSharp.Tools - contains compiled binaries for AssetImporter and PackageTool for Windows and macOS
• UrhoSharp.WinForms - WinForms control
• UrhoSharp.WPF - WPF control
• UrhoSharp.Cocoa - Cocoa control (macOS)
• UrhoSharp.Forms - Xamarin.Forms support for iOS, Android and UWP
• UrhoSharp.SharpReality - HoloLens and Mixed Reality platforms
• UrhoSharp.HoloLens - deprecated. Was renamed to UrhoSharp.SharpReality

Quick start

To help developers get up and running quickly with UrhoSharp we are providing a solution template for Visual Studio (you can find it in "Online templates" tab). This template consists of PCL+Android+iOS+Mac/Windows with a simple scene and some assets (Xamarin Studio templates will be available soon):

How to build bindings

This is currently a little messy, so YMMV.

In order to compile binaries for all platforms you will need both Windows and OS X environment. Please follow these steps:

Compile UrhoSharp on macOS

You will need:

• XCode
• Visual Studio for Mac
• Homebrew (/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install))
• CMake (brew install cmake)
• Command Line tools (xcode-select --install)
• Android NDK + ANDROID_NDK_HOME environment variable

NOTE: UrhoSharp.csproj and UrhoSharp.Forms.csproj are SDK-style NETStandard2.0 projects with multi-targeting, unfortunately Visual Studio for Mac currently doesn't fully support such projects so you have to compile them using msbuild CLI, e.g. cd Bindings/Forms && msbuild /restore UrhoSharp.Forms.csproj /p:Configuration=Release /p:Platform=AnyCpu

If you have an error message tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance during compilation try to switch developer directory like this sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

1. Clone the repository including submodules

git clone [email protected]:xamarin/urho.git --recursive

2. Compile Urho.pch, SharpieBinder and generate bindigs

The following command will download Clang 3.7.0 if you do not have it installed, and use this to scan the Urho header files, then compile the sources to PCH, parse it via SharpieBinder and generate C# bindings. Additionally there is a perl script to generate bindings to Urho3D events.

make Generated

3. Compile UrhoSharp for Mac (fat dylib)

make Mac

it usually takes 5-10 minutes.

4. Compile UrhoSharp for iOS (fat dylib: i386, x86_64, armv7, arm64)

make iOS SDK_VER=12.1

5. Compile UrhoSharp for Android (armeabi, armeabi-v7a, arm64, x86, x86_64)

make -j5 Android

-j5 means a job per ABI. Make sure you have installed Android SDK and NDK (see MakeAndroid file) This target can also be executed on Windows.

Compile UrhoSharp on Windows

Obviously you can't do it on OS X so you have to switch to Windows environment. Make sure you have installed:

You will need:

• Visual Studio 2017
• CMake 3.10

Open "Command Prompt for Visual Studio" (or regular CMD with msbuild.exe added to the PATH) Go to the project root directory and execute

MakeWindows.bat x64 Release 2017 OpenGL

All compiled binaries could be found in the Bin/{platform} folder. You can also change the parameters, for example the following command:

MakeWindows.bat x86 Debug 2017 DirectX

Compiles debug version of mono-urho.dll with DirectX as a backend.

Compile UrhoSharp on Linux*

Special thanks to @aktowns Prerequisites for Ubuntu 16.06

sudo apt-get install cmake clang-3.7 avr-libc libglew-dev libsdl2-dev libsdl2-image-dev libglm-dev libfreetype6-dev libgl1-mesa-dev libx11-dev

Then just execute:

make Linux

*Tested on Ubuntu 16.06, Fedora 25 and WSL

Updating Documentation

Once you have a build, run the refresh-docs target, like this:

make refresh-docs

This will update the documentation based on the API changes. Then you can use a tool like DocWriter [1] on the Mac to edit the contents, or just edit the ECMA XML documentation by hand with an XML editor.

[1] http://github.com/xamarin/DocWriter

urho's Issues

get_UIElement fails with EntryPointNotFoundException

Steps:

1. Run 02_HelloGUI sample
2. Click on the fish image
   Actual:
   EntryPointNotFoundException for urho_map_get_ptr is thrown

static public UIElement get_UIElement (IntPtr handle, int stringHash)
{
    return new UIElement (urho_map_get_ptr (handle, stringHash));
}```

NavigationMesh.FindPath

15_Navigation (Line 292)

navMesh->FindPath(currentPath_, jackNode_->GetPosition(), endPos_);

Binder needs to bind enumerations

Input.GetTouch and GetJoystickByIndex return unsafe pointer

From 37_UIDrag (Line 206)

TouchState* ts = input->GetTouch(i);

Why is Text.h not being generated?

While we do get four invocations, the "decl.IsCompleteDefinition" is always false

Screenshot

Should RefCounted even be surfaced?

Currently we generate the code for it, but it looks like something that should be an internal implementation detail.

Network.Connect overload with VariantMap for the identity

Currently we do not auto-bind, or surface this API.

Crash: "pointer being freed was not allocated" on UIElement double click

Steps to reproduce:

1. make sure native lib is recompiled as it should contain changes in glue.cpp from #35
2. Run sample 02_HelloGUI
3. Click on any UI button twice (with a small delay).
   Actual:
   On the second click it crashes with the following report:

Exception Type: EXC_CRASH (SIGABRT)
Exception Codes: 0x0000000000000000, 0x0000000000000000

Application Specific Information:
abort() called
*** error for object 0x7f9913965340: pointer being freed was not allocated

TileMap2D.GetInfo(out TileMapInfo2D)

36_Urho2DTileMap (Line 101)

const TileMapInfo2D& info = tileMap->GetInfo();

Skeleton.GetBone(int)

From 13_Ragdolls (Line 109)

Skeleton& skeleton = model->GetSkeleton();
for (unsigned i = 0; i < skeleton.GetNumBones(); ++i)
  skeleton.GetBone(i)->animated_ = false;

eventData not surfaced in the event args

In a handful of cases the eventData is sent with SendEvent, but we do not surface that, in particular it is used by the E_CLIENTIDENTITY message.

ScriptInstance type is missing

From 21_AngelScriptIntegration (Line 112)

ScriptInstance* instance = boxNode->CreateComponent<ScriptInstance>();

Enumeration remapping

Currently we generate the enumeration values as they are surfaced in C, but we need to do enumeration mapping to make those first class .NET names.

struct JoystickState is empty

Defined in Input.h line 73

Unsubscribing from events currently unsuscribes all events

All events of a given type, because Urho does not have an API to remove just the susbscribed event/handler pair.

Find a way of mapping "events" to C# events and EventArgs.

UIElement.GetVar/SetVar (same for Node)

Some samples use it for storing some info (usually it's String or Vector type).
We can avoid using them in samples. But we can also marshal them at least with String argument.

OpenConsoleWindow() and GetConsoleInput()

global methods definin in ProcessUtils.h

From sample 26_ConsoleInput (Line 112)

String input = GetConsoleInput();

Octree.RaycastSingle

In sample 08_Decals (Line 294):

PODVector<RayQueryResult> results;
RayOctreeQuery query(results, cameraRay, RAY_TRIANGLE, maxDistance, DRAWABLE_GEOMETRY);
scene_->GetComponent<Octree>()->RaycastSingle(query);

Documentation: make the CxxBinder collect the documentation from the header files and produce C# inline docs.

Bind command line argument parser/update of EngineParameters

Used by the sample, but also by a sample player.

Terrain.GetNormal leads to crash in Sample 23_Water

Line 140:

objectNode.Rotation = Quaternion.FromRotationTo(new Vector3(0.0f, 1.0f, 0.0f), terrain.GetNormal(position));

Support for "Variant" in public API (ValueAnimation.SetKeyFrame)

From 30_LightAnimation (Line 127)

SharedPtr<ValueAnimation> colorAnimation(new ValueAnimation(context_));
colorAnimation->SetKeyFrame(0.0f, Color::WHITE);

Async support

Add async support for user code.

For this to work, we need to have a "context" attached to each operation where we want to support async. In my mind, those are Update and SceneUpdate, but there might be others.

So what we would need to do is, when we first subscribe to one of those events, we need to create a SynchronizationContext for them (UpdateContext and SceneUpdateContext), and we need to make sure that when an event is "dispatched" for Update or SceneUpdate, that we save the current context, then set this as the default context for the duration of the event, and we reset it afterwards [1].

Then, we would need to make our synchronization context basically track any queued tasks, and execute any complete tasks on the update/sceneupdate event.

Ideas

Perhaps to make this work, we could provide a default SceneUpdate/Update event handlers in Application, and we encourage developers to not subscribe manually with SubscribeToSceneUpdate, but instead to set an event handler, something like:

Application.SceneUpdate += MySceneUpdate

That would centralize all of the SceneUpdates, instead of having hundreds of independent SceneUpdates everywhere.

Notes

[1] Potential problem: if a game uses a lot of subscriptions to events, say to 100 events, we do not want to have to push/pop the synchronization context 100 times. So we probably want to proxy all scene update notifications into one big group and dispatch them all at once.

Connection.SendRemoteEvent

From 17_SceneReplication (Line 482)

newConnection->SendRemoteEvent(E_CLIENTOBJECTID, true, remoteEventData);

Binding Optimization: APIs that require no marshaling

APIs that require no marshaling should be surfaced directly by the P/Invoke, without the extra layer method

Figure out a way of annotating methods that must become properties

Currently we map all methods as methods, but some of those should be properties.

BillboardSet_GetBillboard: Cannot marshal 'return value': Pointers cannot reference marshaled structures.

https://github.com/xamarin/urho/blob/fe6e046dcdba3bcf17b5e3759f828c52731bc663/bindings/src/BillboardSet.cs it doesn't want to marshal return struct. I investigated it and found out that boolean fields (in Rect and the Enabled) cause that. Because the bool type is not blittable (http://msdn.microsoft.com/en-us/library/75dwhxf7.aspx).
So I see two workarounds: replace bool with byte type (in both Billboard and Rect structures) or rewrite the method somehow to not to return a reference to a struct (field accessors?).

Plane is missing

As it turned out,Vector4 and Plane are different types. And the second one is missing.
These methods too:
Camera::SetReflectionPlane(Plane)
Camera::SetClipPlane(Plane)

From 23_Water sample

// Create a mathematical plane to represent the water in calculations
waterPlane_ = Plane(waterNode_->GetWorldRotation() * Vector3(0.0f, 1.0f, 0.0f), waterNode_->GetWorldPosition());
// Create a downward biased plane for reflection view clipping. Biasing is necessary to avoid too aggressive clipping
waterClipPlane_ = Plane(waterNode_->GetWorldRotation() * Vector3(0.0f, 1.0f, 0.0f), waterNode_->GetWorldPosition() -
    Vector3(0.0f, 0.1f, 0.0f));

// Create camera for water reflection
// It will have the same farclip and position as the main viewport camera, but uses a reflection plane to modify
// its position when rendering
reflectionCameraNode_ = cameraNode_->CreateChild();
Camera* reflectionCamera = reflectionCameraNode_->CreateComponent<Camera>();
reflectionCamera->SetFarClip(750.0);
reflectionCamera->SetViewMask(0x7fffffff); // Hide objects with only bit 31 in the viewmask (the water plane)
reflectionCamera->SetAutoAspectRatio(false);
reflectionCamera->SetUseReflection(true);
reflectionCamera->SetReflectionPlane(waterPlane_);
reflectionCamera->SetUseClipping(true); // Enable clipping of geometry behind water plane
reflectionCamera->SetClipPlane(waterClipPlane_);

Need to run Application "onMainThread" events on every update (as long as items are available)

boolean return type should be marked with [return: MarshalAs(UnmanagedType.I1)] everywhere

e.g.

[DllImport ("mono-urho", CallingConvention = CallingConvention.Cdecl)]
[return: MarshalAs(UnmanagedType.I1)]
internal static extern bool Input_GetMouseButtonPress (IntPtr handle, int button);

without it can return true when should return false (and it does it for _11_Physics sample)
see http://stackoverflow.com/a/4621621

Unsubscribers from events

There are lots of typed subscribers defined in UrhoObject\Object.Events such as:

SubscribeToUpdate
SubscribeToPostRenderUpdate
SubscribeToNetworkMessage

But there is no mechanism to unsubscribe from those events. Original samples use the following code:

UnsubscribeFromEvent(E_SCENEUPDATE);

where E_SCENEUPDATE is a StringHash

Support for "EngineParameters"

The engine parameters are the mechanism by which the engine is configured at startup, we need to bind and surface these parameters to managed code.

Application::Setup allows the engine to be tuned here:

// Modify engine startup parameters
engineParameters_["WindowTitle"] = GetTypeName();
engineParameters_["LogName"]     = GetSubsystem<FileSystem>()->GetAppPreferencesDir("urho3d", "logs") + GetTypeName() + ".log";
engineParameters_["FullScreen"]  = false;
engineParameters_["Headless"]    = false;

Add support for constructors

Write struct size validator

As we plan to hand bind the structures to match the ABI of urho, it makes sense to have a struct size and offset validator to ensure that changes to urho do not break the interop by accident

Missing PixelSize constant definition

Example usage from 24_Urho2DSprite (Line 98):

 float halfWidth = graphics->GetWidth() * 0.5f * PIXEL_SIZE;

Scene.SaveXml/LoadXml

From 32_Urho2DConstraints (Line 496)

scene_->SaveXML(saveFile);

Controls type is missing

From 19_VehicleDemo

RenderPath.SetShaderParameter

From 09_MultipleViewports (line 206):

effectRenderPath->SetShaderParameter(""BloomMix"", Vector2(0.9f, 0.6f));

CodeGenerator doesn't respect C++'s enums' values.

BodyType2D in C# (generated):

public enum BodyType2D
{
    BT_STATIC,
    BT_DYNAMIC, //means 1
    BT_KINEMATIC
}

in C++:

enum BodyType2D
{
    BT_STATIC = b2_staticBody,
    BT_DYNAMIC = b2_dynamicBody, //its value is actually 2
    BT_KINEMATIC = b2_kinematicBody,
};

BufferedSoundStream.AddData should accept byte[] instead of IntPtr

From 29_SoundSynthesis

soundStream_.AddData(newData, numSamples * sizeof(signed short));

where newData is a short[]

Need to retain managed objects

When an instance of a managed object is passed down, we need a wait to retain it.

So effectively, implementing toggle refs

Node.RemoveComponent<> (generic)

from 32_Urho2DConstraints (Line 538):

pickedNode->RemoveComponent<ConstraintMouse2D>();

Network.GetClientConnections()

From 17_SceneReplication (Line 482):

newConnection->SendRemoteEvent(E_CLIENTOBJECTID, true, remoteEventData);

ConstraintGear2D: AccessViolationException when trying to add it to the node

32_Urho2DConstraints C# (Line 344)
someNode.CreateComponent()
or
someNode.AddComponent(new ConstraintGear2D(Context));

throw AccessViolationException

Hate the Urho Enumerations

The enumerations are not very useful.

One optin is to make the enumeration values just constants that we can reference from an actual enumeration, like this:

enum MyCuteEnumeration {
Foo = UrhoEnums.ENUM_FOO_VALUE
}

So we could get the right value, and just prettify without having to manually deal with all the cases and casing that will berequired.

CxxBinder doesn't change string to SoundType for SoundSource and Audio

Audio.GetMasterGain(string) => Audio.GetMasterGain(SoundType)
SoundSource.SetSoundType(string) => SoundSource.SetSoundType(SoundType)

it's still string despite of my changes to CxxBinder: c4121a2

RenderPath.Clone

Sample: 09_MultipleViewports (line 202)

 SharedPtr<RenderPath> effectRenderPath = viewport->GetRenderPath()->Clone();

The challenge with this binding is that the Clone() return a SharedPtr, so we would need to surface the internal version of this object. Not difficult, but the side effects need to be understood.

Model.Clone()

From 34_DynamicGeometry (Line 155):

SharedPtr<Model> cloneModel = originalModel->Clone();