Release notes version 0.3.0
The new and famous Blender viewport engine is now used by UPBGE. Additionally, we can use the other engines availables, as grease pencil or workbench.
Moreover, there is an option to reproduce the viewport exactly as blender one (including the icons, etc)
The Collection actuator is meant to replace a part of Scene actuator.
In the Scene actuator we had:
- Overlay Scenes which were used by the ones who use bge to create games.
- Suspend/Resume Scene.
The Collection actuator can replace this logic.
Suspend/Resume have 3 options:
- logic (suspend/resume logic + animations for all objects + children in the collection).
- physics (suspend/resume physics for all objects + children in the collection).
- visibility (suspend/resume visibility/render for all objects + children in the collection).
Overlay has 2 modes:
- Add overlay collection (render all objects of the collection with a selected camera in overlay).
- Remove overlay collection.
Notes:
-
The camera used to render in overlay must not be used neither for ImageRender, neither as main active camera.
-
The objects of the overlay collection are only influenced by the lights which are in overlay collection.
-
Overlay render pass can have a BIG performance impact on low end GPUs because it requires an ENTIRE extra render pass.
Basic tutos:
Overlay Camera Options:
In Camera tab > Game Camera Settings, you have several options related to overlay render pass:
-
Game Overlay Mouse Control: When enabled and if you are using logic bricks, the mouse events for Mouse Over Sensor and Mouse Over Any Sensor will be computed in the Overlay Camera space. It means that you will be abled to activate these sensors for objects in overlay collection. If you don't use logic bricks (python) you can still change kxscene.active_camera to choose in which "camera space" the mouse events will be handled.
-
Overlay Pass Render Settings: You can choose to disable scene post processing effects (Bloom, AO, SSR, World Volumetrics) in overlay pass only. Like that the main render pass can have bloom but the overlay pass can be rendered without bloom for example. Same for other mentionned post processing effects.
As layers disappeared in 2.8, Objects in the Scene are now organized with Collections.
During conversion, 2 gameobjects lists are created:
- list of gameobjects considered as active (scene.objects in python)
- list of gameobjects considered as inactive (scene.objectsInactive in python)
To know in which list an object must go, the EYE beside the object in outliner has to be used:
If the eye is checked, Objects will be converted as active gameobjects. If the eye is not checked, Objects will be converted as inactive gameobjects (which can be spawned during runtime).
The following rules have to be applied:
- ALL children MUST have the same eye state than the parent.
- ONLY THE EYE should be used to say which gameobjects will be considered as active or inactive (logic/physics/visibility at game start).
- Viewport visibility flag must NOT be used.
Additional tip:
- You can organize your objects in several collections. If you have a collection with only inactive objects, you can toogle eye state using right click on collection > Visibility > Show All Inside/Hide All Inside.
-
In old bge or upbge based on Blender 2.7, viewport texts were not displayed. In 2.8+, as we are using directly eevee to render, viewport Texts are rendered and replace old bge Freetype Texts.
-
Viewport Texts can be edited in the same way than in old bge with game properties.
-
For more options about texts you can use bpy API: https://upbge.org/#/documentation/docs/latest/api/bge.types.KX_FontObject.html for example. You can also enable python tooltips in user preferences and get the all the API related to fonts via user interface.
-
You can still use Freetype Texts in post processing using blf and bgl modules.
Now it is possible to use bpy in embedded and player!!!!
Actually, we strongly recommend to use Python Tooltips in User Preferences > Interface:
#IMPORTANT In 2.8 bge, KX_GameObject is just a "container" for a Blender Object. You can access this Object like that:
kxscene = bge.logic.getCurrentScene()
kxob = bge.logic.getCurrentController().owner
ob = kxob.blenderObject
From there you can extrapolate:
kxLight = bge.logic.getCurrentScene().objects["Point"]
obLightData = kxLight.blenderObject.data
def increaseLightPower():
obLightData.energy += 0.1
The API changed a bit. Check this updated tutorial: https://audaspace.github.io/bindings/tutorials.html
The options to play actions in 0.3 are globally the same than in 0.2. However, there were some internal changes to have it working in 0.3.
- Remaining IPO controllers:
- Transform actions (actions related to location, rotation, and scale).
- Camera actions (camera lens, clip start, clip end). It corresponds to elements of camera projection matrix which can be animated.
- Light actions (light energy, color, distance). The code has been adapted to have these values animatable in 2.8+ upbge.
- Object color actions. The code has been adapted for 2.8+.
- Removed/unused IPO controllers:
- Material IPO controllers (replaced with nodetrees system)
- World IPO controllers (replaced with nodetrees system)
- Armatures actions:
-
We can still use action actuator or kxob.playAction to play armatures actions, but due to 2.8+ adaptation, the internal code called to play armatures actions is default Blender viewport animations system. For now, armature actions (and more globally deform modifiers actions) are slower than in old bge. Performances related to deform tasks work globally better on linux than on windows OS.
-
Part of logic bricks related to armatures (armature actuator and armature sensor) has not been adapted yet. Python scripts using bpy API can be used to handle missing logic (bone contraints...).
- Shapekeys actions:
- Code has been updated to play shapekeys actions with action actuator or kxob.playAction bge API. However, blendin for shapekeys has not been adapted yet.
- NodeTree actions:
- Action actuator or kxob.playAction can be used to play any kind of node tree actions (World and Material shaders, Geometry Nodes...).
- Modifiers actions:
- Normally, all Deform modifiers actions are supported.
- Grease Pencil modifier actions:
-
Several action types for grease pencil modifier are supported. See: https://github.com/UPBGE/upbge/pull/1440 .
Example file: all_modifiers.zip
Gpencil_modifiers_3.mp4
- Constraints actions:
- Animatable transform constraints actions are supported (follow path action).
- Custom properties actions:
- A Custom property or IDProperty can be animated and used in a shader nodetree for example with "Attribute" node. The Custom property action can be played with action actuator or kxob.playAction.
Additional note:
- A single keyframe action can be used to refresh a Geometry nodetree during bge runtime (In viewport, geometry nodes sometimes need the timeline to be played to be refreshed. The same can be done using a single keyframe action (a value keyframed anywhere in Geometry nodetree and played with an action actuator)).
As OpenGL version changed, 2D filters code was adapted. Concretely, there are only 2 minor changes:
uniform sampler2D bgl_RenderedTexture;
in vec4 bgl_TexCoord; // It needs to be declared at the beginning of the 2D filter
out vec4 fragColor; // It needs to be declared at the beginning of the 2D filter
void main()
{
vec4 sceneColor = texture(bgl_RenderedTexture, bgl_TexCoord.xy);
fragColor = sceneColor * vec4(0.0, 0.0, 0.8, 1.0); // makes the scene blueish
}
gl_FragColor and gl_TexCoord[0].st are replaced as shown above.
The predefined uniforms are the same than previously:
- bgl_RenderedTexture
- bgl_DepthTexture
- bgl_RenderedTextureWidth
- bgl_RenderedTextureHeight
- bgl_TextureCoordinateOffset
We tried to adapt ImageRender code for 2.8 viewport. A part of the python API is not relevant anymore.
As render is done with eevee: alpha, horizon, zenith, background... are deprecated. Before refreshing texture, you can use a pre_draw callback to enable background transparency, modify background, disable some eevee's builtin post-processing effects like that:
import bpy, bge
from bge import texture
cont = bge.logic.getCurrentController() # on main camera
scene = bge.logic.getCurrentScene()
rendercam = scene.objects["rendercam"]
renderplane = scene.objects["renderplane"]
bge.overlayTex = texture.Texture(renderplane, 0, 0)
bge.overlayTex.source = texture.ImageRender(scene, rendercam)
bge.overlayTex.source.capsize = [512, 512]
filter = scene.filterManager.addFilter(0, bge.logic.RAS_2DFILTER_CUSTOMFILTER, cont.actuators["overlay"].shaderText)
def preDraw():
depsgraph = bpy.context.evaluated_depsgraph_get()
scene_eval = bpy.context.scene.evaluated_get(depsgraph)
# Make background transparent before rendering overlay texture
scene_eval.render.film_transparent = True
# Disable not wanted effects before rendering overlay texture
scene_eval.eevee.bloom_intensity = 0
def renderOverlay():
# Append preDraw to bge.overlayTex.source pre-draw callbacks
bge.overlayTex.source.pre_draw.append(preDraw)
# Render Overlay Camera to renderplane texture
bge.overlayTex.refresh(True)
def sendUniformsTo2DFilters():
# Render overlay texture
renderOverlay()
# send uniforms to 2D filter to do the compositing between main render and overlay
if filter is not None:
filter.setTexture(0, bge.overlayTex.bindId, "overlayTex")
Additional notes:
- In a shader node_tree, Image Texture node "interpolation mode" may need to be set to "closest" to have ImageRender working properly.
- You need to use evaluated scene in pre_draw callbacks for performance reasons (See code above).
- In ImageRender and ImageMirror, the "samples" optional argument which was used to set MSAA is now used to set ImageRender number of "Samples per frame" done (similar to this: https://github.com/UPBGE/upbge/wiki/Release-notes-version-0.3.0#samples-per-frame option).
- An interesting use of ImageRender is to use v3d.shading.render_pass ( https://docs.blender.org/api/master/bpy.types.View3DShading.html?highlight=render_pass#bpy.types.View3DShading.render_pass ) to do compositing in a 2D filter.
As libload caused too much issues in previous bge versions, a new system is implemented to import data in bge during runtime.
- First step is to load a bpy.types.Object (a blender Object) in blender using bpy:
It can be done in several ways but the most common is to use Append, as when you append an object from another .blend:
filepath = "C:\\Users\\Me\\Desktop\\cube.blend"
bpy.ops.wm.append(directory=filepath+"/Object/", filepath="cube.blend", filename="Cube")
This step can't be asynchronous when you are using Append. Only Alembic files have an option to import data asynchronously (as far we know). See Blender API for that.
- Second step is to convert the Object into a KX_GameObject:
kxob = kxscene.convertBlenderObject(bpy.data.objects["Cube"]) #considering that we just appended the cube to the scene
When you append/import several Objects at the same time, you can convert all objects asynchronously:
When you are using these methods, you might want, after conversion, to find bge.types.KX_GameObject (s) from bpy.types.Object (s):
# example if we want to get gameobjects after we called convertBlenderCollection
gameobjList = []
for ob in collection.objects:
kxob = kxscene.getGameObjectFromObject(ob)
gameobjList.append(kxob)
As in 0.2, the normal way to add gameobjects in kxscene is to use kxscene.addObject method.
Notes:
- Default behaviour:
-
First, only gameobjects in kxscene.objectsInactive can be spawned. Please read https://github.com/UPBGE/upbge/wiki/Release-notes-version-0.3.0#layers-replaced-with-collections .
-
When you are using addObject method with default options, a gameobject instance sharing the same mesh and materials is spawned.
- Full Duplication:
- If you need to have a full copy of the gameobject (which doesn't share mesh/materials), you need to use an optional argument:
kxscene.addObject("Cube", empty, 0, True) # addObject(object, reference, time=0, dupli=0)
This "full duplication" option is also available in add object actuator (edit object actuator) UI.
- When you are using "full duplication", only the object is spawned and not its children (because we can't know if you also want a full duplication of the children or not)
- Custom duplication:
- If you need to have more control on duplication options, you need to use bpy first to duplicate only what you want, then use kxscene.convertBlenderObject method to create a new KX_GameObject from the newly created duplicated Object.
- Instance Collections:
- In 2.8+, Groups have been replaced with Instance Collections. Instance Collections can be spawned too. It is used to spawn several gameobjects at the same time and recreate the relationships (rigid body constraints, actuator relationships) between these gameobjects.
As in 0.2, replaceMesh can be done only for rendered mesh, both for rendered and physics mesh, or only for physics mesh.
However, there is a limitation concerning physics mesh:
When using Replace Mesh actuator or replaceMesh python API, the physics shape can only be recreated from RAS_MeshObject registered at the moment of conversion (when bge starts).
A new optional argument is added to reinstancePhysicsMesh from "evaluated Object" (Object with modifier applied).
Evaluated Object corresponds to the last available rendered gameobj/Object shape.
If the Object has modifiers, physics can be reinstanced/recreated from this evaluated Object:
- Reinstance physics from current evaluated gameobj/Object:
kxob.reinstancePhysicsMesh(evaluated=True)
- Reinstance physics from another evaluated gameobj/Object:
cube = kxscene.objects["Cube"]
suzanne = kxscene.objects["Suzanne"]
cube.reinstancePhysicsMesh(gameObject=suzanne, evaluated=True)
Warning: In this case, Suzanne evaluated shape (suzanne with modifiers applied) must be available. Suzanne evaluated shape is normally available if Suzanne is in scene.objects (active objects) but not if Suzanne is in scene.objectsInactive (inactive objects) because the depsgraph avoids to compute evaluated shapes for inactive objects.
When the evaluated shape is not available, the non evaluated mesh is used instead (Mesh without modifiers applied) to recreate the physics shape.
- Reinstance physics from a RAS_MeshObject:
cube = kxscene.objects["Cube"]
suzanne = kxscene.objects["Suzanne"]
cube.reinstancePhysicsMesh(meshObject=suzanne.meshes[0])
In this case, physics will be recreated from Suzanne RAS_MeshObject registered at the moment of conversion (when bge starts).
- Reinstance physics from a non evaluated gameobj/Object:
cube = kxscene.objects["Cube"]
suzanne = kxscene.objects["Suzanne"]
cube.reinstancePhysicsMesh(gameObject=suzanne) # evaluated=False by default
Physics shape will be recreated from Suzanne wihout modifiers applied.
-
2.8+ adaptation of LOD has not anymore a distinction between Mesh and Materials. When you change of LOD, both mesh and materials are changed.
-
A new option named "Physics Update" has been added in LOD panel to update physics shape when a LOD changes.
-
The "Physics Update" option won't work if you are using "viewport render" mode.
"""
Copyright <2020>
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
"""
import bpy, pip, subprocess, bge, aud, sys
try:
from gtts import gTTS
except ImportError:
pybin = sys.executable
subprocess.check_call([pybin, "-m", "pip", "install", "--upgrade", "pip"])
subprocess.check_call([pybin, '-m', 'pip', 'install', 'gTTS'])
from gtts import gTTS
own = bge.logic.getCurrentController().owner
if bge.logic.getCurrentController().sensors['Always'].positive or bge.logic.getCurrentController().sensors['Play'].positive:
# Controls all audio that plays during game
if not bge.logic.getCurrentController().sensors['Play'].positive:
tts = gTTS('Good morning.', lang='en-au', slow=True)
else:
tts = gTTS(own['input'], lang='en-uk', slow=True)
tts.save('hello.mp3')
if 'device' not in own:
device = aud.Device()
own['device'] = device
else:
device = own['device']
factory = aud.Sound.file('hello.mp3')
handle = device.play(factory)
handle.pitch =1.25
The former feature to play animated textures was removed during the eevee refactor. Now there is at least 2 ways to replicate the same functionality:
-
Using the new Sprites Animation node that you can find at shader editor (Add->UPBGE->Sprites Animation) Below, if you click on the image, you can see a video tutorial on how to implement it:
For best results unwrap with cube projection and enable scale to bounds. -
Using nodes and object color. You can see an example here below (Thanks to Jacob Merrill (BluePrintRandom)):
1. Add an uv input node
2. Add a vector math node
3. Connect UV node to top input of vector math node
4. Add object info node - connect object color to math node input 2
5. Connect math node to texture node vector input
Below, if you click on the image, you can see a video tutorial on how to implement it:
Example archive: fire_sprite.zip
The object color is in object property tab in render viewport display and you can change these values, and keyframe them.
https://blenderartists.org/t/how-to-record-keyframes-in-game-engine-upbge-blender-2-8/1233170/5 (copy and develop it)
Viewport denoising can cause some glitches/artifacts when camera is moving.
You can try to disable it in render tab > sampling.
A. You can add either the fxaa glsl filter:
- In text editor > templates > openGL shading langage, click on fxaa.glsl to open the filter in the text editor.
- On the main camera, add an always sensor (without pulse mode), add a custom 2D filter actuator and select fxaa.glsl. Link sensor and actuaor.
B. You can use either builtin SMAA filter in render tab > sampling.
Start game to see if it improves the rendering.
Note: Disabling viewport denoising can impact other eevee's post processing effects (AO for example), then if you disable viewport denoising, some eevee's post processing effects won't work properly.
import car object geometry - apply modifiers and join everything...
Rotate vehicle so that front of vehicle faces -Y, or downwards viewing from top. Apply rotation and scale and make physics "no colision".
If single geometry, separate each wheel and reset origin to centre of geometry, optionally rename each wheel accordingly, to easily identify later.
Add subdivided cube with Shrinkwrap Modifier to envelop car body. Set physics to Rigid Body, collision bounds to triangle mesh. Parent car's body to cube and set drawmode to wireframe.
Select cube, add vehicle.setup component. Set Mass, Stability, and set each wheel by name. Set other settings in component.
Simplest way to manipulate the vehicle: Add a float "force" property and a float "steer" property. Add keyboard sensors with TRUEPULSE to add to steer and force property. Add negative numbers to reverse directions. to read the speed add a "speed" property and read it.
Demo .blend: https://drive.google.com/file/d/1_ij16K5lFQXfQhD40vGsYLLBpF0wTLnB/view?usp=sharing
When we are working in viewport, volumetrics work fine for a static image, but at runtime, default eevee's code can cause volumes flickering. Volumes blending option was added by lordloki to fix this.
Demo .blend: https://drive.google.com/file/d/1--lTR3rBM8Fwy7LlYjcIj2yrUBb0jaMe/view?usp=sharing
As the depsgraph does many things automatically, there are some cases where the user wants to use depsgraph object transform instead of logic transform.
In this case (and surely other cases (blender constraints...), the user might want to be abled to use depsgraph transform instead of the scene graph transform (transformation with logic/physics/bge scripts/bge constraints...)
This is why we can add an option in object tab to let the user choose if he wants to let the depsgraph do the transformation instead of bge.
2.8+ upbge has 2 rendering modes:
A. The first (default one) has been implemented to handle most of old bge rendering features.
As in 0.2 (based on blender 2.7), this mode allows you to use:
- VideoTexture module (ImageRender...).
- Custom viewports.
- 2D filters.
- Overlay Collections (which replaces Overlay Scenes).
- BGE pre and post_draw callbacks.
Canvas/Viewport sizes are handled in the same way than in old bge.
Only KX_Camera "area" is drawn, and we did as best as possible to have this mode working in the same way than in old bge.
This mode works only with eevee (material preview and rendered) and grease pencil rendering engines.
B. The second one can be use checking "Use Viewport Render" in render tab.
It is using directly Blender viewport normal rendering pipeline.
a. Benefits:
- You can use all render engines included in Blender (wireframe, workbench, eevee, grease pencil, cycles and possibly other external render engines).
- You can choose to draw overlays or not (outlines, relationship lines, bones, floor grid...).
- You can use Stereoscopy rendering options.
- You can use VR features.
b. Inconvenients:
- Specific bge rendering features won't work.
- It can be slightly slower than default mode.
- It has not been tested with all bge features (some features might not work as expected).
Notes:
When using "Viewport Render" mode:
- You can do pre and post draw callbacks but using bpy draw handlers (bpy.types.SpaceView3D.draw_handler_add/remove).
- You might be abled to use OffScreen Rendering to replace Video Texture module features.
Several things are not supported in "viewport render" mode.
- 2D filters are not implemented when we are in "viewport render" mode (but there will surely be realtime compositing in next blender versions).
- ImageRender doesn't work (We can use blender offscreens instead).
- Overlay collections are not supported in viewport render mode.
- BGE post_draw callbacks are not supported (we have to use bpy draw handlers instead).
- Custom BGE viewport should not work.
- LOD physics update option won't work in "viewport render" mode.
- Samples per frame option is not available.
When using EEVEE:
-
If nothing nothing is moving/changing in the Scene, an accumulation of several render passes is done. The number of viewport render passes which will be done for a "static scene" is set according to Viewport Samples number (in render tab > Sampling > Viewport Samples). Between each render pass, some settings are changed (for example, view is being slightly jittered) to improve anti-aliasing and to smooth shadows (Soft Shadows), volumetrics...
-
As soon as something changes in the 3D view, only 1 sample is rendered for performance reasons, then global image quality decrease (Less efficient anti-aliasing, no Soft Shadows...).
-
upbge based on 2.8+ adds an option "Samples per frame" in render tab to allow to accumulate several viewport samples per rendered frame, which improves a lot quality in some scenes but has a big performances cost.
-
The number of samples per frame is clamped between 1 and Viewport Samples number.
-
This option is only available for default render mode (not available in "Viewport Render" mode)
Soft Bodies code has been adapted for 2.8+.
- We changed the default behaviour for collisions between a SoftBody and a Rigid Body enabling "Cluster Collisions" > "Rigid to SoftBody" option. Depending on physics shapes, it can work better but sometimes, it is causing weird behaviours, then you can disable it.
Under label "Physics Joint Error Reduction" in Scene tab > Game Physics settings, new bullet settings are exposed:
Notes:
- upbge 2.8+ is using current bullet library bundled with blender.
- We changed default "ERP for contact constraints (erp2)" value to have same behaviour than with previous versions of Bullet. The new default was set to 0.2. We changed it to 0.8 (old bullet versions default value) to avoid an issue handling collisions between a dynamic and a static object when dynamic object position is edited using applyMovement (worldPosition) (instead using force or velocity (normal way to move a dynamic object)).
An option is added to use "Continuous Collision Detection", and 2 new bullet settings are exposed:
- Default bullet mode is "Discrete Collision Detection". Continous collision detection can improve collision detection for fast moving objects and avoid "tunneling effect".
General articles on the topic:
Currently, normal map node is a bit slow for realtime. An addon is included to replace normal map nodes and make them faster
