[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [20281] trunk/blender/source/gameengine/ PyDoc: - Added an intro page for the BGE docs rather then using GameLogic
Campbell Barton
ideasman42 at gmail.com
Wed May 20 03:12:01 CEST 2009
Revision: 20281
http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=20281
Author: campbellbarton
Date: 2009-05-20 03:11:56 +0200 (Wed, 20 May 2009)
Log Message:
-----------
- Added an intro page for the BGE docs rather then using GameLogic
- Added notes on BGE stability and modules
- updated some examples to new api syntax
- include BGL Mathutils and Geometry modules in docs
Modified Paths:
--------------
trunk/blender/source/gameengine/PyDoc/GameLogic.py
trunk/blender/source/gameengine/PyDoc/epy_docgen.sh
Added Paths:
-----------
trunk/blender/source/gameengine/PyDoc/API_intro.py
Added: trunk/blender/source/gameengine/PyDoc/API_intro.py
===================================================================
--- trunk/blender/source/gameengine/PyDoc/API_intro.py (rev 0)
+++ trunk/blender/source/gameengine/PyDoc/API_intro.py 2009-05-20 01:11:56 UTC (rev 20281)
@@ -0,0 +1,103 @@
+# This is not a real module, it's simply an introductory text.
+
+"""
+The Blender Game Engine Python API Reference
+============================================
+
+ See U{release notes<http://wiki.blender.org/index.php/Dev:Ref/Release_Notes/2.49/Game_Engine>} for updates, changes and new functionality in the Game Engine Python API.
+
+ Top Module:
+ -----------
+
+ - L{GameLogic}
+ - L{GameKeys}
+ - L{GameTypes}
+ - L{Mathutils}
+ - L{Geometry}
+ - L{BGL}
+
+ Undocumented modules:
+ ---------------------
+ - VideoTexture
+ - CValue
+ - Expression
+ - PhysicsConstraints
+
+
+Introduction:
+=============
+
+ This reference documents the Blender Python API, a growing collection of
+ Python modules (libraries) that give access to part of the program's internal
+ data and functions.
+
+ Through scripting Blender can be extended in real-time via
+ U{Python <www.python.org>}, an impressive high level, multi-paradigm, open
+ source language. Newcomers are recommended to start with the tutorial that
+ comes with it.
+
+ This opens many interesting possibilities not available with logic bricks.
+
+ Game Engine API Stability:
+ --------------------------
+
+ When writing python scripts there are a number of situations you should avoid to prevent crashes or unstable behavior.
+ While the API tries to prevent problems there are some situations where error checking would be too time consuming.
+
+ Known cases:
+ - Memory Limits.
+
+ There is nothing stopping you from filling a list or making a string so big that that causes blender to run out of memory, in this case python should rasie a MemoryError, but its likely blender will crash before this point.
+
+ - Accessing any data that has been freed.
+
+ For instance accessing a KX_GameObject after its End Object actuator runs.
+ This will cause a SystemError, however for L{KX_MeshProxy}, L{KX_VertexProxy} and L{KX_VertexProxy} it will crash the blender game engine.
+
+ See: L{GameTypes.PyObjectPlus.invalid} which many types inherit.
+
+ - Mixing L{KX_GameObject} between scenes.
+
+ For instance tracking/parenting an L{KX_GameObject} object to an object from other scene.
+
+ External Modules:
+ -----------------
+
+ Since 2.49 support for importing modules has been added.
+
+ This allows you to import any blender textblock with a .py extension.
+
+ External python scripts may be imported as modules when the script is in the same directory as the blend file.
+
+ The current blend files path is included in the sys.path for loading modules.
+ All linked libraries will also be included so you can be sure when linking in assets from another blend file the scripts will load too.
+
+ A note to newbie script writers:
+ --------------------------------
+
+ Interpreted languages are known to be much slower than compiled code, but for
+ many applications the difference is negligible or acceptable. Also, with
+ profiling (or even simple direct timing with L{Blender.sys.time<Sys.time>}) to
+ identify slow areas and well thought optimizations, the speed can be
+ I{considerably} improved in many cases. Try some of the best BPython scripts
+ to get an idea of what can be done, you may be surprised.
+
+ at author: The Blender Python Team
+ at requires: Blender 2.49 or newer.
+ at version: 2.49
+ at see: U{www.blender.org<http://www.blender.org>}: documentation and forum
+ at see: U{blenderartists.org<http://blenderartists.org>}: user forum
+ at see: U{projects.blender.org<http://projects.blender.org>}
+ at see: U{www.python.org<http://www.python.org>}
+ at see: U{www.python.org/doc<http://www.python.org/doc>}
+ at see: U{Blending into Python<en.wikibooks.org/wiki/Blender_3D:_Blending_Into_Python>}: User contributed documentation, featuring a blender/python cookbook with many examples.
+
+ at note: the official version of this reference guide is only updated for each
+ new Blender release. But you can build the current SVN
+ version yourself: install epydoc, grab all files in the
+ source/gameengine/PyDoc/ folder of Blender's SVN and use the
+ epy_docgen.sh script also found there to generate the html docs.
+ Naturally you will also need a recent Blender binary to try the new
+ features. If you prefer not to compile it yourself, there is a testing
+ builds forum at U{blender.org<http://www.blender.org>}.
+"""
Modified: trunk/blender/source/gameengine/PyDoc/GameLogic.py
===================================================================
--- trunk/blender/source/gameengine/PyDoc/GameLogic.py 2009-05-19 18:30:33 UTC (rev 20280)
+++ trunk/blender/source/gameengine/PyDoc/GameLogic.py 2009-05-20 01:11:56 UTC (rev 20281)
@@ -2,29 +2,15 @@
"""
Documentation for the GameLogic Module.
=======================================
-
- Modules available in the game engine:
- - GameLogic
- - L{GameKeys}
- - L{Rasterizer}
- - L{GameTypes}
- Undocumented modules:
- - VideoTexture
- - CValue
- - Expression
- - PhysicsConstraints
+ Module to access logic functions, imported automatically into the python controllers namespace.
- All the other modules are accessible through the methods in GameLogic.
-
- See U{release notes<http://wiki.blender.org/index.php/Dev:Ref/Release_Notes/2.49/Game_Engine>} for updates, changes and new functionality in the Game Engine Python API.
-
Examples::
# To get the controller thats running this python script:
- co = GameLogic.getCurrentController() # GameLogic is automatically imported
+ cont = GameLogic.getCurrentController() # GameLogic is automatically imported
# To get the game object this controller is on:
- obj = co.getOwner()
+ obj = cont.owner
L{KX_GameObject} and L{KX_Camera} or L{KX_LightObject} methods are
available depending on the type of object::
# To get a sensor linked to this controller.
@@ -32,10 +18,10 @@
# +---------------------+ +--------+
# | Sensor "sensorname" +--+ Python +
# +---------------------+ +--------+
- sens = co.getSensor("sensorname")
+ sens = cont.sensors["sensorname"]
- # To get a list of all sensors:
- sensors = co.getSensors()
+ # To get a sequence of all sensors:
+ sensors = co.sensors
See the sensor's reference for available methods:
- L{DelaySensor<GameTypes.SCA_DelaySensor>}
@@ -56,7 +42,7 @@
# +--------+ +-------------------------+
# + Python +--+ Actuator "actuatorname" |
# +--------+ +-------------------------+
- actuator = co.getActuator("actuatorname")
+ actuator = co.actuators["actuatorname"]
# Activate an actuator
controller.activate(actuator)
@@ -96,7 +82,7 @@
cam = scene.active_camera
Matricies as used by the game engine are B{row major}::
- matrix[row][col] = blah
+ matrix[row][col] = float
L{KX_Camera} has some examples using matricies.
Modified: trunk/blender/source/gameengine/PyDoc/epy_docgen.sh
===================================================================
--- trunk/blender/source/gameengine/PyDoc/epy_docgen.sh 2009-05-19 18:30:33 UTC (rev 20280)
+++ trunk/blender/source/gameengine/PyDoc/epy_docgen.sh 2009-05-20 01:11:56 UTC (rev 20281)
@@ -7,5 +7,10 @@
# set posix locale so regex works properly for [A-Z]*.py
LC_ALL=POSIX
-epydoc --debug -v -o BPY_GE --url "http://www.blender.org" --top GameLogic \
- --name "Blender GameEngine" --no-private --no-sourcecode --inheritance=included *.py
+epydoc --debug -v -o BPY_GE --url "http://www.blender.org" --top API_intro \
+ --name "Blender GameEngine" --no-private --no-sourcecode --inheritance=included \
+ *.py \
+ ../../../source/blender/python/api2_2x/doc/BGL.py \
+ ../../../source/blender/python/api2_2x/doc/Mathutils.py \
+ ../../../source/blender/python/api2_2x/doc/Geometry.py
+
More information about the Bf-blender-cvs
mailing list