@GDScript

- Built-in GDScript functions. -

Category: Core

Public Methods:

real	sin ( real s )
real	cos ( real s )
real	tan ( real s )
real	sinh ( real s )
real	cosh ( real s )
real	tanh ( real s )
real	asin ( real s )
real	acos ( real s )
real	atan ( real s )
real	atan2 ( real x, real y )
real	sqrt ( real s )
real	fmod ( real x, real y )
real	fposmod ( real x, real y )
real	floor ( real s )
real	ceil ( real s )
real	round ( real s )
real	abs ( real s )
real	sign ( real s )
real	pow ( real x, real y )
real	log ( real s )
real	exp ( real s )
real	isnan ( real s )
real	isinf ( real s )
real	ease ( real s, real curve )
real	decimals ( real step )
real	stepify ( real s, real step )
int	rand ()
real	randf ()
real	rand_range ( real from, real to )
Array	rand_seed ( real seed )
real	deg2rad ( real deg )
real	rad2deg ( real rad )
real	linear2db ( real nrg )
real	db2linear ( real db )
real	max ( real a, real b )
real	min ( real a, real b )
real	clamp ( real val, real min, real max )
int	nearest_po2 ( int val )
Object	weakref ( Object obj )
Object	convert ( var what, int type )
String	str ( var what, var ... )
Nil	print ( var what, var ... )
Nil	printerr ( var what, var ... )
Nil	printraw ( var what, var ... )
Array	range ( var ... )

Description:

- This contains the list of built-in gdscript functions. Mostly math functions and other utilities. Everything else is expanded by objects. -

Method Documentation:

real @GDScript::sin ( real s )

- Standard sine function. -

real @GDScript::cos ( real s )

- Standard cosine function. -

real @GDScript::tan ( real s )

- Standard tangent function. -

real @GDScript::sinh ( real s )

- Hyperbolic sine. -

real @GDScript::tanh ( real s )

- Hyperbolic tangent. -

real @GDScript::asin ( real s )

- Arc-sine. -

real @GDScript::acos ( real s )

- Arc-cosine. -

real @GDScript::atan ( real s )

- Arc-tangent. -

real @GDScript::atan2 ( real x, real y )

- Arc-tangent that takes a 2D vector as argument, retuns the full -pi to +pi range. -

real @GDScript::sqrt ( real s )

- Square root. -

real @GDScript::fmod ( real x, real y )

- Module (remainder of x/y). -

real @GDScript::fposmod ( real x, real y )

- Module (remainder of x/y) that wraps equally in positive and negative. -

real @GDScript::floor ( real s )

- Floor (rounds down to nearest integer). -

real @GDScript::ceil ( real s )

- Ceiling (rounds up to nearest integer). -

real @GDScript::round ( real s )

- Round to nearest integer. -

real @GDScript::abs ( real s )

- Remove sign (works for integer and float). -

real @GDScript::sign ( real s )

- Return sign (-1 or +1). -

real @GDScript::pow ( real x, real y )

- Power function, x elevate to y. -

real @GDScript::log ( real s )

- Natural logarithm. -

real @GDScript::exp ( real s )

- Exponential logarithm. -

real @GDScript::isnan ( real s )

- Return true if the float is not a number. -

real @GDScript::isinf ( real s )

- Return true if the float is infinite. -

real @GDScript::ease ( real s, real curve )

- Easing function, based on exponent. 0 is constant, 1 is linear, 0 to 1 is ease-in, 1+ is ease out. Negative values are in-out/out in. -

real @GDScript::decimals ( real step )

- Return the amount of decimals in the floating point value. -

real @GDScript::stepify ( real s, real step )

- Snap float value to a given step. -

int @GDScript::rand ()

- Random value (integer). -

real @GDScript::randf ()

- Random value (0 to 1 float). -

real @GDScript::rand_range ( real from, real to )

- Random range. -

Array @GDScript::rand_seed ( real seed )

- random from seed, pass a seed and an array with both number and new seed is returned. -

real @GDScript::deg2rad ( real deg )

- Convert from degrees to radians. -

real @GDScript::rad2deg ( real rad )

- Convert from radias to degrees. -

real @GDScript::linear2db ( real nrg )

- Convert from linear energy to decibels (audio). -

real @GDScript::db2linear ( real db )

- Convert from decibels to linear energy (audio). -

real @GDScript::max ( real a, real b )

- Return the maximum of two values. -

real @GDScript::min ( real a, real b )

- Return the minimum of two values. -

real @GDScript::clamp ( real val, real min, real max )

- Clamp both values to a range. -

int @GDScript::nearest_po2 ( int val )

- Return the nearest larger power of 2 for an integer. -

Object @GDScript::weakref ( Object obj )

- Return a weak reference to an object. -

Object @GDScript::convert ( var what, int type )

- Convert from a type to another in the best way possible. The "type" parameter uses the enum TYPE_* in Global Scope. -

String @GDScript::str ( var what, var ... )

- Convert one or more arguments to strings in the best way possible. -

Nil @GDScript::print ( var what, var ... )

- Print one or more arguments to strings in the best way possible to a console line. -

Nil @GDScript::printerr ( var what, var ... )

- Print one or more arguments to strings in the best way possible to standard error line. -

Nil @GDScript::printraw ( var what, var ... )

- Print one or more arguments to strings in the best way possible to console. No newline is added at the end. -

Array @GDScript::range ( var ... )

- Return an array with the given range. Range can be 1 argument N (0 to N-1), two arguments (initial, final-1) or three arguments (initial,final-1,increment). -

@Global Scope

- Global scope constants and variables. -

Category: Core

Public Variables:

Globals Globals -

IP IP -

Geometry Geometry -

ResourceLoader ResourceLoader -

ResourceSaver ResourceSaver -

PathRemap PathRemap -

OS OS -

TranslationServer TranslationServer -

TranslationServer TS -

SceneIO SceneIO -

VisualServer VisualServer -

VisualServer VS -

AudioServer AudioServer -

AudioServer AS -

PhysicsServer PhysicsServer -

PhysicsServer PS -

Physics2DServer Physics2DServer -

Physics2DServer PS2D -

SpatialSound2DServer SpatialSoundServer -

SpatialSound2DServer SS -

SpatialSound2DServer SpatialSound2DServer -

SpatialSound2DServer SS2D -

Constants:

MARGIN_LEFT = 0 -

MARGIN_TOP = 1 -

MARGIN_RIGHT = 2 -

MARGIN_BOTTOM = 3 -

VERTICAL = 1 -

HORIZONTAL = 0 -

HALIGN_LEFT = 0 -

HALIGN_CENTER = 1 -

HALIGN_RIGHT = 2 -

VALIGN_TOP = 0 -

VALIGN_CENTER = 1 -

VALIGN_BOTTOM = 2 -

SPKEY = 16777216 -

KEY_ESCAPE = 16777217 -

KEY_TAB = 16777218 -

KEY_BACKTAB = 16777219 -

KEY_BACKSPACE = 16777220 -

KEY_RETURN = 16777221 -

KEY_ENTER = 16777222 -

KEY_INSERT = 16777223 -

KEY_DELETE = 16777224 -

KEY_PAUSE = 16777225 -

KEY_PRINT = 16777226 -

KEY_SYSREQ = 16777227 -

KEY_CLEAR = 16777228 -

KEY_HOME = 16777229 -

KEY_END = 16777230 -

KEY_LEFT = 16777231 -

KEY_UP = 16777232 -

KEY_RIGHT = 16777233 -

KEY_DOWN = 16777234 -

KEY_PAGEUP = 16777235 -

KEY_PAGEDOWN = 16777236 -

KEY_SHIFT = 16777237 -

KEY_CONTROL = 16777238 -

KEY_META = 16777239 -

KEY_ALT = 16777240 -

KEY_CAPSLOCK = 16777241 -

KEY_NUMLOCK = 16777242 -

KEY_SCROLLLOCK = 16777243 -

KEY_F1 = 16777244 -

KEY_F2 = 16777245 -

KEY_F3 = 16777246 -

KEY_F4 = 16777247 -

KEY_F5 = 16777248 -

KEY_F6 = 16777249 -

KEY_F7 = 16777250 -

KEY_F8 = 16777251 -

KEY_F9 = 16777252 -

KEY_F10 = 16777253 -

KEY_F11 = 16777254 -

KEY_F12 = 16777255 -

KEY_F13 = 16777256 -

KEY_F14 = 16777257 -

KEY_F15 = 16777258 -

KEY_F16 = 16777259 -

KEY_KP_ENTER = 16777344 -

KEY_KP_MULTIPLY = 16777345 -

KEY_KP_DIVIDE = 16777346 -

KEY_KP_SUBSTRACT = 16777347 -

KEY_KP_PERIOD = 16777348 -

KEY_KP_ADD = 16777349 -

KEY_KP_0 = 16777350 -

KEY_KP_1 = 16777351 -

KEY_KP_2 = 16777352 -

KEY_KP_3 = 16777353 -

KEY_KP_4 = 16777354 -

KEY_KP_5 = 16777355 -

KEY_KP_6 = 16777356 -

KEY_KP_7 = 16777357 -

KEY_KP_8 = 16777358 -

KEY_KP_9 = 16777359 -

KEY_SUPER_L = 16777260 -

KEY_SUPER_R = 16777261 -

KEY_MENU = 16777262 -

KEY_HYPER_L = 16777263 -

KEY_HYPER_R = 16777264 -

KEY_HELP = 16777265 -

KEY_DIRECTION_L = 16777266 -

KEY_DIRECTION_R = 16777267 -

KEY_BACK = 16777280 -

KEY_FORWARD = 16777281 -

KEY_STOP = 16777282 -

KEY_REFRESH = 16777283 -

KEY_VOLUMEDOWN = 16777284 -

KEY_VOLUMEMUTE = 16777285 -

KEY_VOLUMEUP = 16777286 -

KEY_BASSBOOST = 16777287 -

KEY_BASSUP = 16777288 -

KEY_BASSDOWN = 16777289 -

KEY_TREBLEUP = 16777290 -

KEY_TREBLEDOWN = 16777291 -

KEY_MEDIAPLAY = 16777292 -

KEY_MEDIASTOP = 16777293 -

KEY_MEDIAPREVIOUS = 16777294 -

KEY_MEDIANEXT = 16777295 -

KEY_MEDIARECORD = 16777296 -

KEY_HOMEPAGE = 16777297 -

KEY_FAVORITES = 16777298 -

KEY_SEARCH = 16777299 -

KEY_STANDBY = 16777300 -

KEY_OPENURL = 16777301 -

KEY_LAUNCHMAIL = 16777302 -

KEY_LAUNCHMEDIA = 16777303 -

KEY_LAUNCH0 = 16777304 -

KEY_LAUNCH1 = 16777305 -

KEY_LAUNCH2 = 16777306 -

KEY_LAUNCH3 = 16777307 -

KEY_LAUNCH4 = 16777308 -

KEY_LAUNCH5 = 16777309 -

KEY_LAUNCH6 = 16777310 -

KEY_LAUNCH7 = 16777311 -

KEY_LAUNCH8 = 16777312 -

KEY_LAUNCH9 = 16777313 -

KEY_LAUNCHA = 16777314 -

KEY_LAUNCHB = 16777315 -

KEY_LAUNCHC = 16777316 -

KEY_LAUNCHD = 16777317 -

KEY_LAUNCHE = 16777318 -

KEY_LAUNCHF = 16777319 -

KEY_UNKNOWN = 33554431 -

KEY_SPACE = 32 -

KEY_EXCLAM = 33 -

KEY_QUOTEDBL = 34 -

KEY_NUMBERSIGN = 35 -

KEY_DOLLAR = 36 -

KEY_PERCENT = 37 -

KEY_AMPERSAND = 38 -

KEY_APOSTROPHE = 39 -

KEY_PARENLEFT = 40 -

KEY_PARENRIGHT = 41 -

KEY_ASTERISK = 42 -

KEY_PLUS = 43 -

KEY_COMMA = 44 -

KEY_MINUS = 45 -

KEY_PERIOD = 46 -

KEY_SLASH = 47 -

KEY_0 = 48 -

KEY_1 = 49 -

KEY_2 = 50 -

KEY_3 = 51 -

KEY_4 = 52 -

KEY_5 = 53 -

KEY_6 = 54 -

KEY_7 = 55 -

KEY_8 = 56 -

KEY_9 = 57 -

KEY_COLON = 58 -

KEY_SEMICOLON = 59 -

KEY_LESS = 60 -

KEY_EQUAL = 61 -

KEY_GREATER = 62 -

KEY_QUESTION = 63 -

KEY_AT = 64 -

KEY_A = 65 -

KEY_B = 66 -

KEY_C = 67 -

KEY_D = 68 -

KEY_E = 69 -

KEY_F = 70 -

KEY_G = 71 -

KEY_H = 72 -

KEY_I = 73 -

KEY_J = 74 -

KEY_K = 75 -

KEY_L = 76 -

KEY_M = 77 -

KEY_N = 78 -

KEY_O = 79 -

KEY_P = 80 -

KEY_Q = 81 -

KEY_R = 82 -

KEY_S = 83 -

KEY_T = 84 -

KEY_U = 85 -

KEY_V = 86 -

KEY_W = 87 -

KEY_X = 88 -

KEY_Y = 89 -

KEY_Z = 90 -

KEY_BRACKETLEFT = 91 -

KEY_BACKSLASH = 92 -

KEY_BRACKETRIGHT = 93 -

KEY_ASCIICIRCUM = 94 -

KEY_UNDERSCORE = 95 -

KEY_QUOTELEFT = 96 -

KEY_BRACELEFT = 123 -

KEY_BAR = 124 -

KEY_BRACERIGHT = 125 -

KEY_ASCIITILDE = 126 -

KEY_NOBREAKSPACE = 160 -

KEY_EXCLAMDOWN = 161 -

KEY_CENT = 162 -

KEY_STERLING = 163 -

KEY_CURRENCY = 164 -

KEY_YEN = 165 -

KEY_BROKENBAR = 166 -

KEY_SECTION = 167 -

KEY_DIAERESIS = 168 -

KEY_COPYRIGHT = 169 -

KEY_ORDFEMININE = 170 -

KEY_GUILLEMOTLEFT = 171 -

KEY_NOTSIGN = 172 -

KEY_HYPHEN = 173 -

KEY_REGISTERED = 174 -

KEY_MACRON = 175 -

KEY_DEGREE = 176 -

KEY_PLUSMINUS = 177 -

KEY_TWOSUPERIOR = 178 -

KEY_THREESUPERIOR = 179 -

KEY_ACUTE = 180 -

KEY_MU = 181 -

KEY_PARAGRAPH = 182 -

KEY_PERIODCENTERED = 183 -

KEY_CEDILLA = 184 -

KEY_ONESUPERIOR = 185 -

KEY_MASCULINE = 186 -

KEY_GUILLEMOTRIGHT = 187 -

KEY_ONEQUARTER = 188 -

KEY_ONEHALF = 189 -

KEY_THREEQUARTERS = 190 -

KEY_QUESTIONDOWN = 191 -

KEY_AGRAVE = 192 -

KEY_AACUTE = 193 -

KEY_ACIRCUMFLEX = 194 -

KEY_ATILDE = 195 -

KEY_ADIAERESIS = 196 -

KEY_ARING = 197 -

KEY_AE = 198 -

KEY_CCEDILLA = 199 -

KEY_EGRAVE = 200 -

KEY_EACUTE = 201 -

KEY_ECIRCUMFLEX = 202 -

KEY_EDIAERESIS = 203 -

KEY_IGRAVE = 204 -

KEY_IACUTE = 205 -

KEY_ICIRCUMFLEX = 206 -

KEY_IDIAERESIS = 207 -

KEY_ETH = 208 -

KEY_NTILDE = 209 -

KEY_OGRAVE = 210 -

KEY_OACUTE = 211 -

KEY_OCIRCUMFLEX = 212 -

KEY_OTILDE = 213 -

KEY_ODIAERESIS = 214 -

KEY_MULTIPLY = 215 -

KEY_OOBLIQUE = 216 -

KEY_UGRAVE = 217 -

KEY_UACUTE = 218 -

KEY_UCIRCUMFLEX = 219 -

KEY_UDIAERESIS = 220 -

KEY_YACUTE = 221 -

KEY_THORN = 222 -

KEY_SSHARP = 223 -

KEY_DIVISION = 247 -

KEY_YDIAERESIS = 255 -

KEY_CODE_MASK = 33554431 -

KEY_MODIFIER_MASK = -16777216 -

KEY_MASK_SHIFT = 33554432 -

KEY_MASK_ALT = 67108864 -

KEY_MASK_META = 134217728 -

KEY_MASK_CTRL = 268435456 -

KEY_MASK_KPAD = 536870912 -

KEY_MASK_GROUP_SWITCH = 1073741824 -

BUTTON_LEFT = 1 -

BUTTON_RIGHT = 2 -

BUTTON_MIDDLE = 3 -

BUTTON_WHEEL_UP = 4 -

BUTTON_WHEEL_DOWN = 5 -

BUTTON_MASK_LEFT = 1 -

BUTTON_MASK_RIGHT = 2 -

BUTTON_MASK_MIDDLE = 4 -

JOY_BUTTON_0 = 0 -

JOY_BUTTON_1 = 1 -

JOY_BUTTON_2 = 2 -

JOY_BUTTON_3 = 3 -

JOY_BUTTON_4 = 4 -

JOY_BUTTON_5 = 5 -

JOY_BUTTON_6 = 6 -

JOY_BUTTON_7 = 7 -

JOY_BUTTON_8 = 8 -

JOY_BUTTON_9 = 9 -

JOY_BUTTON_10 = 10 -

JOY_BUTTON_11 = 11 -

JOY_BUTTON_12 = 12 -

JOY_BUTTON_13 = 13 -

JOY_BUTTON_14 = 14 -

JOY_BUTTON_15 = 15 -

JOY_BUTTON_MAX = 16 -

JOY_SNES_A = 1 -

JOY_SNES_B = 0 -

JOY_SNES_X = 3 -

JOY_SNES_Y = 2 -

JOY_SONY_CIRCLE = 1 -

JOY_SONY_X = 0 -

JOY_SONY_SQUARE = 2 -

JOY_SONY_TRIANGLE = 3 -

JOY_SEGA_B = 1 -

JOY_SEGA_A = 0 -

JOY_SEGA_X = 2 -

JOY_SEGA_Y = 3 -

JOY_XBOX_B = 1 -

JOY_XBOX_A = 0 -

JOY_XBOX_X = 2 -

JOY_XBOX_Y = 3 -

JOY_DS_A = 1 -

JOY_DS_B = 0 -

JOY_DS_X = 3 -

JOY_DS_Y = 2 -

JOY_SELECT = 10 -

JOY_START = 11 -

JOY_DPAD_UP = 12 -

JOY_DPAD_DOWN = 13 -

JOY_DPAD_LEFT = 14 -

JOY_DPAD_RIGHT = 15 -

JOY_L = 4 -

JOY_L2 = 6 -

JOY_L3 = 8 -

JOY_R = 5 -

JOY_R2 = 7 -

JOY_R3 = 9 -

JOY_AXIS_0 = 0 -

JOY_AXIS_1 = 1 -

JOY_AXIS_2 = 2 -

JOY_AXIS_3 = 3 -

JOY_AXIS_4 = 4 -

JOY_AXIS_5 = 5 -

JOY_AXIS_6 = 6 -

JOY_AXIS_7 = 7 -

JOY_AXIS_MAX = 8 -

JOY_ANALOG_0_X = 0 -

JOY_ANALOG_0_Y = 1 -

JOY_ANALOG_1_X = 2 -

JOY_ANALOG_1_Y = 3 -

JOY_ANALOG_2_X = 4 -

JOY_ANALOG_2_Y = 5 -

OK = 0 -

FAILED = 1 -

ERR_UNAVAILABLE = 2 -

ERR_UNCONFIGURED = 3 -

ERR_UNAUTHORIZED = 4 -

ERR_PARAMETER_RANGE_ERROR = 5 -

ERR_OUT_OF_MEMORY = 6 -

ERR_FILE_NOT_FOUND = 7 -

ERR_FILE_BAD_DRIVE = 8 -

ERR_FILE_BAD_PATH = 9 -

ERR_FILE_NO_PERMISSION = 10 -

ERR_FILE_ALREADY_IN_USE = 11 -

ERR_FILE_CANT_OPEN = 12 -

ERR_FILE_CANT_WRITE = 13 -

ERR_FILE_CANT_READ = 14 -

ERR_FILE_UNRECOGNIZED = 15 -

ERR_FILE_CORRUPT = 16 -

ERR_FILE_EOF = 17 -

ERR_CANT_OPEN = 18 -

ERR_CANT_CREATE = 19 -

ERROR_QUERY_FAILED = 20 -

ERR_ALREADY_IN_USE = 21 -

ERR_LOCKED = 22 -

ERR_TIMEOUT = 23 -

ERR_CANT_AQUIRE_RESOURCE = 24 -

ERR_INVALID_DATA = 26 -

ERR_INVALID_PARAMETER = 27 -

ERR_ALREADY_EXISTS = 28 -

ERR_DOES_NOT_EXIST = 29 -

ERR_DATABASE_CANT_READ = 30 -

ERR_DATABASE_CANT_WRITE = 31 -

ERR_COMPILATION_FAILED = 32 -

ERR_METHOD_NOT_FOUND = 33 -

ERR_LINK_FAILED = 34 -

ERR_SCRIPT_FAILED = 35 -

ERR_CYCLIC_LINK = 36 -

ERR_BUSY = 40 -

ERR_HELP = 42 -

ERR_BUG = 43 -

ERR_WTF = 45 -

PROPERTY_HINT_NONE = 0 - No hint for edited property. -

PROPERTY_HINT_RANGE = 1 -

PROPERTY_HINT_EXP_RANGE = 2 - Hint string is an exponential range, defined as "min,max" or "min,max,step". This is valid for integers and floats. -

PROPERTY_HINT_ENUM = 3 - Property hint is an enumerated value, like "Hello,Something,Else". This is valid for integers, floats and strings properties. -

PROPERTY_HINT_LENGTH = 5 -

PROPERTY_HINT_FLAGS = 7 - Property hint is a bitmask description, for bits 0,1,2,3 abd 5 the hint would be like "Bit0,Bit1,Bit2,Bit3,,Bit5". Valid only for integers. -

PROPERTY_HINT_FILE = 8 - String property is a file (so pop up a file dialog when edited). Hint string can be a set of wildcards like "*.doc". -

PROPERTY_HINT_DIR = 9 - String property is a directory (so pop up a file dialog when edited). -

PROPERTY_HINT_RESOURCE_TYPE = 10 - String property is a resource, so open the resource popup menu when edited. -

PROPERTY_USAGE_STORAGE = 1 - Property will be used as storage (default). -

PROPERTY_USAGE_EDITOR = 2 - Property will be visible in editor (default). -

PROPERTY_USAGE_NETWORK = 4 -

PROPERTY_USAGE_DEFAULT = 7 - Default usage (storage and editor). -

TYPE_NIL = 0 -

TYPE_BOOL = 1 -

TYPE_INT = 2 -

TYPE_REAL = 3 -

TYPE_STRING = 4 -

TYPE_VECTOR2 = 5 -

TYPE_RECT2 = 6 -

TYPE_VECTOR3 = 7 -

TYPE_MATRIX32 = 8 -

TYPE_PLANE = 9 -

TYPE_QUAT = 10 -

TYPE_AABB = 11 -

TYPE_MATRIX3 = 12 -

TYPE_TRANSFORM = 13 -

TYPE_COLOR = 14 -

TYPE_IMAGE = 15 -

TYPE_NODE_PATH = 16 -

TYPE_RID = 17 -

TYPE_OBJECT = 18 -

TYPE_INPUT_EVENT = 19 -

TYPE_DICTIONARY = 20 -

TYPE_ARRAY = 21 -

TYPE_RAW_ARRAY = 22 -

TYPE_INT_ARRAY = 23 -

TYPE_REAL_ARRAY = 24 -

TYPE_STRING_ARRAY = 25 -

TYPE_VECTOR2_ARRAY = 26 -

TYPE_VECTOR3_ARRAY = 27 -

TYPE_COLOR_ARRAY = 28 -

TYPE_MAX = 29 -

Description:

- Global scope constants and variables. This is all that resides in the globals, constants regarding error codes, scancodes, property hints, etc. It's not much. - Singletons are also documented here, since they can be accessed from anywhere. -

Method Documentation:

@Squirrel

Category: Core

Method Documentation:

1 Introduction to 3D Math

1.1 Introduction

There are many approaches to understanding the type of 3D math used in video -games, modelling, ray-tracing, etc. The usual is through vector algebra, matrices, and -linear transformations and, while they are not completely necesary to understand -most of the aspects of 3D game programming (from the theorical point of view), they -provide a common language to communicate with other programmers or -engineers. -

This tutorial will focus on explaining all the basic concepts needed for a -programmer to understand how to develop 3D games without getting too deep into -algebra. Instead of a math-oriented language, code examples will be given instead -when possible. The reason for this is that. while programmers may have -different backgrounds or experience (be it scientific, engineering or self taught), -code is the most familiar language and the lowest common denominator for -understanding. -

1.2 Vectors

1.2.1 Brief Introduction

When writing 2D games, interfaces and other applications, the typical convention is -to define coordinates as an x,y pair, x representing the horizontal offset and y the -vertical one. In most cases, the unit for both is pixels. This makes sense given the -screen is just a rectangle in two dimensions. -

An x,y pair can be used for two purposes. It can be an absolute position (screen -cordinate in the previous case), or a relative direction, if we trace an arrow from the -origin (0,0 coordinates) to it’s position. -

When used as a direction, this pair is called a vector, and two properties can be -observed: The first is the magnitude or length , and the second is the direction. In -two dimensions, direction can be an angle. The magnitude or length can be computed -by simply using Pithagoras theorem: -

The direction can be an arbitrary angle from either the x or y axis, and could be -computed by using trigonometry, or just using the usual atan2 function present in -most math libraries. However, when dealing with 3D, the direction can’t be described -as an angle. To separate magnitude and direction, 3D uses the concept of normal -vectors. -

1.2.2 Implementation

Vectors are implemented in Godot Engine as a class named Vector3 for 3D, and as -both Vector2, Point2 or Size2 in 2D (they are all aliases). They are used for any -purpose where a pair of 2D or 3D values (described as x,y or x,y,z) is needed. This is -somewhat a standard in most libraries or engines. In the script API, they can be -instanced like this: - -

Vectors also support the common operators +, -, / and * for addition, -substraction, multiplication and division. - -

Vectors also can perform a wide variety of built-in functions, their most common -usages will be explored next. -

1.2.3 Normal Vectors

Two points ago, it was mentioned that 3D vectors can’t describe their direction as an -agle (as 2D vectors can). Because of this, normal vectors become important for -separating a vector between direction and magnitude. -

A normal vector is a vector with a magnitude of 1. This means, no matter where -the vector is pointing to, it’s length is always 1. -

Normal vectors have endless uses in 3D graphics programming, so it’s -recommended to get familiar with them as much as possible. -

1.2.4 Normalization

Normalization is the process through which normal vectors are obtained -from regular vectors. In other words, normalization is used to reduce the -magnitude of any vector to 1. (except of course, unless the vector is (0,0,0) -). -

To normalize a vector, it must be divided by its magnitude (which should be -greater than zero): - -

1.2.5 Dot Product

The dot product is, pheraps, the most useful operation that can be applied to 3D -vectors. In the surface, it’s multiple usages are not very obvious, but in depth it can -provide very useful information between two vectors (be it direction or just points in -space). -

The dot product takes two vectors (a and b in the example) and returns a scalar -(single real number): -

1.2.6 Cross Product

The cross product also takes two vectors a and b, but returns another vector c that is -orthogonal to the two previous ones. -

1.3 Plane

1.3.1 Theory

A plane can be considered as an infinite, flat surface that splits space in two halves, -usually one named positive and one named negative. In regular mathematics, a plane -formula is described as: -

However, in 3D programming, this form alone is often of little use. For planes to -become useful, they must be in normalized form. -

A normalized plane consists of a normal vector n and a distance d. To normalize -a plane, a vector n and distance d’ are created this way: -

In any case, normalizing planes is not often needed (this was mostly for -explanation purposes), and normalized planes are useful because they can be created -and used easily. -

A normalized plane could be visualized as a plane pointing towards normal n, -offseted by d in the direction of n. -

In other words, take n, multiply it by scalar d and the resulting point will be part -of the plane. This may need some thinking, so an example with a 2D normal vector -(z is 0, so plane is orthogonal to it) is provided: -

1.3.2 Implementation

1.4 Matrices, Quaternions and Coordinate Systems

It is very often needed to store the location/rotation of something. In 2D, it is often -enough to store an x,y location and maybe an angle as the rotation, as that should -be enough to represent any posible position. -

In 3D this becomes a little more difficult, as there is nothing as simple as an angle -to store a 3-axis rotation. -

The first think that may come to mind is to use 3 angles, one for x, one for y and -one for z. However this suffers from the problem that it becomes very cumbersome to -use, as the individual rotations in each axis need to be performed one after another -(they can’t be performed at the same time), leading to a problem called “gimbal -lock”. Also, it becomes impossible to accumulate rotations (add a rotation to an -existing one). -

To solve this, there are two known diferent approaches that aid in solving -rotation, Quaternions and Oriented Coordinate Systems. -

1.4.1 Oriented Coordinate Systems

Oriented Coordinate Systems (OCS) are a way of representing a coordinate system -inside the cartesian coordinate system. They are mainly composed of 3 Vectors, one -for each axis. The first vector is the x axis, the second the y axis, and the third is the - -z axis. The OCS vectors can be rotated around freely as long as they are kept the -same length (as changing the length of an axis changes its cale), and as long as they -remain orthogonal to eachother (as in, the same as the default cartesian system, -with y pointing up, x pointing left and z pointing front, but all rotated -together). -

Oriented Coordinate Systems are represented in 3D programming as a 3x3 matrix, -where each row (or column, depending on the implementation) contains one of the -axis vectors. Transforming a Vector by a rotated OCS Matrix results in the rotation -being applied to the resulting vector. OCS Matrices can also be multiplied to -accumulate their transformations. -

However, in most usage cases, one wants to store a translation together with the -rotation. For this, an origin vector must be added to the OCS, thus transforming it -into a 3x4 (or 4x3, depending on preference) matrix. Godot engine implements this -functionality in the Transform class: - -

Transform contains internally a Matrix3 “basis” and a Vector3 “origin” (which can -be modified individually). -

1.4.2 Transform Internals

Internally, the xform() process is quite simple, to apply a 3x3 transform to a vector, -the transposed axis vectors are used (as using the regular axis vectors will result on -an inverse of the desired transform): - -

1.4.3 Using The Transform

So, it is often desired apply sucessive operations to a transformation. For example, -let’s a assume that there is a turtle sitting at the origin (the turtle is a logo reference, - -for those familiar with it). The y axis is up, and the the turtle’s nose is pointing -towards the z axis. -

The turtle (like many other animals, or vehicles!) can only walk towards the -direction it’s looking at. So, moving the turtle around a little should be something -like this: - -

As can be seen, every new action the turtle takes is based on the previous one it -took. Had the order of actions been different and the turtle would have never reached -the lettuce. -

Transforms are just that, a mean of “accumulating” rotation, translation, scale, -etc. -

1.4.4 A Warning about Numerical Precision

Performing several actions over a transform will slowly and gradually lead to -precision loss (objects that draw according to a transform may get jittery, bigger, -smaller, skewed, etc). This happens due to the nature of floating point numbers. if -transforms/matrices are created from other kind of values (like a position and -some angular rotation) this is not needed, but if has been accumulating -transformations and was never recreated, it can be normalized by calling the -.orthonormalize() built-in function. This function has little cost and calling it every -now and then will avoid the effects from precision loss to become visible. - - - - - diff --git a/doc/html/tutorial01/tutorial0x.png b/doc/html/tutorial01/tutorial0x.png deleted file mode 100644 index a0ed4f53ff..0000000000 Binary files a/doc/html/tutorial01/tutorial0x.png and /dev/null differ diff --git a/doc/html/tutorial01/tutorial1x.png b/doc/html/tutorial01/tutorial1x.png deleted file mode 100644 index 80f0d099f7..0000000000 Binary files a/doc/html/tutorial01/tutorial1x.png and /dev/null differ diff --git a/doc/html/tutorial01/tutorial2x.png b/doc/html/tutorial01/tutorial2x.png deleted file mode 100644 index 76c502b6da..0000000000 Binary files a/doc/html/tutorial01/tutorial2x.png and /dev/null differ diff --git a/doc/html/tutorial01/tutorial3x.png b/doc/html/tutorial01/tutorial3x.png deleted file mode 100644 index 8431e9d15c..0000000000 Binary files a/doc/html/tutorial01/tutorial3x.png and /dev/null differ diff --git a/doc/html/tutorial01/tutorial4x.png b/doc/html/tutorial01/tutorial4x.png deleted file mode 100644 index 1ce7a2bb45..0000000000 Binary files a/doc/html/tutorial01/tutorial4x.png and /dev/null differ -- cgit v1.2.3


Position		Direction