GODOT IS OPEN SOURCE

1 files changed, 984 insertions, 0 deletions

diff --git a/doc/squirrel.lyx b/doc/squirrel.lyx
new file mode 100644
index 000000000..05270c1b8
--- /dev/null
+++ b/doc/squirrel.lyx
@@ -0,0 +1,984 @@
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass article
+\use_default_options true
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding auto
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\use_hyperref false
+\papersize default
+\use_geometry false
+\use_amsmath 1
+\use_esint 1
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 1
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Title
+Squirrel Usage in Godot
+\end_layout
+
+\begin_layout Section
+Introduction
+\end_layout
+
+\begin_layout Standard
+Squirrel is a nice scripting language.
+ It's sort of a mix between Lua, Java and JavaScript and ends up being easy
+ to learn for most programmers.
+ It has more language features than GDScript but it's also slower, more
+ limited and not as well integrated.
+ This guide will explain how Squirrel is integrated to Godot and all the
+ quirks that are needed to know in order to use it properly.
+\end_layout
+
+\begin_layout Section
+Enabling Squirrel
+\end_layout
+
+\begin_layout Standard
+Squirrel may not be enabled by default in a Godot build.
+ To enable it, execute SCons with the following parameters:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+shell$ scons squirrel=yes <target_binary>
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section
+Documentation
+\end_layout
+
+\begin_layout Standard
+Godot utilizes Squirrel 2.2.
+ Documentation can be found at: 
+\begin_inset CommandInset href
+LatexCommand href
+target "http://squirrel-lang.org/#documentation"
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section
+Class Files
+\end_layout
+
+\begin_layout Standard
+Unless writing a library, Godot expects a class for scripting an object.
+ Since a Squirrel source file can contain many classes, the main class must
+ be returned.
+ The following is an example of extending a button:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+class MyButton extends Button {
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+	constructor() {
+\end_layout
+
+\begin_layout Plain Layout
+
+		// ALWAYS call parent constructor
+\end_layout
+
+\begin_layout Plain Layout
+
+		Button.constructor() 
+\end_layout
+
+\begin_layout Plain Layout
+
+	}
+\end_layout
+
+\begin_layout Plain Layout
+
+}
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+return MyButton // main class returned
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Additionally, classes are all copied to the root table, so all class names
+ in scripts must be different if they are attempted to be loaded simultaneously.
+ The same can be said for any other globals declared in the script.
+ 
+\end_layout
+
+\begin_layout Standard
+Finally, squirrel scripts must be saved with the .nut or .sq extensions (both
+ are recognized).
+\end_layout
+
+\begin_layout Section
+Including Other Scripts
+\end_layout
+
+\begin_layout Standard
+Other scripts can be included with the include() directive.
+ Full and relative paths are supported.
+ When included, the classes and globals are moved to the root table, so
+ they become immediately available.
+ Constants, however, are only inlined in the current class on load, so Squirrel
+ does not make them available.
+ Example of including scripts:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+include("my_button.nut") # // relative to current script, expected to be
+ in the same path
+\end_layout
+
+\begin_layout Plain Layout
+
+include("res://buttons/my_button.nut") // using resource path
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section
+Built-In Types
+\end_layout
+
+\begin_layout Standard
+There are some small differences between the Built-In types in Godot and
+ the ones in Squirrel, so the documentation will not match.
+ The differences are documented here.
+\end_layout
+
+\begin_layout Standard
+An attempt will be made to document everything here,but if in doubt about
+ bindings on built-in types, you can always take a loot at the bindings
+ source file in script/squirrel/sq_bind_types.cpp.
+\end_layout
+
+\begin_layout Standard
+Built-In Types in Squirrel are passed by reference (unlike by value like
+ in GD).
+ They also don't need to be freed.
+\end_layout
+
+\begin_layout Subsection
+AABB
+\end_layout
+
+\begin_layout Standard
+\begin_inset Quotes eld
+\end_inset
+
+pos
+\begin_inset Quotes erd
+\end_inset
+
+, 
+\begin_inset Quotes eld
+\end_inset
+
+size
+\begin_inset Quotes erd
+\end_inset
+
+ and 
+\begin_inset Quotes eld
+\end_inset
+
+end
+\begin_inset Quotes erd
+\end_inset
+
+ are not available Use get_pos()/set_pos and get_size()/set_size().
+\end_layout
+
+\begin_layout Subsection
+InputEvent
+\end_layout
+
+\begin_layout Standard
+InputEvent is a single datatype and contains everything.
+ Use only the fields meant for the event type:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+//for mouse motion and button
+\end_layout
+
+\begin_layout Plain Layout
+
+int mouse_x
+\end_layout
+
+\begin_layout Plain Layout
+
+int mouse_y
+\end_layout
+
+\begin_layout Plain Layout
+
+int mouse_button_mask
+\end_layout
+
+\begin_layout Plain Layout
+
+int mouse_global_x
+\end_layout
+
+\begin_layout Plain Layout
+
+int mouse_global_y
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+//for mouse button
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+int mouse_button_index
+\end_layout
+
+\begin_layout Plain Layout
+
+bool mouse_button_pressed
+\end_layout
+
+\begin_layout Plain Layout
+
+bool mouse_button_doubleclick
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+//for mouse motion
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+int mouse_motion_x
+\end_layout
+
+\begin_layout Plain Layout
+
+int mouse_motion_y
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+//for keyboard
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+int key_scancode
+\end_layout
+
+\begin_layout Plain Layout
+
+int key_unicode
+\end_layout
+
+\begin_layout Plain Layout
+
+bool key_pressed
+\end_layout
+
+\begin_layout Plain Layout
+
+bool key_echo
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+//for keyboard and mouse
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+bool mod_alt
+\end_layout
+
+\begin_layout Plain Layout
+
+bool mod_shift
+\end_layout
+
+\begin_layout Plain Layout
+
+bool mod_meta
+\end_layout
+
+\begin_layout Plain Layout
+
+bool mod_control
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+//joy button
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+int joy_button_index
+\end_layout
+
+\begin_layout Plain Layout
+
+bool joy_button_pressed
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+//joy axis
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+int joy_axis
+\end_layout
+
+\begin_layout Plain Layout
+
+float joy_axis_value
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+//screen drag and touch
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+int screen_index
+\end_layout
+
+\begin_layout Plain Layout
+
+int screen_x
+\end_layout
+
+\begin_layout Plain Layout
+
+int screen_y
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+//screen touch
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+int screen_index
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+//action
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+int action_id
+\end_layout
+
+\begin_layout Plain Layout
+
+bool action_pressed
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Matrix3
+\end_layout
+
+\begin_layout Standard
+x,y,z member vectors are not available.
+ Use get_row() and set_row() instead.
+ Individual float values of the matrix are available as swizzle masks such
+ as xxy, xyz, zzx, etc.
+\end_layout
+
+\begin_layout Standard
+Additional in-place versions of some functions are available: transpose(),
+ invert(), rotate(), scale(), orthonormalize().
+\end_layout
+
+\begin_layout Subsection
+Transform
+\end_layout
+
+\begin_layout Standard
+\begin_inset Quotes eld
+\end_inset
+
+basis
+\begin_inset Quotes erd
+\end_inset
+
+ and 
+\begin_inset Quotes eld
+\end_inset
+
+origin
+\begin_inset Quotes erd
+\end_inset
+
+ members are not available.
+ Use get_basis()/set_basis() and get_origin()/set_origin() instead.
+ Additional in-place versions of some functions are available: invert(),
+ affine_invert(), orthonormalize(), rotate(), translate(), scale().
+\end_layout
+
+\begin_layout Standard
+Vector2
+\end_layout
+
+\begin_layout Subsection
+Plane
+\end_layout
+
+\begin_layout Standard
+\begin_inset Quotes eld
+\end_inset
+
+normal
+\begin_inset Quotes erd
+\end_inset
+
+ member vector is not available.
+ Use get_normal(), set_normal() instead.
+\end_layout
+
+\begin_layout Subsection
+Rect2
+\end_layout
+
+\begin_layout Standard
+\begin_inset Quotes eld
+\end_inset
+
+pos
+\begin_inset Quotes erd
+\end_inset
+
+, 
+\begin_inset Quotes eld
+\end_inset
+
+size
+\begin_inset Quotes erd
+\end_inset
+
+ and 
+\begin_inset Quotes eld
+\end_inset
+
+end
+\begin_inset Quotes erd
+\end_inset
+
+ are not available Use get_pos()/set_pos and get_size()/set_size().
+\end_layout
+
+\begin_layout Subsection
+Native Arrays
+\end_layout
+
+\begin_layout Standard
+Native arrays such as RawArray, IntArray,StringArray, etc are not supported.
+ Use regular squirrel arrays instead, since conversion to/from them will
+ happen automatically.
+\end_layout
+
+\begin_layout Subsection
+Math Functions
+\end_layout
+
+\begin_layout Standard
+Math functions are inside the Math namespace in Squirrel.
+ For example Math.sin , Math.PI, Math.atan2().
+\end_layout
+
+\begin_layout Subsection
+Native Types
+\end_layout
+
+\begin_layout Standard
+Array, Dictionary and NodePath are not available.
+ Use a native array, table and string respectively.
+\end_layout
+
+\begin_layout Section
+_get , _set
+\end_layout
+
+\begin_layout Standard
+_get and _set are reserved in Squirrel, for overriding Godot Object property
+ getter/setter, use _get_property and _set_property.
+\end_layout
+
+\begin_layout Section
+Member Export
+\end_layout
+
+\begin_layout Standard
+Simple exporting of members (so far only integer, floating point and string
+ are supported) is supported by the @export extension.
+ It is used like this:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+class MyButton extends Button {
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+	aprop=1 // @export
+\end_layout
+
+\begin_layout Plain Layout
+
+	bprop=2.0 // @export
+\end_layout
+
+\begin_layout Plain Layout
+
+	cprop="3" // @export
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+	//these will be available to the property editor, and will be loaded/saved
+ with the scene.
+\end_layout
+
+\begin_layout Plain Layout
+
+}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section
+Always Enabled Scripts
+\end_layout
+
+\begin_layout Standard
+Scripts are not enabled in the editor by default.
+ To enable a script always, add an @always_enabled comment.
+ Example:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+//@always_enabled
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+class MyButton extends Button {
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+...
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section
+Threads
+\end_layout
+
+\begin_layout Standard
+Thread support in Squirrel is very poor.
+ This is because of the stack-based nature of the language implementation.
+ Since godot can run in multiple threads, it will forcibily lock the whole
+ VM when accessed from multiple threads, which will result in degraded performan
+ce.
+ Creating user threads in Squirrel is definitely not recomended, as it may
+ completely lock the main thread.
+\end_layout
+
+\begin_layout Section
+References
+\end_layout
+
+\begin_layout Standard
+Godot has a built-in reference counted type used in conjunction with a template
+ (objects that inherit the 
+\begin_inset Quotes eld
+\end_inset
+
+Reference
+\begin_inset Quotes erd
+\end_inset
+
+ class).
+ Since Squirrel also uses reference counting, it becomes impossible for
+ such types in godot to contain a script, because it would result in an
+ un-breakable reference cycle.
+ To avoid this, a Ref() class was created in Squirrel.
+ 
+\end_layout
+
+\begin_layout Standard
+When calling Godot API functions, returned references are wrapped inside
+ Ref() transparently, but the problem arises when creating a Reference-derived
+ object from the code.
+ In such cases, the reference must be wrapped manually like this:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+local f = Ref( File() )
+\end_layout
+
+\begin_layout Plain Layout
+
+local err = f.open("hello.txt",File.READ)
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Anything not a reference that inherits from Object can be freed manually
+ by calling .free(), just like in GDScript.
+ Object classes are in itself weak references to engine objects, and their
+ validity can be checked by calling the 
+\begin_inset Quotes eld
+\end_inset
+
+has_instance()
+\begin_inset Quotes erd
+\end_inset
+
+ built-in method.
+\end_layout
+
+\begin_layout Section
+Unicode
+\end_layout
+
+\begin_layout Standard
+Squirrel source code is supposed to support Unicode, but the implementation
+ is very broken (Squirrel attempts to use 16 bit chars no matter what, making
+ it incompatible when the host OS is 32 bit, like Linux).
+ Squirrel source code is parsed as UTF-8, and strings also contain UTF-8.
+ Wide char access in strings is not supported.
+\end_layout
+
+\begin_layout Section
+Debugging
+\end_layout
+
+\begin_layout Standard
+Squirrel is well integrated into the Godot debugger.
+ To run the project in debug mode, execute the godot binary with the -debug
+ argument.
+ Godot will break on squirrel errors and allow the programmer to debug.
+\end_layout
+
+\begin_layout Section
+Utility Functions
+\end_layout
+
+\begin_layout Standard
+There are a few squirrel-only utility functions available:
+\end_layout
+
+\begin_layout Subsection
+print(value[,value])
+\end_layout
+
+\begin_layout Standard
+Print stuff to stdout.
+\end_layout
+
+\begin_layout Subsection
+dofile(path)
+\end_layout
+
+\begin_layout Standard
+Execute a squirrel script file and return whatever the file returns.
+ Not recommended to use in production because it can't be optimized.
+\end_layout
+
+\begin_layout Subsection
+nativeref(var)
+\end_layout
+
+\begin_layout Standard
+Convert any squirrel type to an engine type.
+ When this type returns to squirrel, it's converted back.
+ This is useful to add to Godot callbacks to ensure that the datatype is
+ not converted.
+\end_layout
+
+\begin_layout Subsection
+unicode_split(string)
+\end_layout
+
+\begin_layout Standard
+Split an unicode string (utf8) into an array of widechars.
+ Useful since there is no wide char access from Squirrel.
+\end_layout
+
+\begin_layout Subsection
+breakpoint()
+\end_layout
+
+\begin_layout Standard
+Stop the debugger when reaches here (when run inside the debugger).
+\end_layout
+
+\begin_layout Subsection
+backtrace()
+\end_layout
+
+\begin_layout Standard
+Print a backtrace of the call stack.
+\end_layout
+
+\begin_layout Subsection
+tr(text)
+\end_layout
+
+\begin_layout Standard
+Translate text (use string lookup in Godot translation system).
+\end_layout
+
+\begin_layout Subsection
+printerr(text)
+\end_layout
+
+\begin_layout Standard
+Print a string to stderr.
+\end_layout
+
+\end_body
+\end_document