ad37e34fbacdfa6a59f71dbe8605043bd40bc30a
[blender.git] / source / gameengine / PyDoc / API_intro.py
1 # This is not a real module, it's simply an introductory text.
2
3 """
4 The Blender Game Engine Python API Reference
5 ============================================
6
7         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.
8
9         Top Module:
10         -----------
11
12                 - L{GameLogic}
13                 - L{GameKeys}
14                 - L{GameTypes}
15                 - L{Mathutils}
16                 - L{Geometry}
17                 - L{BGL}
18         
19         Undocumented modules:
20         ---------------------
21                 - VideoTexture
22                 - CValue
23                 - Expression
24                 - PhysicsConstraints
25
26
27 Introduction:
28 =============
29
30         This reference documents the Blender Python API, a growing collection of
31         Python modules (libraries) that give access to part of the program's internal
32         data and functions.
33         
34         Through scripting Blender can be extended in real-time via
35         U{Python <www.python.org>}, an impressive high level, multi-paradigm, open
36         source language.  Newcomers are recommended to start with the tutorial that
37         comes with it.
38
39         This opens many interesting possibilities not available with logic bricks.
40
41         Game Engine API Stability:
42         --------------------------
43
44         When writing python scripts there are a number of situations you should avoid to prevent crashes or unstable behavior.
45         While the API tries to prevent problems there are some situations where error checking would be too time consuming.
46         
47         Known cases:
48                 - Memory Limits.
49
50                                 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.
51                                 
52                 - Accessing any data that has been freed.
53
54                                 For instance accessing a KX_GameObject after its End Object actuator runs.
55                                 This will cause a SystemError, however for L{KX_MeshProxy}, L{KX_VertexProxy} and L{KX_VertexProxy} it will crash the blender game engine.
56                                 
57                                 See: L{GameTypes.PyObjectPlus.invalid} which many types inherit.
58
59                 - Mixing L{KX_GameObject} between scenes.
60
61                                 For instance tracking/parenting an L{KX_GameObject} object to an object from other scene.
62
63         External Modules:
64         -----------------
65         
66         Since 2.49 support for importing modules has been added.
67
68         This allows you to import any blender textblock with a .py extension.
69         
70         External python scripts may be imported as modules when the script is in the same directory as the blend file.
71         
72         The current blend files path is included in the sys.path for loading modules.
73         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.
74         
75         A note to newbie script writers:
76         --------------------------------
77
78         Interpreted languages are known to be much slower than compiled code, but for
79         many applications the difference is negligible or acceptable.  Also, with
80         profiling (or even simple direct timing with L{Blender.sys.time<Sys.time>}) to
81         identify slow areas and well thought optimizations, the speed can be
82         I{considerably} improved in many cases.  Try some of the best BPython scripts
83         to get an idea of what can be done, you may be surprised.
84
85 @author: The Blender Python Team
86 @requires: Blender 2.49 or newer.
87 @version: 2.49
88 @see: U{www.blender.org<http://www.blender.org>}: documentation and forum
89 @see: U{blenderartists.org<http://blenderartists.org>}: user forum
90 @see: U{projects.blender.org<http://projects.blender.org>}
91 @see: U{www.python.org<http://www.python.org>}
92 @see: U{www.python.org/doc<http://www.python.org/doc>}
93 @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.
94
95 @note: the official version of this reference guide is only updated for each
96         new Blender release.  But you can build the current SVN
97         version yourself: install epydoc, grab all files in the
98         source/gameengine/PyDoc/ folder of Blender's SVN and use the
99         epy_docgen.sh script also found there to generate the html docs.
100         Naturally you will also need a recent Blender binary to try the new
101         features.  If you prefer not to compile it yourself, there is a testing
102         builds forum at U{blender.org<http://www.blender.org>}.
103 """