- 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

3 files changed, 118 insertions, 24 deletions

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<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.
+
+@author: The Blender Python Team
+@requires: Blender 2.49 or newer.
+@version: 2.49
+@see: U{www.blender.org<http://www.blender.org>}: documentation and forum
+@see: U{blenderartists.org<http://blenderartists.org>}: user forum
+@see: U{projects.blender.org<http://projects.blender.org>}
+@see: U{www.python.org<http://www.python.org>}
+@see: U{www.python.org/doc<http://www.python.org/doc>}
+@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.
+
+@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>}.
+"""
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<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.
+	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<GameTypes.SCA_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
+