#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 \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