diff options
Diffstat (limited to 'doc/squirrel.lyx')
| -rw-r--r-- | doc/squirrel.lyx | 984 |
1 files changed, 0 insertions, 984 deletions
diff --git a/doc/squirrel.lyx b/doc/squirrel.lyx deleted file mode 100644 index 05270c1b8f..0000000000 --- a/doc/squirrel.lyx +++ /dev/null @@ -1,984 +0,0 @@ -#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 |