Dev:Ref/Release Notes/2.49/Game Engine

Release notes guidelines I've started to move things in release note page. When you edit here you have links to Templates under the edit box, click to go at the relevant template and edit it, so that Release Notes will be automatically completed as you write in the template. See also the guidelines here. Thanks! :) --mindrones 11:56, 12 April 2009 (UTC)

-- These docs are from revisions r17201 to r19906, changes still being made

-- WIP, 19906 to 20471, http://www.pasteall.org/5820 (included most bugs)

Textures

Video Texture

http://wiki.blender.org/index.php/Dev:Source/GameEngine/VideoTexture

• Loading of video files as texture supported
• Webcam streaming and online video streaming
• Mirror option to easily create mirrors
• Camera to texture option
• Updated ffmpeg to release version 0.5

Physics

Bullet Physics SDK update

• New generic 6dof constraint with run-time configurable limits, motors and springs to allow for physics-based vehicles, forklift, robots and ragdolls.
• Add support to lock individual axis during rigid body simulation, for translation and rotation. This makes it easier to do 1D or 2D physics (tetris, blockout) - set the physics type to rigid body and open the advanced popup.
• Added min/max linear velocity values which can prevent unstable physics by objects moving too fast. It can also be accessed by python to accelerate or throttle objects in their current direction.
• Improved dampening formula for dynamic and rigid objects, a value of 1.0 will not move the object at all.
• As usual, users can expect some different results with old files

Physics Integration

• GameObject "mass" attribute writeable & the setMass actuator.
• Dynamically update the coumpound parent shape when parenting or unparenting to a compound object.
• Recording physics no longer has problems with axis flipping
  

  fix for euler flipping

Sensor Object Type

New sensor object to generalize Near and Radar sensor, static-static collision capability.

A new type of "Sensor" physics object is available in the GE for advanced collision management. It's called Sensor for its similarities with the physics objects that underlie the Near and Radar sensors. Like the Near and Radar object it is:

• static and ghost
• invisible by default
• always active to ensure correct collision detection
• capable of detecting both static and dynamic objects
• ignoring collision with their parent
• capable of broadphase filtering based on:
  • Actor option: the collisioning object must have the Actor flag set to be detected
  • property/material: as specified in the collision sensors attached to it.
    Broadphase filtering is important for performance reason: the collision points will be computed only for the objects that pass the broahphase filter.
• automatically removed from the simulation when no collision sensor is active on it

Unlike the Near and Radar object it can:

• take any shape, including triangle mesh
• be made visible for debugging (just use the Visible actuator)
• have multiple collision sensors using it

Other than that, the sensor objects are ordinary objects. You can move them freely or parent them. When parented to a dynamic object, they can provide advanced collision control to this object.

The type of collision capability depends on the shape:

• box, sphere, cylinder, cone, convex hull provide volume detection.
• triangle mesh provides surface detection but you can give some volume to the suface by increasing the margin in the Advanced Settings panel. The margin applies on both sides of the surface.

Performance tip:

• Sensor objects perform better than Near and Radar: they do less synchronizations because of the Scenegraph optimizations and they can have multiple collision sensors on them (with different property filtering for example).
• Always prefer simple shape (box, sphere) to complex shape whenever possible.
• Always use broadphase filtering (avoid collision sensor with empty propery/material)
• Use collision sensor only when you need them. When no collision sensor is active on the sensor object, it is removed from the simulation and consume no CPU.

Known limitations:

• When running Blender in debug mode, you will see one warning line of the console:
  "warning btCollisionDispatcher::needsCollision: static-static collision!"
  In release mode this message is not printed.
• Collision margin has no effect on sphere, cone and cylinder shape.

Other performance improvements:

• Remove unnecessary interpolation for Near and Radar objects and by extension sensor objects.
• Use direct matrix copy instead of quaternion to synchronize orientation.

Adjustable Frame/Logic/Physics Rate

BGE: GUI control over frame rate, logic rate, physics rate and physics subrate.

Four new buttons in World settings to control frame rate:

• fps: Nominal frame rate in frame per second.
  Also sets the physics timestep = 1/fps
• phys: Maximum number of physics timestep per game frame in case the actual fps is less than nominal. This allows the physics to keep up with real time even if the graphics slows down the game.
• sub: Fixed number of simulation substeps per physic timestep.
  Improves the precision of the physics simulation. Useful for fast moving objects for example.
• log: Maximum number of logic steps per game frame in case the actual fps is less than nominal. This allows the logic system to follow the physics simulation.
  Upper bound = phys
  (setting the value higher than phys has no effect).
  On games with heavy logic system, it is useful to set this value to 1, to keep logic time under control.

All these values were already accessible from Python except phys:

• GameLogic.getMaxPhysicsFrame(): Gets the maximum number of physics frame per render frame.

• GameLogic.setMaxPhysicsFrame(phys): Sets the maximum number of physics timestep that are executed per render frame.
  Higher value allows physics to keep up with realtime even if graphics slows down the game.
  Physics timestep is fixed and equal to 1/tickrate (see setLogicTicRate)
  maxphysics/ticrate is the maximum delay of the renderer that physics can compensate.
  phys: integer

BlenderPlayer

BlenderPlayer Update

• Updated blenderplayer.exe -h text
• Fixing blenderplayer arguments (-c, -w, -f)
• Python can now import text (internal textblocks within the blend-file). It used to work only in the 3dview, but not in the player too.
• args after " - " are now ignored (same as with blender, so a game can have its own args read by python)
• Python can now access sys.argv args used to start the blenderplayer

Python API

GE Python API: Changes

• Replacing many get/set methods with attributes that give direct access to the properties.
  • Deprecation warnings can be disabled with "Ignore deprecation warnings" option to the game menu (disabled in Game Player by default).
  • Improved range clamping for attributes.
  • Added a utility that updates old scripts to use the new API. Be sure to keep a backup and carefully review the changes that are made.

Menu: Text → Text plugins → Convert BGE 2.49

• Internal and external scripts can now be imported as python modules.
• Python's dir(ob) now reliably returns all methods, attributes and property names for all game-engine types.
• Accessing game engine data that has been removed will raise a SystemError, check for this case with the 'invalid' [[1]] property.
• Python 2.6 compatibility (now supports python 2.3 - 2.6)

• GameObject names are now read only, (renaming was buggy)
• printing a GameObject wont raise an exception anymore.
  
• CListValue changes...
  • disable changing CValueLists that the BGE uses internally
    scene.objects.append(1) would crash when drawing.
    
  • types can now accept negative indicies eg scene.objects[-1]
  • fix for printing, scene.objects will no longer show [,,,]
  • An asserts for not yet implimented functionality, this would close blender.
    Better to print an error if the user manages to run this functions (I managed to by ListValue.count([1,2,3]))
    
  • New method - ListValue.from_id(int) which uses the int return of pythons id() function to lookup a list item.

gameOb.other = id(otherGameOb)
...some time later...
otherGameOb = scene.objects.from_id(gameOb.other)

• Changed GameLogic.addActiveActuator(actu, bool) to raise an error if the actuator is not in the list.
  Before it would allow any value as the actuator and fail silently (makes debugging scripts more difficult).
• Allow the actuator to be a string which is convenient if you dont want to change the settings of the actuator.
  GameLogic.addActiveActuator(controller.getActuator("SomeAct"), True)
  ...can be replaced with...
  controller.activate("SomeAct")
  
• Existing method ob.isA("KX_GameObject")now accepts python types eg. ob.isA(GameTypes.KX_GameObject)
  

GE Python API: Additions

• VideoTexture module
  TODO Document this
• OpenGL access from the game engine as a module so you can import BGL directly.
• New module GameTypes which gives access to all types defined by the BGE.
• GameLogic.getSceneList()
  • Dictionary style access to GameObject's ob.someProp = 10 can now be ob["someProp"] = 10
    This avoids naming conflicts with new attributes and is faster since it does not have to look up built in attributes first.
• print warnings when python attributes and methods conflict with game properties.
• experimental KX_GameObject attributes "sensors", "controllers" and "actuators" (NEAT !!!!)
• KX_GameObject.localInertia attribute.
• KX_GameObject.replaceMesh(mesh)
• KX_GameObject.sendMessage(...) and GameLogic.sendMessage(...)
• KX_GameObject.setParent(parent,compound,ghost), compound, ghost are new args.
• KX_GameObject.get(key, value) - dictionary like alternative to KX_GameObject["key"].
• KX_GameObject.has_key(key) - dictionary like function to check for a key.
• ListValue.get(key, value) - dictionary like alternative to ListValue["key"].
• ListValue.has_key(key) - dictionary like function to check for a key.
• KX_Camera.useViewport to get/set the viewport toggle, (deprecates enableViewport(bool))
• KX_Scene.addObject(...)
• KX_Scene.active_camera can now be set to set the camera without an actuator.
• KX_Scene.lights - list of light objects
• KX_Scene.cameras - list of cameras
• KX_Scene.objects_inactive - allows access to objects in unseen layers (before the AddObject actuator adds them).

BGE KX_Camera methods to handle Screen Space - (getScreenPosition, getScreenVect, getScreenRay)

• getScreenPosition(obj): Gets the position of an object projected on screen space.
• getScreenVect(x, y): Gets the vector from the camera position in the screen coordinate direction.
• getScreenRay(x, y, dist, property): Look towards a screen coordinate (x,y) and find first object hit within dist that matches prop.
  

Performance

Important Optimizations

• Speedup for bullet creating convex hull meshes for faster startup times.
  
• Speedup for bullet physics mesh conversion
• Speedup for Blender Player's profile drawing
• Implemented a cache for the expression controller for better performance.

Minor Optimizations

• Flat shaded faces can now share vertices's increasing performance for some models.
• Compile scripts when converting controllers to give more predictable performance and print syntax errors early on rather then when the script is first executed.
  
• Where possible use vec.setValue(x,y,z) to assign values to a vector instead of vec= MT_Vector3(x,y,z), for MT_Point and MT_Matrix types too.
• Added SG_Spatial::SetWorldFromLocalTransform() since the local transform is use for world transform in some cases.
• Removed some unneeded vars from UpdateChildCoordinates functions
• Py API - Mouse, Ray, Radar sensors - use PyObjectFrom(vec) rather then filling the lists in each function. Use METH_NOARGS for get*() functions.
  
• Py API - When reading python vector arguments, Check for a tuple rather then using a generic python sequencer, approx 2x speedup.
• Speed up mesh conversion by avoiding allocation/deallocation of material object on each face.
• Allow to create display list on meshes with modifiers but without armature and shape keys. These modified meshes are static and can be put safely in a display list. As the rendering of modifiers is done in direct openGL call, giving a bit of a performance boost.

BGE Scenegraph improvement

The scenegraph improvement consists in avoiding position update if the object has not moved since last update and the removal of redundant updates and synchronization with the physics engine and the Rasterizer.

Vizualizarea arborelui de selecţie

Arborele de Delimitare a Volumelor Dinamice, (DBVT) este folosit pentru a construi un arbore cu obiectele grafice din scenă. Elementele arborelui sunt cutii AABB (Aligned Axis Bounding Boxes) în care sunt incluse obiectele. Acest lucru oferă o bună precizie în scenele închise şi deschise. Acest nou sistem este activat în mod implicit, dar poate fi dezactivat cu un buton în setările World. Cu aceste îmbunătăţiri, selecţia şi o parte graficii Scenei devin de 5 ori mai rapide decât în versiunea ​​2.48. Cu toate acestea, viteza de lucru este vizibilă doar când ai mai multe obiecte (>100).

Selecţia ocluziilor

Selecţia ocluziilor se referă la abilitatea unor obiecte (occluders) de a ascunde alte obiecte (adică de a nu le trimite către GPU). Implementarea este realizată identic ca la arborele de selecţie.

Selecţia ocluziilor nu este activată implicit pentru că este o facilitate care cere mai întâi înţelegerea ei pentru a aduce mai multe beneficii. Dacă nu este folosită corect, ar putea încetini jocul. (Nu pre mult, totuşi, pentru că timpul de procesare se autoreglează.)

Cum funcţionează

Selecţia ocluziilor se activează atunci când defineşti cel puţin un "occluder" în scenă. Opţiunea pentru Occluder se află la butoanele pentru fizică (physics):

Opţiunea "Occluder" trebuie folosită doar pe obiecte de tip reţea. ..........As far as Physics is concerned, it is equivalent to "No collision".  The reason why I chose to make the Occluder mode mutually exclusive with other physics mode is to emphasize on the fact that occluders should be specifically designed for that purpose and not every mesh should be an occluder. However, you can enable the Occlusion capability on physics objects using Python and Logic bricks. We'll come to that.

When an occluder object enters the view frustrum, the BGE builds a ZDepth buffer from the faces of that object. Whether the faces are one-side or two-side is important: only the front faces and two-side faces are used to build the ZDepth buffer. If multiple occluders are in the view frustrum, the BGE combines them and keeps the most foreground faces.

The resolution of the ZDepth buffer is controllable in the World settings with the "Occlu Res" button:

By default the resolution is 128 pixels for the largest dimension of the viewport while the resolution of the other dimension is set proportionally. Although 128 is a very low resolution, it is sufficient for the purpose of culling. The resolution can be increased to maximum 1024 but at great CPU expense.

The BGE traverses the DBVT tree and for each node checks if it is entirely hidden by the occluders and if so, culls the node (and all the objects it contains).

To further optimize the feature, the BGE builds and uses the ZDepth buffer only when at least one occluder is in the view frustrum. Until then, there is no performance decrease compared to regular view frustrum culling.

How to use it

There are situations where occlusion culling will not bring any benefit:

• If the occluders are small and don't hide many objects.
  In that case, occlusion culling is just dragging your CPU down.
• If the occluders are large but hides simple objects.
  In that case you're better off sending the objects to the GPU.
• If the occluders are large and hides many complex objects but in a very predictable way.
  Example: a house full of complex objects. Although occlusion culling will perform well in this case, you will get better performance by implementing a specific logic that hides/unhides the objects; for instance making the objects visible only when the camera enters the house.
  

Occlusion culling makes most sense when the occluders are large objects (buildings, mountains, ...) that hide many complex objects in an unpredictable way. However, don't be too concerned about performance: even if you use it inappropriately, the performance decrease will be limited due to the structure of the algorithm.

Occluders can be visible graphic objects but beware that too many faces will make the ZDepth buffer creation slow. For example, a terrain is not a good candidate for occlusion: too many faces and too many overlap. Occluder can be invisible objects placed inside more complex objects (ex: "in the walls" of a building with complex architecture). Occluders can have "holes" through which you will see objects.

Here is a possible workflow to create occluders from a complex terrain:

• duplicate the terrain and make it low poly
• remove all horizontal parts and keep only the high elevation parts
• make all the face invisible and set the Occluder mode.

To optimize further, you may split the occluder into several objects (make an occluder from each mountain, each wall, etc.) and do the same for the terrain: this way, parts of the terrain that are behind occluders will not be rendered.

You can verify how the occlusion is working by running the game in wireframe mode.

In-game control

You can turn on/off the occlusion capability of an object with Python:

obj.occlusion = True
obj.setOcclusion(True, False)    #param1=occlusion, param2=recurse in children

The object doesn't need to be defined as an occluder in the GUI: you can enable occlusion capability on any mesh object, including static and dynamic objects during the game.

You can also use the Visibility Actuator:

Note that the layout of the actuator has changed: The Visible/Invisible mutually exclusive buttons have been replaced by two independent buttons: push the button to activate the feature (Visible/Occluding), unpush the button to activate the opposite feature (Invisible/Non-occluding).

Note that the actuator sets the Visibility and Occlusion mode at the same time. If you need to set them separately, use Python.

Known limitation

• If you want to use occlusion culling, you must at least have one occluder at the start of the game. The occluder doesn't need to be in an active layer. After that, you can enable and disable occlusion capability on every mesh objects during the game using on the In-game control.

Logic Bricks

Sensors

• New Pulse option for the collision sensor:
  • With the Pulse option enabled, any change to the set of colliding objects will trigger an event.
  • Changes in collision are detected by comparing the number of objects colliding with the last event, as well as a hash made from the object pointers.
  • Also changed the touch sensors internal list of colliding objects to only contain objects that match the property or material.
• Mouse Sensor:
  • now it's possible to get state of RMB
    
• BGE Joystick Sensor
  • Raised limit of 2 axis 8 axis pairs (8==16 joysticks axis pairs)
  • Added a new Joystick Sensor type "Single Axis", so you can detect horizontal or vertical movement, rather then just Up/Down/Left/Right
  • Added Python attribute "axisSingle" so you can get the value from the selected axis (rather then getting it out of the axis list)
    

New Tap Option

Sensor "tap" option to generate automatically on/off pulses

When enabled, this option converts any positive trigger from the sensor into a pair of positive+negative trigger, with the negative trigger sent in the next frame. The negative trigger from the sensor are not passed to the controller as the option automatically generates the negative triggers. From the controller point of view, the sensor is positive only for 1 frame, even if the underlying sensor state remains positive.

The option interacts with the other sensor option in this way:

• Level option: tap option is mutually exclusive with level option. Both cannot be enabled at the same time.
• Invert option: tap option operates on the negative trigger of the sensor, which are converted to positive trigger by the invert option.
  Hence, the controller will see the sensor positive for 1 frame when the underlying sensor state turns negative.
• Positive pulse option: tap option adds a negative trigger after each repeated positive pulse, unless the frequency option is 0, in which case positive pulse are generated on every frame as before, as long as the underlying sensor state is positive.
• Negative pulse option: this option is not compatible with tap option and is ignored when tap option is enabled.

Notes

• Keyboard "All keys" is handled specially when tap option is set:
  There will be one pair of positive/negative trigger for each new key press, regardless on how many keys are already pressed and there is no trigger when keys are released, regardless if keys are still pressed.
  In case two keys are pressed in succesive frames, there will be 2 positive triggers and 1 negative trigger in the following frame.

High Priority Controllers

A new bookmark button is available on the controller UI. When set, the controller is guaranteed to execute before all other non-bookmarked controllers, provided it is scheduled for execution.

This is useful for initialization scripts that run once at startup or scripts that must set some prerequisite for the other controllers at the start of each logic frame.

This feature is also available at python level with the "useHighPriority" attribute. It can be changed during the game.

Note that if several script are bookmarked, their relative order of execution is not guaranteed. Make sure they don't depend on each other.

Python Module Controller

Added support for any number of attributes, this means packages are supported automatically. As well as "myModule.myFunc" you can do "myPackage.myModule.myFunc", nested packages work too. The python controller is passed to the python function as an argument for functions that take 1 arg.

This allows live editing of scripts

• Thread http://blenderartists.org/forum/showthread.php?t=156672
• Video http://download.blender.org/apricot/live_bge_edit.ogv

Actuators

• added "toggle" an option for the property actuator, toggles bool, ints, floats and timer properties.
  

2D filters

• canvascoord - gl_TexCoord[3]
  • Now it's possible to get the canvas coordinates of the pixel.
• Print the detailed GLSL shader errors (once), for easier debugging.

Camera

Fisheye (Dome) and Spherical Panoramic Display

http://wiki.blender.org/index.php/Dev:Source/GameEngine/Fisheye_Dome_Camera

• Known limitation:
  • Resizing of the screen doesn't work in the gameplayer
  • Mouse cursor and some of its events are ignored
    
  • Reflection and Normal Map Input options (refl/norm) produces seams.
    

Miscellaneous

Various changes

• For "int" properties, use long internally rather than int, which gives a larger range.
  from −2,147,483,648 to +2,147,483,647 to...
  −9,223,372,036,854,775,808 to +9,223,372,036,854,775,807
  allowing you to store pythons id() values on a 64bit system.
• Expression Controller accepts modulus operations (%)
  
• Building the GameEngine without SDL is now possible - WITH_BF_SDL
  
• Building without Solid & Sumo physics is now possible - WITH_BF_SOLID
  

Bug Fixes

Other Bug Fixes

There are many minor bugs that where fixed since 2.48a, this list shows bugs users might have noticed.

• KX_Scene's culling algorithm didn't use the correct camera.
  
• logicBrick.getExecutePriority was crashing because of a typo
  
• Fixed crash python api CListValue.index(val) and CListValue.count(val) when the pyTypes could not be converted into a CValue.
  
• Fixed crash when the replace mesh actuator references a mesh that has no object in the current scene.
  
• Physics debug visualization now works with overlay scenes
• KX_GameObject SetParent - Disallowed setting a parent to its self, caused a recursion crash.
  
• KX_PolygonMaterial's "gl_texture" attribute wasnt checking for a valid m_tface
  
• KX_RayCast::RayTest - didnt check for a valid physics_environment and would crash
  
• KX_SceneActuator's getCamera python function wasnt checking if there was a camera.
  
• key logging never worked for alphanum keys -=_+ and |\
  
• the End key didn't work work at all for the keyboard sensor.
  
• Adding new lights wasnt setting the light layer from the parent
  
• refcounting bugfix, gameOb.getParent() and gameOb.parent both added a reference when they should not have.
• Random sensor will produce true random sequence of events when seed is set to 0 in the GUI.
• Multiple hats didnt work, Allow up to 4 hats (was 2).
• Kinematic object were not giving the correct friction to dynamic object when they have a translation and rotation movement at the same time (translation is ignored).
• Software OpenGL crashed on some systems when starting the BGE (SDL related).
• When a dynamic object is parented to a compound shape and then unparented, it jumps at the position it had before the parenting.
• Fix Near/Radar position error on newly activated objects, causing several detection problems in YoFrankie
• Disable force/velocity actions on static objects
• Fix margin not passed correctly to gImpact shape.
• Methods didn't check for zombies which could crash in the case where a method for an object is kept.
• missing NULL check for scene crashed blender when it failed to load a file.
• relative path variable wasnt updated when loading new files.
• lamp energy IPO was not supported in glsl mode.
• 'No Sleeping' option rigid body objects.

Reported bugs fixed

• [#18175] error on anaglyph view of a splitted viewport.
• [#18228] Specular changing when camera rotates (it's using infinite viewpoint instead of local)
• [#17974] two small fix for blender 2.48 (memory leak and uninitalized vars)
• [#18419] Bad drawing of alpha blended faces in overlay scenes
• [#18423] Lights in overlay scenes get merged with the original scene when the mode is not GLSL
• [#18428] GLSL mode is using lights in hidden layers to generate shadow
• [#18154] 2dFilter and motion blur should run only once to all the scenes
• [#18504] The GL_PROJECTION matrix is being reset by the 2dfilter.
• [#18504] Dupligroup offsets don't work in BGE.
• [#18168] Get local orientation of object using game engine python script system.
• [#18521] Dupligroups + Bullet Softbodies are broken.
• [#17678] "Mouse over" sensor broken when using viewports.
• [#17670] Python controlled mist doesnt work in textured mode.
• [#17863] Shaky game camera.
• [#17950] crash when GE softbody is parented to a rigid body/soft body/dynamic object.
• [#18496] Partial fix for the issue with light state switching when using Dome.
• [#18606] Writing to KX_GameObject.orientation causes crash
• [#18616] Scons+MinGW compiling error with gaming engine enabled.
• [#18681] Mousesensor Over doesn't work in ortho mode of 3dview camera
• [#18749] Crash on joysticksensor.getAxisValue()
• [#18819] save and load globalDictionary actuators don't load the proper files in 2.49 RC3
• [#18840] Joystick sensor lag
• [#18624] Collision detection fails on parented objects. (partial fix).
• [#17796] Glsl + bones + set smooth = bug on vertext groups.
• [#18091] Hitbox of object X doesn't move along when object X is parented to object Y.
• [#18596] No ipo dynamics in 2.49rc1.
• [#18732] Python Light options don't work with GLSL materials.
• [#18665] Servo control and relative motion
• [#18762] Incompatibility between the soft body deformer and other types of deformer was causing the soft body to disappear in the game.
• [#18664] Incorrect behavior for objects when unparented. A parented object is made static in all cases.