Scripts:
[blender.git] / source / blender / python / api2_2x / doc / API_intro.py
1 # This is not a real module, it's simply an introductory text.
2
3 """
4 The Blender Python API Reference
5 ================================
6
7  Top Module:
8  -----------
9
10   - L{Blender} (*)
11
12  Submodules:
13  -----------
14   - L{Armature}
15      - L{Bone}
16      - L{NLA}
17   - L{BGL}
18   - L{Camera} (*)
19   - L{Curve}
20   - L{Draw} (*)
21   - L{Effect}
22   - L{Image} (*)
23   - L{Ipo} (*)
24   - L{Lamp} (*)
25   - L{Lattice}
26   - L{Library}
27   - L{Material} (*)
28   - L{Mathutils}
29   - L{Metaball} (*)
30   - L{NMesh}
31   - L{Noise}
32   - L{Object} (*)
33   - L{Registry}
34   - L{Scene} (*)
35      - L{Radio} (new)
36      - L{Render}
37   - L{Text}
38   - L{Texture}
39   - L{Types}
40   - L{Window} (* important: L{Window.EditMode})
41   - L{World} (*)
42   - L{sys<Sys>} (*)
43
44  (*) - marks updated.
45
46 Introduction:
47 =============
48
49  This reference documents the Blender Python API, a growing collection of
50  Python modules (libraries) that give access to part of the program's internal
51  data and functions.
52  
53  Through scripting Blender can be extended in realtime via
54  U{Python <www.python.org>}, an impressive high level, multi-paradigm, open
55  source language.  Newcomers are recommended to start with the tutorial that
56  comes with it.
57
58  This opens many interesting possibilities, ranging from automating repetitive
59  tasks to adding new functionality to the program: procedural models,
60  importers and exporters, even complex applications and so on.  Blender itself
61  comes with some scripts, but many others can be found in the Scripts & Plugins
62  sections and forum posts at the Blender-related sites listed below.
63
64 Scripting and Blender:
65 ======================
66
67 There are four basic ways to execute scripts in Blender:
68
69  1. They can be loaded or typed as text files in the Text Editor window, then
70  executed with ALT+P.
71  2. Via command line: 'blender -P <scriptname>' will start Blender and executed
72  the given script.  <scriptname> can be a filename in the user's file system or
73  the name of a text saved in a .blend Blender file:
74  'blender myfile.blend -P textname'.
75  3. Properly registered scripts can be selected directly from the program's
76  menus.
77  4. Scriptlinks: these are also loaded or typed in the Text Editor window and
78  can be linked to objects, materials or scenes using the Scriptlink buttons
79  tab.  Script links get executed automatically when their events (ONLOAD,
80  REDRAW, FRAMECHANGED) are triggered.  Normal scripts can create (L{Text}) and
81  link other scripts to objects and events, see L{Object.Object.addScriptLink},
82  for example.
83
84 Registering scripts:
85 --------------------
86  To be registered a script needs two things:
87    - be either in the default scripts dir or in the user defined scripts path
88      (see Info window, paths tab);
89    - have a proper header.
90
91  Try 'blender -d' to know where your default dir for scripts is, it will
92  inform either the dir or the file with that info already parsed, which is
93  in the same dir of the scripts folder.
94
95  The header should be like this one (all double and single apostrophes below
96  are required)::
97   #!BPY
98   \"\"\"
99   Name: 'Script Name'
100   Blender: 233
101   Group: 'Export'
102   Submenu: 'All' all
103   Submenu: 'Selected' sel
104   Submenu: 'Configure (gui)' gui
105   Tooltip: 'Export to some format.'
106   \"\"\"
107
108  where:
109   - B{Name} is the string that will appear in the menu;
110   - B{Blender} is the minimum program version required to run the script;
111   - B{Group} defines where the script will be put, see all groups in the
112     Scripts Window's header, menu "Scripts";
113   - B{Submenu} adds optional submenus for further control;
114   - B{Tooltip} is the (short) tooltip string for the menu entry.
115
116  Submenu lines are not required, use them if you want to provide extra
117  options.  To see which submenu the user chose, check the "__script__"
118  dictionary in your code: __script__['arg'] has the defined keyword (the word
119  after the submenu string name: all, sel or gui in the example above) of the
120  chosen submenu.  For example, if the user clicked on submenu 'Selected' above,
121  __script__['arg'] will be "sel".
122
123  If your script requires extra data or configuration files, there is a special
124  folder where they can be saved: see 'datadir' in L{Blender.Get}.
125
126 Interaction with users:
127 -----------------------
128
129  Scripts can:
130   - simply run and exit;
131   - grab the main input event queue and process (or pass to Blender) selected
132     keyboard, mouse, redraw events;
133   - pop messages, menus and small number and text input boxes;
134   - draw graphical user interfaces (guis) with OpenGL calls and native
135     program buttons, which stay there accepting user input like any other
136     Blender window until the user closes them;
137   - make changes to the 3D View (set visible layer(s), view point, etc);
138   - use external Python libraries, if available.
139
140  You can read the documentation for the L{Window}, L{Draw} and L{BGL} modules
141  for more information and also check Python's site for external modules that
142  might be useful to you.  Note though that any imported module will become a
143  requirement of your script, since Blender itself does not bundle external
144  modules.
145
146 Command line mode:
147 ------------------
148
149  Python was embedded in Blender, so to access bpython modules you need to
150  run scripts from the program itself: you can't import the Blender module
151  into an external Python interpreter.  But with "OnLoad" script links, the
152  "-b" background mode and additions like the "-P" command line switch,
153  L{Blender.Save}, L{Blender.Load}, L{Blender.Quit} and the L{Library} module,
154  for many tasks it's possible to control Blender via some automated process
155  using scripts.
156
157 Demo mode:
158 ----------
159
160  Blender has a demo mode, where once started it can work without user
161  intervention, "showing itself off".  Demos can render stills and animations,
162  play rendered or realtime animations, calculate radiosity simulations and
163  do many other nifty things.  If you want to turn a .blend file into a demo,
164  write a script to run the show and link it as a scene "OnLoad" scriptlink.
165  The demo will then be played automatically whenever this .blend file is
166  opened, B{unless Blender was started with the "-y" parameter}.
167
168 The Game Engine API:
169 --------------------
170
171  Blender has a game engine for users to create and play 3d games.  This
172  engine lets programmers add scripts to improve game AI, control, etc, making
173  more complex interaction and tricks possible.  The game engine API is
174  separate from the Blender Python API this document references and you can
175  find its own ref doc in the docs section of the main sites below.
176
177 A note to newbie script writers:
178 --------------------------------
179
180  Interpreted languages are known to be much slower than compiled code, but for
181  many applications the difference is negligible or acceptable.  Also, with
182  profiling to identify slow areas and well thought optimizations, the speed
183  can be I{considerably} improved in many cases.  Try some of the best bpython
184  scripts to get an idea of what can be done, you may be surprised.
185
186 @author: The Blender Python Team
187 @requires: Blender 2.34 or newer.
188 @version: 2.34
189 @see: U{www.blender3d.org<http://www.blender3d.org>}: main site
190 @see: U{www.blender.org<http://www.blender.org>}: documentation and forum
191 @see: U{www.elysiun.com<http://www.elysiun.com>}: user forum
192 @see: U{projects.blender.org<http://projects.blender.org>}
193 @see: U{www.python.org<http://www.python.org>}
194 @see: U{www.python.org/doc<http://www.python.org/doc>}
195 @note: this documentation was generated by epydoc, which can output html and
196    pdf.  For pdf it requires a working LaTeX environment.
197 """