path: root/doc/squirrel.lyx

#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