985 lines
16 KiB
Text
985 lines
16 KiB
Text
|
#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
|