What's this documentation?

This documentation helps you out with setting up UrsinaForMobile. The doc itself won't be anymore with the main repository. It is hosted in this repo.

So, if you want to change UfM itself, do pull requests on the main repo. If you want to change the documentation, change the docs repo.

About the docs

The docs are officially hosted on Github Pages, on this url.

Getting started

Welcome to the documentation !!! Here, we'll see basic concepts, like how do we setup UfM, to neat concepts.

Cloning the repository

Well, I guess you know how to clone a github repo...

But if you don't know, follow these steps: First, make sure you have git installed. Then, enter this command in your terminal:

git clone https://github.com/PaologGithub/UrsinaForMobile

Python dependencies

First, make sure you have CPython 3.13 installed on your computer. You cannot use other version of python, only 3.13 is supported for now. Make sure too that you use python 3.13 while building, and not any other installed version. To be sure which version you use, use python3.13 and not python3 in the commands.

Protobuf installation

Then, install protobuf. I don't remember why we need version 3.20.0, but as I remember, that's the latest supported version. To install protobuf, use this command:

python3.13 -m pip install protobuf===3.20.0

Panda3D installation

To build Ursina For Mobile binaries, you need to build Panda3D on Android. WARNING: TO BUILD PANDA3D FOR ANDROID, YOU CANNOT, ON YOUR PC, USE A STABLE WHEEL OF PANDA3D. So, it's required to use a beta wheel.

There are multiple wheel for multiple os, here are some:

Windows (64 bit):

python3.13 -m pip install https://buildbot.panda3d.org/downloads/b32d5c672441c280f7e799483d223e252cf9f797/panda3d-1.11.0.dev3788-cp313-cp313-win_amd64.whl

Linux (64 bit):

python3.13 -m pip install https://buildbot.panda3d.org/downloads/b32d5c672441c280f7e799483d223e252cf9f797/panda3d-1.11.0.dev3788-cp313-cp313-manylinux2014_x86_64.whl

MacOS (Universal (Intel and Apple Silicon)(Not recommended)):

python3.13 -m pip install https://buildbot.panda3d.org/downloads/b32d5c672441c280f7e799483d223e252cf9f797/panda3d-1.11.0.dev3788-cp313-cp313-macosx_11_0_universal2.whl

MacOS (Intel - 64 bit):

python3.13 -m pip install https://buildbot.panda3d.org/downloads/b32d5c672441c280f7e799483d223e252cf9f797/panda3d-1.11.0.dev3788-cp313-cp313-macosx_10_13_x86_64.whl

You can grab other wheel from the buildbot. Make sure you use wheels that have:

panda3d-1.11.0.devXXXX version in the wheel
cp313 python version of the wheel

Understanding the structure

This is the structure of a default UfM game:

/
|- assets/
|  |- game_assets/
|  |  |- ...
|  |- ursina_assets/
|  |  |- ...
|  |- logo.png
|
|- project/
|  |- builder/
|  |  |- ... [.py]
|  |- wheels/
|  |  |- ... [.whl]
|  |- settings.toml
|
|- src/
|  |- ... [.py]
|- ...
|- setup.py

In this section, I will go through each directory, explaining what they do, and what to do in them.

[!WARNING] This chapter is, I think, one of the most important one. It'll learn you how to create your basic game, etc etc. Please read it carefully, entirely.

`Assets` folder

The assets folder contains two subfolders:

game_assets: The folder you'll modify to include your own assets. Put your assets here, and use them with ursina.application.asset_folder.
ursina_assets: The folder that contains ursina base assets. Normally, you won't modify this folder. Access it with ursina.application.package_folder

`Project` folder

This folder is not a thing you'll modify much; you'll principally modify it when you set up your game, but then, you normally won't need to modify it much. There is these subfolders:

builder: You won't normally edit this folder; it's just some modules that'll get run. Maybe you'll modify it to change how your app get built.
wheels: This folder includes basic python wheels, like Panda3D and Ursina. If you need to include wheels, put them in this folder.
settings.toml: This is the most important file in the folder. This is where you set up your game, and we'll learn now how to use this file:

Using `project/settings.toml`

This is the default settings.toml:

[android]
# Identifier used by android
id          = "your.company.app.name"
# Version of your game
version     = "0.0.0"
# Name displayed in the settings page (not the launcher)
name        = "My ursina game"
# Icon of the application
icon        = "assets/logo.png"
# Classifiers of the application
classifiers = ["Topic :: Games/Entertainment"]

[application]
# Name displayed on the launcher
# Can now have spaces in it
# Uh no in reality
name        = "MyUrsinaGame"
# Main python file of the game
startfile   = "src/__main__.py"

[build]
# Android version code. NOT EQUAL to android.version, used by Google Play Store
# Each time you update your app on the Play Store, you should increment this by one.
vercode     = 0
# Platforms supported by your app
platforms   = ["android"]
# What file to includes
includes    = [
    "assets/game_assets/**",    # Game assets
    "assets/ursina_assets/**",  # Ursina assets, don't remove this.
    "assets/assets.gen",        # Generated list of assets
    "**/*.png",
    "**/*.jpg",
    "**/*.egg",
]

[assets]
# Ursina assets dir
ursina_dir  = "assets/ursina_assets"
# Game assets dir
game_dir    = "assets/game_assets"

I guess the comments are already straightforward, so I won't really go through it, but this is the file you'll need to modify first to make your game your game.

`Src` folder

This folder includes your application, with 2 main files:

__main__.py: The main application (can be redefined in project/settings.toml)

[!WARNING] When modifying the main file, make sure to include these two lines at the beginning:
from setup_ursina_android import setup_ursina_android
setup_ursina_android()

setup_ursina_android.py: This file is here to set up ursina for android, and help you out. Modify it only if you know what you're doing.

Android building dependencies

To run your app, you need to have a working device/emulator with USB debugging. Then, you need to install ADB, Java Development Kit, and BundleTool.

Building your game

This chapter will learn you how to build your game.

You'll see how to compile your app, sign it, build apks/apk.

Creating the aab

AAB is a special type of package. The acronym is for 'Android App Bundle', and is used to publish your app on the Google Play Store.

However, this is not easy to directly install an AAB to a device. Second however, Panda3D build your app as an AAB bundle, not an APK one.

To create the aab, this is pretty straightforward; you just need to use setup.py script, like this:

python3.13 setup.py bdist_apps

However, this method can only be used for development use. To release your app, you'll need to build the AAB with a certificate, which you'll learn in the next page.

Creating the AAB with a certificate

This is a sub-part of the 2.1 step. So, I assume that you read the 2.1 step before this one.

First, you need to create a certificate. To do that, you need OpenSSL (I didn't put OpenSSL as dependency, but you'll need to install it if you want to use certificates.)

To create the certificate, do this:

openssl genpkey -algorithm RSA -aes256 -out private.pem
openssl req -new -x509 -sha256 -days 365 -key private.pem > cert.pem

Then, you need to modify setup.py like this:

from setuptools import setup

# ...

setup(
    # ...
    options={
        'build_apps': {
            # ...
        },
        'bdist_apps': {
            'signing_certificate': 'cert.pem',
            'signing_private_key': 'private.pem',
            # optional: Panda will otherwise ask passphrase on command-line
            #'signing_passphrase': 'panda3d_is_cool',
        },
    },
    # ...
)

WARNING: Putting your signing_passphrase on a public repo is really bad. If you need to do that, you can use a .env environnment. Because setup.py is a python file, you can use python-dotenv in it.

And, to build your application, use this command:

python setup.py bdist_apps

Converting your AAB to APKs

An APKs file is a .zip-like file that contains one .apk for each processor architecture. This type of file is required for C++ application, because compiling for C++ gives you one binary that only works for one processor architecture. So, because Panda3D is written in C++, we need to have this kind of file.

To convert an AAB to APKs, you need to use Java and BundleTool (check requirements step to see where to install.)

Then, use this command:

java -jar Path/To/BundleTool.jar --bundle ./dist/*.aab --output ./dist/app.apks

However, you can build you app to a single APK. WARNING: I don't know why, but some people got assets error (not loading or buggy pngs) while using this. This is not recommended. To do this, you can use the --universal flag

java -jar Path/To/BundleTool.jar --bundle ./dist/*.aab --output ./dist/app.apk --universal

Installing your game

This part will show you how you can install your game on your local device.

Installing the APKs

You may be tempted to install your game on your device (I dunno why did I put 'tempted', but maybe you'll want to play your game... maybe...)

To install your game, ensure you have one device connected to ADB (check with adb devices). WARNING: You need to have only one device connected to ADB, or else BundleTool will throw you an error.

To install your apks, use this command:

java -jar Path/To/BundleTool.jar install-apks --apks=./dist/*.apks

You may be tempted/need to use other method, which will we talk in the next step.

Other methods of installation

This step isn't required. This is if, for example, BundleTool doesn't work, or that you used the AAB -> Universal APK.

When AAB -> Universal APK used

This method gave you a .apk file, that you can just open in Android, or use adb install Path/To/Apk.apk to install from the computer.

Other ways for APKs

You can use, in Android, for example, File Manager + (On F-Droid and Google Play Store), which provide support for .apks (simply clicking on it will install the app). It doesn't seem that the Native File Explorer support .apks, so it is a File Manager + functionnality.

Your Game

The chapters before made you create an UfM repository, build and install the produced application.

This chapter is about making your own game; with this chapter, you'll learn how to include assets, modify the code, logging, and some other things.

Everything in this chapter is required; in this chapter, you can see which sub-chapter is interesting / you need, and just go to them. It is good, for your understanding of this project, to read every part; but it isn't required.

Ursina For Mobile - Docs