From 73904597e9c822fde9ec633db650c9783cf43847 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Wed, 20 May 2009 01:11:56 +0000 Subject: - 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 --- source/gameengine/PyDoc/API_intro.py | 103 ++++++++++++++++++++++++++++++++++ source/gameengine/PyDoc/GameLogic.py | 30 +++------- source/gameengine/PyDoc/epy_docgen.sh | 9 ++- 3 files changed, 118 insertions(+), 24 deletions(-) create mode 100644 source/gameengine/PyDoc/API_intro.py (limited to 'source/gameengine/PyDoc') diff --git a/source/gameengine/PyDoc/API_intro.py b/source/gameengine/PyDoc/API_intro.py new file mode 100644 index 00000000000..ad37e34fbac --- /dev/null +++ b/source/gameengine/PyDoc/API_intro.py @@ -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} 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 }, 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}) 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. + +@author: The Blender Python Team +@requires: Blender 2.49 or newer. +@version: 2.49 +@see: U{www.blender.org}: documentation and forum +@see: U{blenderartists.org}: user forum +@see: U{projects.blender.org} +@see: U{www.python.org} +@see: U{www.python.org/doc} +@see: U{Blending into Python}: User contributed documentation, featuring a blender/python cookbook with many examples. + +@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}. +""" diff --git a/source/gameengine/PyDoc/GameLogic.py b/source/gameengine/PyDoc/GameLogic.py index 28fd95611bc..1bc406daf09 100644 --- a/source/gameengine/PyDoc/GameLogic.py +++ b/source/gameengine/PyDoc/GameLogic.py @@ -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 - - All the other modules are accessible through the methods in GameLogic. - See U{release notes} for updates, changes and new functionality in the Game Engine Python API. + Module to access logic functions, imported automatically into the python controllers namespace. 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 @@ Documentation for the GameLogic Module. # +---------------------+ +--------+ # | 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} @@ -56,7 +42,7 @@ Documentation for the GameLogic Module. # +--------+ +-------------------------+ # + Python +--+ Actuator "actuatorname" | # +--------+ +-------------------------+ - actuator = co.getActuator("actuatorname") + actuator = co.actuators["actuatorname"] # Activate an actuator controller.activate(actuator) @@ -96,7 +82,7 @@ Documentation for the GameLogic Module. 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. diff --git a/source/gameengine/PyDoc/epy_docgen.sh b/source/gameengine/PyDoc/epy_docgen.sh index 0872d2abbbd..dd30256f42f 100755 --- a/source/gameengine/PyDoc/epy_docgen.sh +++ b/source/gameengine/PyDoc/epy_docgen.sh @@ -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 + -- cgit v1.2.3