2.50:

svn merge https://svn.blender.org/svnroot/bf-blender/trunk/blender -r19820:HEAD

Notes:
* Game and sequencer RNA, and sequencer header are now out of date
  a bit after changes in trunk.
* I didn't know how to port these bugfixes, most likely they are
  not needed anymore.
  * Fix "duplicate strip" always increase the user count for ipo.
  * IPO pinning on sequencer strips was lost during Undo.

1 files changed, 103 insertions, 0 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>}.
+"""