upbge / upbge-docs

UPBGE Manual

UPBGE Manual

View the latest build of this documentation

Welcome to the official repository of UPBGE's Manual and Python API, the UPBGE source-code repository can be found here.

You can contribute by opening an issue asking for a topic to be included in the documentation and/or opening a pull-request with the desired changes. If you'd rather contribute several things directly ask for commit rights.

Once a change is committed, a build is automatically generated and the new changes pushed to the upbge-docs repository directly.

Local Build Requirements

To build this documentation you'll need:

• Python 3
• Sphinx
• Read The Docs Theme for Sphinx

Once all dependencies are installed, simply open the console at the top-level directory and run the command:

make html

The documentation will than be built into the build directory.

License

UPBGE itself is released under the GNU General Public License.

Except where otherwise noted, the content of the UPBGE Manual is available under a Creative Commons Attribution-ShareAlike 4.0 International License or any later version. Excluded from the CC-BY-SA are also the used logos, trademarks, icons, source code and Python scripts.

This UPBGE manual contains exclusive information from UPBGE Documentation Team, but it's also based on others manuals and articles whose authors are exposed below:

• The Blender Manual by the Blender Documentation Team which is licensed under a CC-BY-SA v4.0.

• The "Game Development with Blender" book by Mike Pan, Dalai Felinto and Other Authors which is licensed under a CC-BY-SA v4.0.

• The UPBGE Manual by the UPBGE Documentation Team which is licensed under a CC-BY-SA v4.0.

This means that when someone contributes to the manual, they don't hold exclusive copyright to their text. They are of course, acknowledged and appreciated for their contribution. However, others' can change and improve any or all text in order to keep the manual consistent and up to date.

If you want to use the UPBGE manual in other sites or other formats, please attribute the different authors and include hyperlinks (online) or URLs (in print) to the different manuals that are pointed out above.

UPBGE Documentation Team

• Antônio Froz (uayten)
• Denis Nicolas (denicolas)
• Guilherme Teres Nunes (UnidayStudio)
• Joel Gomes da Silva (joelgomes1994)
• Jorge Bernal (lordloki)
• Leopold A-C (IzaZed)
• marechal-p (wkk)
• NaincyKumariKnoldus
• RPaladin
• ShaunKulesa
• Tristan Porteries (panzergame)
• Ulysse Martin (youle31)
• Xavier Cho (mysticfall)
• (aum7)
• You!

upbge-docs's Issues

Scenes aren't used anymore

Trying to create my first HUD in UPBGE 0.3 alpha, a bit confused. Most people seemed to use addScene() previously. Now I finally found why that doesn't work:

UPBGE/upbge#1167

So for instance this should probably be updated:
https://upbge-docs.readthedocs.io/en/latest/api/bge.logic.html?highlight=addscene#bge.logic.addScene

Building step

Is this necessary now that its all automated?

Requirements
To build this documentation, it's required:

Python 3
Sphinx
Read The Docs Theme for Sphinx
Once every dependency is instaled, simply open the console on the top level directory and run the command:

make html

The documentation will be built in the directory build.

UPBGE Manual » Logic Bricks » Actuators » Mouse Actuator: many corrections

UPBGE Manual » Logic Bricks » Actuators » Mouse Actuator
https://upbge.org/manual/manual/logic/actuators/types/mouse.html

The following sentence belongs to "Motion Actuator":
"Servo control is a powerful way to achieve motion in way which mimics the movement of objects in the physical world. It consists in a servo controller that adjusts the force on the object in order to achieve a given speed."

In the rest of the document, each parameter description, from "Use X axis, Y axis" to "Object axis X, Y, Z", actually belongs to "Motion Actuator". For example, the description of "Use X axis, Y axis" is actually the description of "Reference Object" in section "Servo Control" of "Motion Actuator"...

UPBGE Manual » Logic Bricks » Actuators » Edit Object Actuator: undocumented feature

UPBGE Manual » Logic Bricks » Actuators » Edit Object Actuator
https://upbge.org/manual/manual/logic/actuators/types/edit_object.html

In section "Track To", "Up Axis" and "Track Axis" are undocumented...

The sentence "The Y axis is considered the front of the object." should be removed.
Documentation could be something like:
"
Up Axis
Selects the axis that should point up.

Track Axis
Selects the axis that should point to the target object.
"

Readme change

@lordloki what's your opinion on this?

## Requirements
Building is automatically done when you edit a file. To edit either create a pull request or ask for edit permission.

OR

To build this documentation on your own system, you will be required to have these dependencies installed:
- [Python 3](https://www.python.org/)
- [Sphinx](https://pypi.org/project/Sphinx/)
- [Read The Docs Theme for Sphinx](https://pypi.org/project/sphinx_rtd_theme/)

Once every dependency is installed, simply open the console on the top level directory and run the command:

`make html`

The documentation will be built in the directory **build**.

UPBGE Manual - Logic Bricks - Sensors - Movement Sensor not included

https://upbge.org/manual/manual/logic/sensors/index.html

The Movement Sensor is not included in the manual.

There is a page describing it in the upbge API: https://upbge.org/api/bpy.types.MovementSensor.html?highlight=movement%20sensor

UPBGE Manual » Logic Bricks » Actuators » Constraints Actuator: correction

UPBGE Manual » Logic Bricks » Actuators » Constraints Actuator
https://upbge.org/manual/manual/logic/actuators/types/constraint.html

In section "Distance Constraint":
"Persistence button: When on, force field constraint always looks at Property/Material; when off, turns itself off if it cannot find the Property/Material."
should be:
"Persistence button: when on, Distance Constraint always looks for Property/Material; when off, turns itself off if it cannot find the Property/Material."

UPBGE Manual » Logic Bricks » Actuators » Motion Actuator: update

UPBGE Manual » Logic Bricks » Actuators » Motion Actuator
https://upbge.org/manual/manual/logic/actuators/types/motion.html

In section "Servo Control", since "Servo Type" has been added (with 2 choices, "Linear" and "Angular"), this sentence is no longer correct:
"Only the positional velocity is influenced by this actuator; it does not control rotation at all, and it controls position only indirectly."
It should be replaced with something like:
"This actuator controls position or rotation only indirectly."

Documentation structure proposal

Hello! Here I show my proposal on the documentation structure, I'm already working at it, but I'm publishing it to enable a discussion if it's really a good planning, or can be enhanced.

The latest development build of this manual can be viewed here.

UPBGE Directed Manual

First, the documentation is a merge of Blender manual (Game Engine section only) and UPBGE's Python API (UPBGE and Standalone modules only).

The manual will only contain UPBGE's specific features or, at most, game dev specific tasks, and any generic definition will have a link to the related subject on the Blender official manual. For example, the manual may explain the game specific definitions on materials, but for general materials settings the manual will provide a link to Blender official manual, on the Materials section.

From now on, I will refer only to Blender manual pages inside Game Engine section.

Rework of Manual Tree Structure

The document's structure on official Blender manual is somewhat messy, with no contexts or sub themes, along with some pages that don't belong in there. My proposal is to make a context based manual:

MANUAL

• Introduction - This chapter is totally adapted to UPBGE 0.3
  • Briefing
  • A Deeper Look
  • Compatibility Notes
• Tutorials
  • Getting Started
    • 3D Basic Concepts
    • Game Basic Concepts
    • Blender/UPBGE Basics
  • Introducing Logic Bricks
    • Moving A Cube
    • First person camera
    • Playing An Animation
    • Using Linked Libraries In Game
  • Introducing Logic Nodes - This chapter is totally adapted to UPBGE 0.3
    • A First Example
  • Introducing Python Scripting
    • Basic Concepts
    • Moving A Cube
    • Playing An Animation
    • Dealing With Group Instances
  • Introducing Python Components
    • Setting Up A Python Component
• Editors
  • Properties Editor
    • Render
    • Scene
    • World
    • Object
    • Constraints
    • Texture
    • Physics
    • Materials
    • Data
  • Logic Bricks Editor
    • Logic Bricks Area
    • Properties Panel
    • Components Panel
  • Logic Nodes Editor
    • Properties Panel
    • Logic Nodes Area
  • Python Editor
    • Properties Panel
    • Python Area
• Logic Bricks - This chapter is totally adapted to UPBGE 0.3
  • Introduction
  • Sensors
  • Controllers
  • Actuators
  • Properties
  • States
• Logic Nodes
  • Getting Started
    • Creating A Basic Logic Tree
    • Creating A Character
  • Node types
    • Condition Nodes
    • Parameter Nodes
    • Action Nodes
• Python Scripting
  • Introduction
  • Python And The Game Engine
  • Understanding Inheritance And Composition In Game Scripting
• Python Components - This chapter is totally adapted to UPBGE 0.3
  • Introduction
  • Getting Started
    • Character Controller Templates
    • Top Down Templates
    • Vehicle Templates
    • Util Templates
• Physics
  • Introduction
  • World Settings
  • Object Settings
    • No collision
    • Static
    • Dynamic
    • Rigid body
    • Soft body
    • Character
    • Navigation
    • Common Settings
  • Material Settings
  • Constraints
  • Sensors
  • Vehicle Physics
  • Other Tips
• Release Game
  • Licensing of Games
  • Performance Considerations
  • Standalone Player
  • Release Procedure
• Tools
  • API Stubs
• About This Manual - This chapter is totally adapted to UPBGE 0.3
  • Introduction to the UPBGE Manual
    • Conventions
    • Contribute
  • Manual License and Credits
  • What's New

Note that some important topics aren't listed on the proposal (like Camera, World, Physics), it is because those topics will be part of Editors > Properties Editor, according to its subject (Camera in Data tab, World in World tab, and so on). Also, I thought about moving the Logic top section to Editors > Logic Editor's subsection, but it will depend on the upcoming logic nodes (Node Editor will be added to Editors).

I'll be waiting for enhancement comments on this proposal, thanks. 😄

UPBGE Manual » Logic Bricks » Actuators » Armature Actuator: swapped words

UPBGE Manual » Logic Bricks » Actuators » Armature Actuator
https://upbge.org/manual/manual/logic/actuators/types/armature.html

"The Armature Actuator only is available for armature objects."
should be:
"The Armature Actuator is only available for armature objects."

Document import sheningans happing with in-editor Python files

Blender/UPBGE overrides the import function in Python to first look into the datablocks to find some Python module file.

As it can be confusing, an entry in the documentation should make it clear.

See: UPBGE/upbge#1011 (comment) (comment)

Issue moved from UPBGE/upbge

UPBGE Manual » Logic Bricks » Actuators » Steering Actuator: corrections

UPBGE Manual » Logic Bricks » Actuators » Steering Actuator
https://upbge.org/manual/manual/logic/actuators/types/steering.html

• "Lock Z velocity" is undocumented (tooltip says "Disable simulation of linear motion along Z axis.").
• "Visualize": maybe it should be specified that it's only for "Path following" behavior.
• "Visualize": the sentence "It is also necessary to enable Debug Properties in the Display menu of the Render tab." should be removed.

Manual Translation

I want to translate the UPBGE user manual. How to do that?

Broken URL in the UPBGE manual

I would love to get my hands on to this file called "Manual-BGE-Physics-DancingSticks.blend" mentioned on this page: https://upbge.org/#/documentation/docs/latest/manual/manual/physics/introduction.html

However the link redirects to the Blender Wiki which shows "No file by this name exists."

Is there a way to find this this file in any repository or online somewhere?

UPBGE Manual » Logic Bricks » Actuators » Game Actuator: undocumented feature

UPBGE Manual » Logic Bricks » Actuators » Game Actuator
https://upbge.org/manual/manual/logic/actuators/types/game.html

"Screenshot" is undocumented.
Documentation could be something like:
'
Screenshot
Save a screenshot to the specified file.
File
Path to the screenshot to save (".png" is appended to the filename).
'

UPBGE Manual » Logic Bricks » Actuators » Armature Actuator: correction

UPBGE Manual » Logic Bricks » Actuators » Armature Actuator
https://upbge.org/manual/manual/logic/actuators/types/armature.html

"Used to change the Influence of a constraint by selecting a new weight with the Influence field"
should be:
"Used to change the influence of a constraint by selecting a new influence with the Influence field"

Missing Video Texture demo's

Hi,

These are listed art the bottom of https://github.com/UPBGE/UPBGE-Docs/blob/master/drafts/videotexture.rst

They are not on the main official documentation page for Video Textures.

It would be nice to have a demo Blender file. I can't file the one's listed anywhere.

Cheers

UPBGE Manual » Logic Bricks » Actuators » Motion Actuator: corrections

UPBGE Manual » Logic Bricks » Actuators » Motion Actuator
https://upbge.org/manual/manual/logic/actuators/types/motion.html

The sentence:
"There are two modes of operation, Simple or Servo,"
should be:
"There are three modes of operation, Simple, Servo and Character,"

---

For "Angular Velocity", the sentence:
"The target linear velocity for the object."
should be:
"The target angular velocity for the object."

---

In section "Character Motion", for "Jump", the sentence:
"The character performs the jump previously configured."
could be:
"Make the character jump using the settings in the physics properties (Jump Force and Max Jumps)."

UPBGE Manual » Logic Bricks » Actuators » Action Actuator: correction

UPBGE Manual » Logic Bricks » Actuators » Action Actuator
https://upbge.org/manual/manual/logic/actuators/types/action.html

"It is only visible when an armature is selected, because the actions are stored in the armature."
is wrong, as the Action Actuator is visible when the default cube is selected, for example.

UPBGE Manual - Logic Bricks - Actuators - Action Actuator: omissions

https://upbge.org/manual/manual/logic/actuators/types/action.html#/documentation/docs/latest/manual/manual/logic/actuators/types/action.html

The functions 'Force', 'Add' and 'L' are not explained. They are not present in the bge manual page either, but are described in Mike Pan's book: http://mikepan.com/GameEngineBook/text/03-LogicBricks.html#Action

Also, the functions 'Blend' or 'Add' in 'Blend Mode', are not explained.

UPBGE Manual » Python Scripting » Introduction to Scripting: corrections

UPBGE Manual » Python Scripting » Introduction to Scripting
https://upbge.org/manual/manual/python/introduction.html

Code snippet:
for i in range(10): exec("var\_%d = %d" % (i,i))

• should be indented.
• '_' shouldn't be escaped ("SyntaxError: invalid escape sequence").

Corrected snippet:

for i in range(10):
    exec("var_%d = %d" % (i,i))

---

Right after that:
"
This snip of code is the equivalent to the following:

var_1 = 1

var_2 = 3

var_3 = 3

(...)

"
should be:
"
This snip of code is the equivalent to the following:

var_0 = 0

var_1 = 1

var_2 = 2

(...)

"

UPBGE Manual » Logic Bricks » Actuators » Constraints Actuator: correction

UPBGE Manual » Logic Bricks » Actuators » Constraints Actuator
https://upbge.org/manual/manual/logic/actuators/types/constraint.html

In section "Distance Constraint":
"Property/Material that triggers the Force Field constraint (blank for all Properties/Materials)."
should be:
"Property/Material that triggers the Distance Constraint (blank for all Properties/Materials)."

UPBGE Manual » Logic Bricks » Actuators » Sound Actuator: correction

UPBGE Manual » Logic Bricks » Actuators » Sound Actuator
https://upbge.org/manual/manual/logic/actuators/types/sound.html

For "Play End", the sentence:
"The sound is not replayed if activated while still playing."
should be:
"The sound is replayed if activated while still playing."

UPBGE Manual » Logic Bricks » Actuators » Filter 2D Actuator: correction

UPBGE Manual » Logic Bricks » Actuators » Filter 2D Actuator
https://upbge.org/manual/manual/logic/actuators/types/filter_2d.html

Caption of first screenshot:
"Edit Object actuator."
should be:
"Filter 2D actuator."

UPBGE Manual » Python Scripting » Python and the Game Engine: corrections

UPBGE Manual » Python Scripting » Python and the Game Engine
https://upbge.org/manual/manual/python/python_game_engine.html

In section "Integrating Python in the Game Engine", script "abracadabra.py":

    sens = cont.sensors['my\_sensor']
    act = cont.actuators['my\_actuator']

should be:

    sens = cont.sensors['my_sensor']
    act = cont.actuators['my_actuator']

---

"AttributeError: 'KX_FontObject' object has no attribute 'text'"
This line:

    text_obj.text = "CADABRA"

should be:

    text_obj["Text"] = "CADABRA"

And this other line:

    text_obj.text = "ABRA"

should be:

    text_obj["Text"] = "ABRA"

UPBGE Manual » Logic Bricks » Actuators » Action Actuator: correction

UPBGE Manual » Logic Bricks » Actuators » Action Actuator
https://upbge.org/manual/manual/logic/actuators/types/action.html

"Loop End
Play F-Curve continuously from end to start when a TRUE pulse is received."
should be:
"Loop End
Play F-Curve continuously from start to end when a TRUE pulse is received."

---

"Loop Start
Play F-Curve continuously from start to end when a TRUE pulse is received."
should be:
"Loop Stop
Play F-Curve continuously from start to end when a TRUE pulse is received. Stop when a FALSE pulse is received."

UPBGE Manual » Logic Bricks » Controllers » Controller Editing: tiny correction

Not sure this is the right way to go about such a tiny correction... Please let me know.
Here it is:
UPBGE Manual » Logic Bricks » Controllers » Controller Editing
https://upbge.org/manual/manual/logic/controllers/editing.html
"X Button
Deletes the sensor."
should be:
"X Button
Deletes the controller."

Furo theme and MKDocs

Blender Manual now use now a new "furo" Sphinx theme:
https://docs.blender.org/manual/en/latest/

"Furo" Sphinx theme:
https://github.com/pradyunsg/furo

Blender Developer Docs now use MKdocs
https://developer.blender.org/docs/handbook/building_blender/

as explained in the Blender Developer Blog here:
https://code.blender.org/2023/12/a-new-developer-documentation-platform/

• So could be used the "Furo" Sphinx theme for UPGE docs ?
• As alternative could be considered to use the MKDocs for UPGE docs ?

I personally prefer Markdown based docs like mdBook ( Rust ) or MKdocs ( Python )
But for consistence with Blender probably better to stick with Sphinx reStructuredTex.

thank you

I don't want anything to do with UPBGE or contributions to it, you can keep my words and photos but I just don't want my name on the front.

UPBGE Manual » Logic Bricks » Actuators » Edit Object Actuator: undocumented feature

UPBGE Manual » Logic Bricks » Actuators » Edit Object Actuator
https://upbge.org/manual/manual/logic/actuators/types/edit_object.html

In section "Dynamics", "Suspend Physics" and "Restore Physics" are undocumented...

Documentation could be something like:
"
Suspend Physics
Suspends the object physics (disables object velocity and collision).

Restore Physics
Resumes the object physics (enables object velocity and collision).
"

UPBGE Manual » Python Scripting » Introduction to Scripting: correction

UPBGE Manual » Python Scripting » Introduction to Scripting
https://upbge.org/manual/manual/python/introduction.html

In section "Flexible Data Types":
'
The following code snip assigns the scene objects (retrieved from the game engine) to variables named after their names.

(...)

for object in scene.objects:

   exec("%s = \"object\" " % (object.name))

'
The last line should be:
exec("%s = object" % (object.name))

The page "https://upbge.org/manual/manual/" don't exists

The first page of UPBGE Manual is: https://upbge.org/manual/
And any other page is: https://upbge.org/manual/manual/introduction/index.html
And this page in betwen don't exists: https://upbge.org/manual/manual/

I am currently developing the Logic Nodes documentation and placing the links, but I found this "syntax" error in the links.
I would like to know if there is a possibility to remove "...manual/" from the link, because in the future it would be a hard job to change the links all back to the correct ones

UPBGE Manual » Logic Bricks » Controllers » XOR Controller: tiny correction (grammar)

UPBGE Manual » Logic Bricks » Controllers » XOR Controller
https://upbge.org/manual/manual/logic/controllers/types/xor.html

"when One (and only one) of its inputs are TRUE"
should be:
"when One (and only one) of its inputs is TRUE"

UPBGE Manual » Logic Bricks » Properties: update

UPBGE Manual » Logic Bricks » Properties
https://upbge.org/manual/manual/logic/properties.html

The sentence:
"To turn debugging on, tick the Show Debug Properties checkbox in the Game menu."
should be something like:
"To turn debugging on, tick the Debug Properties checkbox in the Game Debug panel of the Render Properties."

Broken images on site

https://upbge.org/#/documentation/docs/latest/manual/manual/physics/introduction.html
At that page no one image is not available. Please, fix it.
Thank you!

Reported originally by @koorya

Download link to tutorial files not working on https://upbge.org/#/documentation

There's a difference between the documentation with the readthedocs look, compared to the modern look

When clicking the download link for level with assets, on https://upbge.org/#/documentation/docs/latest/manual/manual/tutorials/introducing_logic_nodes/first_person_shooter.html, the manual introduction page page is shown instead of getting a file download.

The download works fine on https://upbge.org/docs/latest/manual/manual/tutorials/introducing_logic_nodes/first_person_shooter.html

Here it does not work:

But here it does:

Attributes no longer read-only?

It says here that the attributes are read-only only:
https://github.com/UPBGE/UPBGE-Docs/blob/master/source/api/bge.types.KX_Scene.rst

That is not true anymore? At least not for UPGE 0.3 Alpha, build for Windows x64 2020-09-29.

I could do this in a script for instance :

objects = (bge.logic.getCurrentScene()).objects
objects["mycube"].applyRotation( [0,0.1,0],True )

The controller had a different owner than mycube , but cube was sure rotating.

Could be nice to clarify that the attributes are not read-only anymore (or?).

UPGE 0.3 is awesome btw.

bgl structure

Hello, are there any examples on bgl? I don't know how the structure would look, like where to put the draw function.

UPBGE Manual » Logic Bricks » Actuators » Actuator Editing: missing words

UPBGE Manual » Logic Bricks » Actuators » Actuator Editing
https://upbge.org/manual/manual/logic/actuators/editing.html

"The column headings contain controls to set which actuators, and the level of detail given, in the actuator column."
should be (something like):
"The column headings contain controls to set which actuators are displayed, and the level of detail given, in the actuator column."

Official Manual link

Hello,
what difference between the manual link that i see in this repo:

• https://upbge.org/docs/latest/manual/index.html

and the manual link that i see in the " https://upbge.org "

• https://upbge.org/#/documentation/docs/latest/manual/index.html

is it just a different theme, or content are different ?

In particular for the manual contributions should i fork "UPBGE-Docs " for pull requests ?

Thank you.

UPBGE Manual » Logic Bricks » Actuators » Edit Object Actuator: corrections

UPBGE Manual » Logic Bricks » Actuators » Edit Object Actuator
https://upbge.org/manual/manual/logic/actuators/types/edit_object.html

In section "Dynamics":

"Disable Rigid Body
Disables the Rigid Body state of the object – disables collision."
should be something like:
"Disable Rigid Body
Disables the Rigid Body state of the object, it then behaves like a Dynamic object (no rotation)."

---

"Enable Rigid Body
Disables the Rigid Body state of the object – enables collision."
should be something like:
"Enable Rigid Body
Enables the Rigid Body state of the object – enables rotation."