some more cleanup:
- made structure in source/gameengine/PyDoc/bge.events.rst to be able to crosslink properly
- cleaned notes and warnings syntax, and also now they are always the last elements after all the other tags
- substituted some lists of possible values of a parameter with links to lists of values (not finished)
like in bge.types.html#bge.types.SCA_PythonKeyboard
- uncertain about some values, like in http://www.blender.org/documentation/250PythonDoc/bge.types.html#bge.types.SCA_ISensor.status
(list of KX_SENSOR_INACTIVE,... etc aren't documented or non-existant, will investigate)
- now that I've made syntax changes in the previous commit I moved blocks to to have sensors/actuators grouped together
- added sections to have a nice table of contents
- formatted 2 lists and links to classes
* source/blender/python/doc/sphinx_doc_gen.py
changed syntax for declating attributes type to use :type: instead of *type* os it
* source/gameengine/Ketsji/KX_PythonInit.cpp
While documenting I've found that we have two naming conventions for constraints in BGE python api,
example: KX_CONSTRAINTACT_DIRPZ and KX_ACT_CONSTRAINT_FHPX: the right convention is KX_CONSTRAINTACT_xxx
After talking with dalai and cambpell we agreed that this kind of change is better suited for NExyon GSoC
so I marked as TODO
Also, found 2 duplicate rows, fixed after askin nexyon
* source/gameengine/PyDoc/bge.logic.rst
there were 2 blocks for constraints, I've put them together in docs and fixed some other lines
* source/gameengine/PyDoc/bge.types.rst
first cleanup: mainly started using ":type:", it was mixed usage of *type* and **type**
started cleaning some bullet list in a way that varibles link to the constant in appropriate page
I'll continue later
PhysicsConstraints module documented by Jean-François (Ninja Goliath) based on GameKit 2nd ed.
Thanks for the initiative and the great help!
General advice for anyone helping with EpyDocs:
* use :: instead of : to keep the indentation correct,
* use B{} for clarity when needed (e.g. createConstraints)
Adding F13 to F19 to complement Matt's recent commit
* There are other (not so important) functions in PhysicsConstraints module that are not exposed in the documentation right now.
The generated page is temporarily here, if someone want to review it:
http://blenderecia.orgfree.com/blender/tmp/PhysicsConstraints-module.html
The patch exposes mouse and keyboard read-only properties in the GameLogic module
Also renames bge.keys to bge.events (* Note: name of bge submodules (logic, render, ...) may change before 2.5 final release [right Campbell?]).
"""
This patch adds two new types to the BGE:
SCA_PythonKeyboard
SCA_PythonMouse
These two types allow users to make use of the keyboard and mouse without the need for a keyboard or mouse sensor.
SCA_PythonKeyboard has an events property that acts just like SCA_KeyboardSensor.events.
SCA_PythonMouse also has an events property to check for mouse events. Further more it supports getting and setting normalized cursor position (from 0.0 to 1.0) with SCA_PythonMouse.position. The cursor can be shown/hidden using SCA_PythonMouse.visible.
"""
Its use is similar with current mouse and keyboard controllers. With the exception of mouse position being normalized and writable as well (replacing Rasterizer.setMousePosition).
Code Sample:
######
from bge import logic, events
mouse = logic.mouse
keyboard = logic.keyboard
for key,status in keyboard.events:
if status == logic.KX_INPUT_JUST_ACTIVATED:
if key == events.WKEY:
print(mouse.position)
# move_forward()
mouse.visible = True # turn cursor visible
mouse.position = 0.5,0.5 # centralize mouse - use tuple
######
* Important Note: mouse.position still will not work properly for Letterbox mode.
In order to fix letterboxing I may need to move the set x,y mouse function to inside the canvas code (to avoid duplicated code between mouse sensor and bge.logic.mouse). I'll leave this for another commit though.
Thanks Mitchell for the work on that.
- added new mathutils.Color() type, use with rna so we can do for eg:
material.diffuse_color.r = 1.0
# also has hsv access
material.diffuse_color.s = 0.6
- made Mathutils and Geometry module names lowercase.
We have already a .sh file to build epydocs from Linux, so why not to have it in Windows as well ;) I think that this guide can help people interested in help with the API documentation to test their work.
I'm actually already in touch with at least one volunteer helping with PhysicsConstraints module. VideoTexture may not be a one man job though, for I hope this document can also help.
of course it wasn't only a matter of adding the properties in the api :)
The code of validValueForIntervalProperty and modeChange are the same BUT in the future they shouldn't be, for I think it's fine to keep them as separated functions.
Bonus fix: Also we are now checking if the new mode is interval and update the range expression.
Add optional parameter to VideoTexture.Texture refresh() method
to specify timestamp (in seconds from start of movie) of the frame
to be loaded. This value is passed down to image source and for
VideoFFmpeg source, it is used instead of current time to load
the frame from the video file.
When combined with an audio actuator, it can be used to synchronize
the sound and the image: specify the same video file in the sound
actuator and use the KX_SoundActuator time attribute as timestamp
to refresh: the frame corresponding to the sound will be loaded:
GameLogic.video.refresh(True, soundAct.time)
PhysicsConstraints is documented in the Game Kit Book:
http://download.blender.org/documentation/gamekit1/
VideoTexture is documented in the wiki:
http://wiki.blender.org/index.php/Dev:Source/GameEngine/2.49/VideoTexture
I don't think I will have time to fill the documentation. But I hope this commit helps someone interested in helping it.
Therefore volunteers to document those modules are highly welcome !!! (let's give to BGE the documentation it deserves)!
* + added GameLogic.Lave/LoadGlobalDict + some typo fixes
How it works now:
whenever you have to read/write object names you can do it without the prefix "OB". (it's not hard at all to fix scripts)
How it was before:
It was a mess :)
We had an inconsistent API where sometimes you had to input "OBname" and other "name" directly to assign object as data (usually in actuators).
Justification for the change:
Talking with Campbell we had since a while ago this feeling that this should be changed any time we were going to deprecate the API. So in order to deliver Blender 2.5beta0 with a more close-to-the-final API we decided that today was a good day to implement that.
Remaining issues:
1) VideoTexture uses IM or MA to identify the output material/texture. I haven't touched that, but it does look a bit off. (i.e. I didn't changed any MA, IM naming)
2) I didn't see the code of dynamic mesh. It may need to be edited as well.
http://wiki.blender.org/index.php/BlenderDev/Blender2.5/Unix_FHS
for scons WITH_BF_FHS enabled an alternative layout eg.
scons WITH_BF_FHS=1 BF_INSTALLDIR="/usr/local"
for CMake just run "make install" after make (CMAKE_INSTALL_PREFIX is used for the base path)
Currently only scripts use both the system and user path correctly, other areas of blender have their own path code inline with lots of ifdefs, needs to be carefully updated.
Instead use __contains__, eg.
if key in gameOb: ...
Mathutils returns from PyMath.cpp were incorrectly using wrapped Mathutils types. Wrapped types should only be used with a callback now.
Previously the only way to detect if the mouse moved over a different object was to enable true-level-triggering and have a python script detect the change.
When the Pulse option is set, focusing on a different object pulses true.
Python attribute is focusSensor.usePulseFocus.
This is similar to the collision sensors pulse option where changes in the set of collision objects generates an event too.
Found this functionality missing when trying to make a logic demo that used mouse-over with overlapping objects.
When the mesh field is left blank and Physics option is enabled, it reinstances the physics mesh from the existing mesh.
like calling gameOb.reinstancePhysicsMesh() from python.
Add support back for reinstancePhysics mesh, a frequently requested feature in the BGE forums.
from what I can tell Sumo supported this but bullet never did.
Currently only accessible via python at the moment.
- rigid body, dynamic, static types work.
- instanced physics meshes are modified too.
- compound shapes are not supported.
Physics mesh can be re-instanced from...
* shape keys & armature deformations
* subsurf (any other modifiers too)
* RAS_TexVert's (can be modified from python)
Moved the reinstancePhysicsMesh functions from RAS_MeshObject into KX_GameObject since the physics data is stored here.
video and blend file demo.
http://www.graphicall.org/ftp/ideasman42/reinstance.ogvhttp://www.graphicall.org/ftp/ideasman42/reinstance_demo.blend
while making a demo of using python to control bones found some more problems.
also added channelNames attribute to BL_ActionActuator to get a list of valid channels to use.
demo: http://www.graphicall.org/ftp/ideasman42/armature_python.blend
its still not that useful since theres not way to know rest bone locations yet but better then nothing.
* extract_pose_from_pose only checked one of the list items for NULL when looping over them yet its possible they are different sizes.
* game_free_pose needed to be used rather then MEM_freeN, channels would never be freed leaking memory.
* setChannel() would make a new pose that wasnt aligned with the existing pose, the lists are assumed aligned so when extracting the channels its unlikely this was ever useful.
* Added getChannel() - returns pose loc/size/quat
* Added option args for setChannel(channel, matrix) or setChannel(channel, loc, size, quat)
* Removed modules Expression and CValue, neither were ever available.
* Added GameLogic.EvalExpression(exp) from the Expression module, evaluates an expression like the expression controller (not sure if this is really that useful since python is far more advanced).
* resetting the original blend file path didint work (own fault == -> =)
* Py3.x PyModule_Create didnt allow importing since it didn't add to sys.modules,
Looks like they want us to use init-tab array, but this doesn't suit us since
it needs to be setup before python is initialized.
* Documented GameLogic.globalDict
Internal texts file on disk is not used it seems python warnings dont support this (even though exceptions do).
The most common cause of this is passing a float as an argument to a method that took an int.
get around this by setting __file__ in the namespace to the script name before executing the script, the file lines are not found but at least the output is not weird and confusing.
Added read only 'mode' attribute to the python controller so there is a way to tell if its executing a module or a script. Updated docs to better explain execution methods.
- Deprecation warnings for using attribute access
- Added dictionary functions to KX_GameObject and ListValue
ob.get(key, default=None)
ob.has_key(key)
ob.has_key is important since there was no way to do something like hasattr(ob, "attr") which can be replaced by ob.has_key("attr") - (both still work of course).
ob.get is just useful in many cases where you want a property if it exists but can fallback to a default.
- CListValue::FindValue was adding a reference but the ~3 places it was used were releasing the reference. added a FindValue that accepts a const char* type to avoid converting python strings to STR_String.
bug reported by blenderage on blenderartist (found other bugs too).
- "All Hat Events" didnt work.
- Multiple hats didnt work
- use a menu with direction names rather then have the user guess. disallow zero as a direction.
- Allow up to 4 hats (was 2).
- Python api was clamping the axis to 2, maximum is currently JOYAXIS_MAX - 16
- New python attributes hatValues and hatSingle, match axis functions.
- Use SDL Axis events to fill in the axis and hat array rather then filling in every axis with SDL_JoystickGetAxis for each axis event.
- Fixed some deprecation warnings in documentation.
- Added more conversions to script.
- Added more attributes to script todo list.
- Print out name of text buffer when encountering an error in batch mode.
- Refactor: Simplified attribute map.
- Added notImplemented function to print warnings for missing conversions. References documentation.
