code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Your first script</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Your first script

This tutorial will show you the basics on how to configure the engine, compile a script, and then execute it. The code in this article is not complete, it only contains the relevant parts to explain the basic structure for using the script library. For complete source codes see the samples that come with the SDK.

In this tutorial a couple of add-ons are used to make the code easier. You are not required to use these in your own application, but they will most likely let you get your project up and running faster. You'll want to take a look at the rest of the add-ons later on to see what else may be useful for you.

// Include the definitions of the script library and the add-ons we'll use.

// The project settings may need to be configured to let the compiler where

// to find these headers. Don't forget to add the source modules for the

// add-ons to your project as well so that they will be compiled into the

// application.

#include <angelscript.h>

#include <scriptstdstring/scriptstdstring.h>

#include <scriptbuilder/scriptbuilder.h>

angelscript.h

The API definition for AngelScript.

Being an embedded scripting library there isn't much that AngelScript allows the scripts to do by themselves, so the first thing the application must do is to register the interface that the script will have to interact with the application. The interface may consist of functions, variables, and even complete classes.

Pay special attention to how the message callback is registered right after the engine is created. The message callback is used by the engine to give human readable error messages when something isn't working as it should, e.g. a registration is done incorrectly, or a script has an error that fails to compile. While you still need to verify the return codes, the message callback can give you valuable information that will let you figure out what is wrong without much effort.

// Create the script engine

asIScriptEngine *engine = asCreateScriptEngine();

// Set the message callback to receive information on errors in human readable form.

int r = engine->SetMessageCallback(asFUNCTION(MessageCallback), 0, asCALL_CDECL); assert( r >= 0 );

// AngelScript doesn't have a built-in string type, as there is no definite standard

// string type for C++ applications. Every developer is free to register its own string type.

// The SDK do however provide a standard add-on for registering a string type, so it's not

// necessary to implement the registration yourself if you don't want to.

RegisterStdString(engine);

// Register the function that we want the scripts to call

r = engine->RegisterGlobalFunction("void print(const string &in)", asFUNCTION(print), asCALL_CDECL); assert( r >= 0 );

asCALL_CDECL

@ asCALL_CDECL

A cdecl function.

Definition: angelscript.h:230

asFUNCTION

#define asFUNCTION(f)

Returns an asSFuncPtr representing the function specified by the name.

Definition: angelscript.h:685

asIScriptEngine

The engine interface.

Definition: angelscript.h:1102

asIScriptEngine::RegisterGlobalFunction

virtual int RegisterGlobalFunction(const char *declaration, const asSFuncPtr &funcPointer, asDWORD callConv, void *auxiliary=0)=0

Registers a global function.

asIScriptEngine::SetMessageCallback

virtual int SetMessageCallback(const asSFuncPtr &callback, void *obj, asDWORD callConv)=0

Sets a message callback that will receive compiler messages.

asCreateScriptEngine

AS_API asIScriptEngine * asCreateScriptEngine(asDWORD version=ANGELSCRIPT_VERSION)

Creates the script engine.

After the engine has been configured, the next step is to compile the scripts that should be executed.

The following is our script that will call the registered print function to write Hello world on the standard output stream. Let's say it's stored in the file test.as.

  void main()
  {
    print("Hello world\n");
  }

Here's the code for loading the script file and compiling it. The AngelScript engine itself doesn't have access to the filesystem so the loading the files has to be done by the application. Here we're going to use the script builder add-on, which does the loading of the script files, and some preprocessing, such as handling #include directives.

// The CScriptBuilder helper is an add-on that loads the file,

// performs a pre-processing pass if necessary, and then tells

// the engine to build a script module.

CScriptBuilder builder;

int r = builder.StartNewModule(engine, "MyModule");

if( r < 0 )

{

  // If the code fails here it is usually because there

  // is no more memory to allocate the module

  printf("Unrecoverable error while starting a new module.\n");

  return;

}

r = builder.AddSectionFromFile("test.as");

if( r < 0 )

{

  // The builder wasn't able to load the file. Maybe the file

  // has been removed, or the wrong name was given, or some

  // preprocessing commands are incorrectly written.

  printf("Please correct the errors in the script and try again.\n");

  return;

}

r = builder.BuildModule();

if( r < 0 )

{

  // An error occurred. Instruct the script writer to fix the

  // compilation errors that were listed in the output stream.

  printf("Please correct the errors in the script and try again.\n");

  return;

}

The last step is to identify the function that is to be called, and set up a context for executing it.

// Find the function that is to be called.

asIScriptModule *mod = engine->GetModule("MyModule");

asIScriptFunction *func = mod->GetFunctionByDecl("void main()");

if( func == 0 )

{

  // The function couldn't be found. Instruct the script writer

  // to include the expected function in the script.

  printf("The script must have the function 'void main()'. Please add it and try again.\n");

  return;

}

// Create our context, prepare it, and then execute

asIScriptContext *ctx = engine->CreateContext();

ctx->Prepare(func);

int r = ctx->Execute();

if( r != asEXECUTION_FINISHED )

{

  // The execution didn't complete as expected. Determine what happened.

  if( r == asEXECUTION_EXCEPTION )

  {

    // An exception occurred, let the script writer know what happened so it can be corrected.

    printf("An exception '%s' occurred. Please correct the code and try again.\n", ctx->GetExceptionString());

  }

}

asEXECUTION_FINISHED

@ asEXECUTION_FINISHED

The context has successfully completed the execution.

Definition: angelscript.h:402

asEXECUTION_EXCEPTION

@ asEXECUTION_EXCEPTION

The execution was terminated by an unhandled script exception.

Definition: angelscript.h:408

asIScriptContext

The interface to the virtual machine.

Definition: angelscript.h:2735

asIScriptContext::GetExceptionString

virtual const char * GetExceptionString()=0

Returns the exception string text.

asIScriptContext::Prepare

virtual int Prepare(asIScriptFunction *func)=0

Prepares the context for execution of the function.

asIScriptContext::Execute

virtual int Execute()=0

Executes the prepared function.

asIScriptEngine::GetModule

virtual asIScriptModule * GetModule(const char *module, asEGMFlags flag=asGM_ONLY_IF_EXISTS)=0

Return an interface pointer to the module.

asIScriptEngine::CreateContext

virtual asIScriptContext * CreateContext()=0

Creates a new script context.

asIScriptFunction

The interface for a script function description.

Definition: angelscript.h:4000

asIScriptModule

The interface to the script modules.

Definition: angelscript.h:2232

asIScriptModule::GetFunctionByDecl

virtual asIScriptFunction * GetFunctionByDecl(const char *decl) const =0

Returns the function by its declaration.

The exception handling above is very basic. The application may also obtain information about line number, function, call stack, and even values of local and global variables if wanted.

Don't forget to clean up after you're done with the engine.

// Clean up

ctx->Release();

engine->ShutDownAndRelease();

asIScriptContext::Release

virtual int Release() const =0

Decrease reference counter.

asIScriptEngine::ShutDownAndRelease

virtual int ShutDownAndRelease()=0

Shuts down the engine then decrease the reference counter.

Helper functions

The print function is implemented as a very simple wrapper on the printf function.

// Print the script string to the standard output stream

void print(string &msg)

{

  printf("%s", msg.c_str());

}

See also

Message callback, Script builder, string object, Samples

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: License</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

License

AngelCode Scripting Library

Copyright © 2003-2023 Andreas Jönsson

This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.

Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.

This notice may not be removed or altered from any source distribution.

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6

repo_name: Antidote/openrpgeditor

license: mit


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Memory management</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Memory management

This article will explain the memory management in AngelScript in detail. It's probably more detail than most developers need to know, but some may want to know exactly how it works in order to evaluate AngelScript better.

Overview of the memory management

AngelScript uses a hybrid method with both reference counting and garbage collection, where reference counting is the main method and the garbage collection is only for backup when circular references needs to be resolved.

This design was chosen because reference counting is the easiest way of passing objects between script engine and application while still keeping track of live objects. If pure garbage collection was used, the script engine would have to know about the entire memory space of the application where script objects could be stored, otherwise it wouldn't be able to know if the objects are still alive or not.

The garbage collector is only used for those object types that have a possibility of forming a circular reference with itself or other objects, e.g. objects that have a member variable as a handle to the same type as itself. Whenever such an object is created, the garbage collector is informed so that it can keep track of the object.

The garbage collector can be executed automatically by the engine, but the application may also choose to do it manually to have better control over when it is done. The garbage collector is incremental, so it can be executed in small steps throughout the application execution without halting the rest of the processing for longer periods.

See also

Garbage collection

Reference counting algorithm

All built-in script objects are automatically reference counted, and the application just need to make sure to call the AddRef and Release methods appropriately if it is storing any references to the objects outside the script engine.

Application registered objects may or may not be reference counted. Those that should be reference counted must implement the ADDREF and RELEASE behaviours so that AngelScript can notify the objects of the changes to the reference count. The application needs to keep track of the reference counter itself and free the memory when there are no more references to the object. This is usually done by having an integer member variable in the object structure itself to hold the reference count. It can also be implemented with a separate structure for holding the reference counter, but it adds extra overhead as the reference counter must be searched for with each change.

See also

Registering an object type

Garbage collector algorithm

The garbage collector, used to handle the scenarios where reference counting isn't enough, uses the following algorithm.

Destroy garbage: Free all objects with only one reference. This reference is held by the GC itself so therefore it is known that nobody else is referencing the object.

Clear counters: Clear the GC counter for the remaining objects. This counter will be used to count the references to the object reachable from the GC. At the same time the objects are also flagged, so that we can detect if the references change while the garbage collector is running. This flag is automatically cleared when incrementing or decrementing the reference counter.

Count GC references: For each of the objects in the GC, tell it to increment the GC counter for all objects it holds references to. This is only done for objects still flagged, because if the flag is no longer set we know it has been referenced by the application, thus it is considered alive along with all objects it holds references to.

Mark live objects: Build a list of all objects in the GC that are not flagged or that doesn't have the GC count equal to the reference counter. These are objects that are considered alive. For each of the objects in the list, add all of the references in the object to the list as well, unless they are already in the list. As the list is traversed it will grow with new objects, these objects will also have their references added to the list. This way we're following the chain of references so we're gathering all objects that are alive.

Verify unmarked objects: Make one more pass over the list of objects in the GC to see if any of the objects that were not marked as alive has had the flag cleared, if it has then the run the 'mark live objects' step again.

Break circular references: All objects that have not been marked as alive by this time are involved in unreachable circular references and must be destroyed. The objects are destroyed by telling the objects to release the references they hold, thus breaking the circular references. When all circular references have been broken, the entire GC routine is restarted which will free the objects. If there were no dead objects, then the GC is finished.

All of the steps are incremental, i.e. they can be interrupted to allow the application and scripts to execute before continuing the garbage collection. Step 1 can also be executed individually at any time during the cycle, this permits to free up memory for objects that are not involved in cyclic memory without having to wait for the detection cycle to complete.

The GC also has a notion of new and old generations. All new objects are placed in the new generation. In this generation, only trivial garbage collection is done, i.e. the 'destroy garbage' step above. Once the objects in the new generation have survived a few iterations without being destroyed, they are moved to the old generation. In the old generation the full garbage collection algorithm is executed.

This division of new and old generations help reduce the work done by the GC to detect circular references, and thus improve the performance of the application.

See also

Garbage collected objects

Memory heap

By default AngelScript uses the memory heap accessed through the standard malloc and free global functions when allocating memory. Usually this means that AngelScript shares the memory heap with the application, though if the AngelScript library is compiled as a DLL or a shared object the heap may actually be separate from the application heap.

Some applications need extra control over the memory heap that the standard C/C++ library doesn't provide. This is common with video games for consoles, that have limited memory and cannot afford loosing space due to fragmentation or many small allocations. AngelScript aids these applications as well as it is possible to register custom memory allocation routines with the library, giving the application exact control over the memory used by AngelScript.

See also

asSetGlobalMemoryFunctions

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Script modules</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Script modules

Each module is an independent unit with it's own scope of script functions, global variables, and classes. All scripts executed from a module will work on the same global variables contained within that module. In this sense a module can be thought of as a shared library that is loaded into an application.

Single module versus multiple modules

Whether it is better to use a single module with all the script code, or multiple modules with smaller and more specialized scripts, depends on the needs of the application.

A single module can be easier to implement, as all script code is in the same scope and can interact with full freedom. On the other hand the entire script must be compiled together, making it more difficult to exchange parts of the script or load only the logic that is needed at the moment.

With multiple modules an application can also expose different interfaces to scripts with different tasks, e.g. a script that controls the graphical user interface in an application should perhaps not have access to the same interface used by the script that controls the artificial intelligence, and vice versa.

Multiple modules can also use the same script code, in this case they will be completely distinct, each with their own set of global variables, functions, and types, even though the same source code was used. There may be valid reasons for using this in an application, but usually it is better to use a single module with script classes. The bytecode, functions, and types will then be shared, and the variables that should be distinct for each instance should be declared as class members.

Exchanging information between modules

While modules are independent, it may sometimes be necessary to exchange information between them. This can be accomplished in many different ways. One way is through function binding, where one module imports functions from another module and call those directly. Another way is with shared script entities, where handles to objects or functions can be exchanged between the modules. A third alternative is through messaging or proxy functions exposed by the application.

All of these alternatives require a little code from the application, as one module doesn't automatically see another without the application's knowledge.

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Object handles to the application</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Object handles to the application

In AngelScript an object handle is a reference counted pointer to an object. In the scripts they are used to pass the objects around by reference instead of by value. Depending on how an application type is registered the type will support handles.

See also

Registering an object type, Object handles in the script language

Managing the reference counter in functions

Whenever the object handle is passed by value from the application to the script engine, or vice versa its reference should be accounted for. This means that the application must release any object handles it receives as parameters when it no longer needs them, it also means that the application must increase the reference counter for any object handle being returned to the script engine. This also applies to the generic calling convention.

A function that creates an object and returns it to the script engine might look like this:

// Registered as "obj@ CreateObject()"

obj *CreateObject()

{

  // The constructor already initializes the ref count to 1

  return new obj();

}

A function that receives an object handle from the script and stores it in a global variable might look like this:

// Registered as "void StoreObject(obj@)"

obj *o = 0;

void StoreObject(obj *newO)

{

  // Release the old object handle

  if( o ) o->Release();

  // Store the new object handle

  o = newO;

}

A function that retrieves a previously stored object handle might look like this:

// Registered as "obj@ RetrieveObject()"

obj *RetrieveObject()

{

  // Increase the reference counter to account for the returned handle

  if( o ) o->AddRef();

  // It is ok to return null if there is no previous handle stored

  return o;

}

A function that receives an object handle in the parameter, but doesn't store it looks like this:

// Registered as "void DoSomething(obj@)"

void DoSomething(obj *o)

{

  // When finished with the object it must be released

  if( o ) o->Release();

}

Auto handles can make it easier

The application can use auto handles (@+) to alleviate some of the work of managing the reference counter. When registering the function or method with AngelScript, add a plus sign to the object handles that AngelScript should automatically manage. For parameters AngelScript will then release the reference after the function returns, and for the return value AngelScript will increase the reference on the returned pointer. The reference for the returned value is increased before the parameters are released, so it is possible to have the function return one of the parameters.

// Registered as "obj@+ ChooseObj(obj@+, obj@+)"

obj *ChooseObj(obj *a, obj *b)

{

  // Because of the auto handles AngelScript will

  // automatically manage the reference counters

  return some_condition ? a : b;

}

The auto handles works the same way for the generic calling convention.

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Operator precedence</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Operator precedence

In expressions, the operator with the highest precedence is always computed first.

Unary operators

Unary operators have the higher precedence than other operators, and between unary operators the operator closest to the actual value has the highest precedence. Post-operators have higher precedence than pre-operators.

This list shows the available unary operators.

:: 	scope resolution operator

[] 	indexing operator

++ -- 	post increment and decrement

. 	member access

++ -- 	pre increment and decrement

not ! 	logical not

+ - 	unary positive and negative

~ 	bitwise complement

@  	handle of

Binary and ternary operators

This list shows the dual and ternary operator precedence in decreasing order.

** 	exponent

* / % 	multiply, divide, and modulo

+ - 	add and subtract

<< >> >>> 	left shift, right shift, and arithmetic right shift

& 	bitwise and

^ 	bitwise xor

| 	bitwise or

<= < >= > 	comparison

== != is !is xor ^^ 	equality, identity, and logical exclusive or

and && 	logical and

or || 	logical or

?: 	condition

= += -= *= /= %= **= &=

 |= ^= <<= >>= >>>= 	assignment and compound assignments

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Overview</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Overview

AngelScript is structured around an engine where the application should register the functions, properties, and even types, that the scripts will be able to use. The scripts are then compiled into modules, where the application may have one or more modules, depending on the need of the application. The application can also expose a different interface to each module through the use of access profiles. This is especially useful when the application works with multiple types of scripts, e.g. GUI, AI control, etc.

As the scripts are compiled into bytecode AngelScript also provides a virtual machine, also known as a script context, for executing the bytecode. The application can have any number of script context at the same time, though most applications will probably only need one. The contexts support suspending the execution and then resuming it, so the application can easily implement features such as concurrent scripts and co-routines. The script context also provides an interface for extracting run-time information, useful for debugging scripts.

The script language is based on the well known syntax of C++ and more modern languages such as Java, C#, and D. Anyone with some knowledge of those languages, or other script languages with similar syntax, such as Javascript and ActionScript, should feel right at home with AngelScript. Contrary to most script languages, AngelScript is a strongly typed language, which permits faster execution of the code and smoother interaction with the host application as there will be less need for runtime evaluation of the true type of values.

The memory management in AngelScript is based on reference counting with an incremental garbage collector for detecting and freeing objects with circular references. This provides for a controlled environment without application freezes as the garbage collector steps in to free up memory.

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Registering a reference type</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Registering a reference type

The basic reference type should be registered with the following behaviours: asBEHAVE_FACTORY, asBEHAVE_ADDREF, and asBEHAVE_RELEASE.

// Registering the reference type

r = engine->RegisterObjectType("ref", 0, asOBJ_REF); assert( r >= 0 );

asOBJ_REF

@ asOBJ_REF

A reference type.

Definition: angelscript.h:254

See also

The any add-on for an example of a reference type.

Garbage collected objects, Class hierarchies, Registering a scoped reference type, and Registering a single-reference type for more advanced types.

Factory function

The factory function is the one that AngelScript will use to instantiate objects of this type when a variable is declared. It is responsible for allocating and initializing the object memory.

The default factory function doesn't take any parameters and should return an object handle for the new object. Make sure the object's reference counter is accounting for the reference being returned by the factory function, so that the object is properly released when all references to it are removed.

CRef::CRef()

{

    // Let the constructor initialize the reference counter to 1

    refCount = 1;

}

CRef *Ref_Factory()

{

    // The class constructor is initializing the reference counter to 1

    return new CRef();

}

// Registering the factory behaviour

r = engine->RegisterObjectBehaviour("ref", asBEHAVE_FACTORY, "ref@ f()", asFUNCTION(Ref_Factory), asCALL_CDECL); assert( r >= 0 );

asCALL_CDECL

@ asCALL_CDECL

A cdecl function.

Definition: angelscript.h:230

asFUNCTION

#define asFUNCTION(f)

Returns an asSFuncPtr representing the function specified by the name.

Definition: angelscript.h:685

asBEHAVE_FACTORY

@ asBEHAVE_FACTORY

Factory.

Definition: angelscript.h:366

You may also register factory functions that take parameters, which may then be used when initializing the object.

The factory function must be registered as a global function, but can be implemented as a static class method, common global function, or a global function following the generic calling convention.

Even though a factory function returns an object handle, it must not return a null handle unless it also sets an exception to signal that the instantiation of the object failed.

The behaviour is undefined if a factory function returns null without setting an exception.

See also List factory function.

Addref and release behaviours

void CRef::Addref()

{

    // Increase the reference counter

    refCount++;

}

void CRef::Release()

{

    // Decrease ref count and delete if it reaches 0

    if( --refCount == 0 )

        delete this;

}

// Registering the addref/release behaviours

r = engine->RegisterObjectBehaviour("ref", asBEHAVE_ADDREF, "void f()", asMETHOD(CRef,AddRef), asCALL_THISCALL); assert( r >= 0 );

r = engine->RegisterObjectBehaviour("ref", asBEHAVE_RELEASE, "void f()", asMETHOD(CRef,Release), asCALL_THISCALL); assert( r >= 0 );

asCALL_THISCALL

@ asCALL_THISCALL

A thiscall class method.

Definition: angelscript.h:236

asMETHOD

#define asMETHOD(c, m)

Returns an asSFuncPtr representing the class method specified by class and method name.

Definition: angelscript.h:750

asBEHAVE_ADDREF

@ asBEHAVE_ADDREF

AddRef.

Definition: angelscript.h:370

asBEHAVE_RELEASE

@ asBEHAVE_RELEASE

Release.

Definition: angelscript.h:372

If the instances of this object will be shared between multiple threads, remember to guarantee that the reference counter is thread safe by making the increments and decrements with atomic instructions.

See also

Multithreading

Reference types without reference counting

If the application provides its own memory management that isn't based on reference counting, then it is possible to register the type without the addref and release behaviours if the flag, asOBJ_NOCOUNT is informed in the call to RegisterObjectType, i.e.

// Registering the reference type

r = engine->RegisterObjectType("ref", 0, asOBJ_REF | asOBJ_NOCOUNT); assert( r >= 0 );

asOBJ_NOCOUNT

@ asOBJ_NOCOUNT

The type doesn't use reference counting. Only valid for reference types.

Definition: angelscript.h:322

Without the addref and release behaviours the application must be careful to not destroy any objects that may potentially still be referenced by the script engine, e.g. in a global variable, or other location.

Unless the objects are guaranteed to stay alive as long as the script engine is instantiated, you may want to consider disabling global variables with engine property asEP_DISALLOW_GLOBAL_VARS. This will make it much easier for the application to know where references to the objects are kept. An alternative to disabling all global variables, is to selectively disallow only the global variables, that can eventually store a reference to the object type. This can be done by enumerating the compiled global variables after script has been built and giving an error to the user in case he includes a variable he shouldn't.

List factory function

The list factory function is a special factory function that can be registered to allow a type to be created from an initialization list. The list factory function takes only a single pointer as argument. AngelScript will pass a pointer to the initialization list buffer in that argument. The buffer will contain all the values necessary to create and initialize the object.

In order for the script engine to know what information must be placed in the buffer the application must provide the list pattern when registering the list factory. The list pattern is declared with a special syntax involving datatypes and the following tokens: {, }, ?, repeat, and repeat_same.

The tokens { } are used to declare that the list pattern expects a list of values or a sublist of values. The repeat token is used to signal that the next type or sub list can be repeated 0 or more times. The repeat_same token is similar to repeat except that it also tells the compiler that every time the same list is repeated it should have the same length. Any data type can be used in the list pattern, as long as it can be passed by value. When a variable type is desired the token ? can be used.

Here's a couple of examples for registering list factories with list patterns:

// The array type can be initialized for example with: intarray a = {1,2,3};

engine->RegisterObjectBehaviour("intarray", asBEHAVE_LIST_FACTORY,

  "intarray@ f(int &in) {repeat int}", ...);

// The dictionary type can be initialized with: dictionary d = {{'a',1}, {'b',2}, {'c',3}};

engine->RegisterObjectBehaviour("dictionary", asBEHAVE_LIST_FACTORY,

  "dictionary @f(int &in) {repeat {string, ?}}", ...);

// The grid type can be initialized with: grid a = {{1,2},{3,4}};

engine->RgisterObjectBehaviour("grid", asBEHAVE_LIST_FACTORY,

  "grid @f(int &in) {repeat {repeat_same int}}", ...);

asBEHAVE_LIST_FACTORY

@ asBEHAVE_LIST_FACTORY

Factory used exclusively for initialization lists.

Definition: angelscript.h:368

The list buffer passed to the factory function will be populated using the following rules:

Whenever the pattern expects a repeat, the buffer will contain a 32bit integer with the number of repeated values that will come afterwards

Whenever the pattern expects a ?, then the buffer will contain a 32bit integer representing the typeId of the value that comes after.

Whenever the pattern expects a reference type, the buffer will contain a pointer to the object

Whenever the pattern expects a value type, the buffer will contain the object itself

All values in the buffer will be aligned to a 32bit boundary, unless the size of the value placed in the buffer is smaller than 32bits.

See also

array template object and dictionary object for example implementations of list factories.

Registering an uninstantiable reference type

Sometimes it may be useful to register types that cannot be instantiated by the scripts, yet can be interacted with. You can do this by registering the type as a normal reference type, but omit the registration of the factory behaviour. You can later register global properties, or functions that allow the scripts to access objects created by the application via object handles.

This would be used when the application has a limited number of objects available and doesn't want to create new ones. For example singletons, or pooled objects.

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Registering object methods</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Registering object methods

Class methods are registered with the RegisterObjectMethod call. Both non-virtual and virtual methods are registered the same way.

Static class methods are in reality global functions so those should be registered as global functions and not as object methods.

// Register a class method

void MyClass::ClassMethod()

{

  // Do something

}

r = engine->RegisterObjectMethod("mytype", "void ClassMethod()", asMETHOD(MyClass,ClassMethod), asCALL_THISCALL); assert( r >= 0 );

asCALL_THISCALL

@ asCALL_THISCALL

A thiscall class method.

Definition: angelscript.h:236

asMETHOD

#define asMETHOD(c, m)

Returns an asSFuncPtr representing the class method specified by class and method name.

Definition: angelscript.h:750

It is also possible to register a global function that takes a pointer to the object as a class method. This can be used to extend the functionality of a class when accessed via AngelScript, without actually changing the C++ implementation of the class.

// Register a global function as an object method

void MyClass_MethodWrapper(MyClass *obj)

{

  // Access the object

  obj->DoSomething();

}

r = engine->RegisterObjectMethod("mytype", "void MethodWrapper()", asFUNCTION(MyClass_MethodWrapper), asCALL_CDECL_OBJLAST); assert( r >= 0 );

asCALL_CDECL_OBJLAST

@ asCALL_CDECL_OBJLAST

A cdecl function that takes the object pointer as the last parameter.

Definition: angelscript.h:238

asFUNCTION

#define asFUNCTION(f)

Returns an asSFuncPtr representing the function specified by the name.

Definition: angelscript.h:685

See also

Registering a function for more details on how the macros work.

Composite members

If the application class that is being registered uses composition, then it is possible to register the methods of the composite members like this:

struct Component

{

  int DoSomething();

};

struct Object

{

  Component *comp;

};

r = engine->RegisterObjectMethod("object", "int DoSomething()", asMETHOD(Component, DoSomething), asCALL_THISCALL, 0, asOFFSET(Object, comp), true); assert( r >= 0 );

asOFFSET

#define asOFFSET(s, m)

Returns the offset of an attribute in a struct.

Definition: angelscript.h:682

The last parameter indicates that to reach the composite member it is necessary to dereference the pointer. If the composite member is inlined, then the parameter should be set to false.

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Registering object properties</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Registering object properties

Class member variables can be registered so that they can be directly accessed by the script without the need for any method calls.

struct MyStruct

{

  int a;

};

r = engine->RegisterObjectProperty("mytype", "int a", asOFFSET(MyStruct,a)); assert( r >= 0 );

asOFFSET

#define asOFFSET(s, m)

Returns the offset of an attribute in a struct.

Definition: angelscript.h:682

If a class member is indirect, i.e. the class holds a pointer to the member that is allocated on the heap, then it is possible to registered the property using & to tell the script engine that an dereference is needed to access the member.

struct MyStruct

{

  OtherStruct *a;

};

r = engine->RegisterObjectProperty("mytype", "othertype &a", asOFFSET(MyStruct,a)); assert( r >= 0 );

Of course, the application must make sure the pointer is valid during the whole time that it may be accessed from the script.

Composite members

If the application class that is being registered uses composition, then it is possible to register the properties of the composite members like this:

struct Component

{

  int a;

};

struct Object

{

  Component *comp;

};

r = engine->RegisterObjectProperty("object", "comp_a", asOFFSET(Component, a), asOFFSET(Object, comp), true); assert( r >= 0 );

The last parameter indicates that to reach the property of the composite member it is necessary to dereference the pointer. If the composite member is inlined, then the parameter should be set to false.

Property accessors

It is also possible to expose properties through property accessors, which are a pair of class methods with prefixes 'get_' and 'set_' and the function decorator 'property' for getting and setting the property value. These methods should be registered with RegisterObjectMethod. This is especially useful when the offset of the property cannot be determined, or if the type of the property is not registered in the script and some translation must occur, i.e. from char* to string.

If the application class contains a C++ array as a member, it may be advantageous to expose the array through indexed property accessors rather than attempting to matching the C++ array type to a registered type in AngelScript. To do this you can create a couple of simple proxy functions that will translate to the array access.

Note

The behaviour of virtual properties can be customized with the engine property asEP_PROPERTY_ACCESSOR_MODE.

struct MyStruct

{

  int array[16];

};

// Write a couple of proxy

int MyStruct_get_array(unsigned int idx, MyStruct *o)

{

  if( idx >= 16 ) return 0;

  return o->array[idx];

}

void MyStruct_set_array(unsigned int idx, int value, MyStruct *o)

{

  if( idx >= 16 ) return;

  o->array[idx] = value;

}

// Register the proxy functions as member methods

r = engine->RegisterObjectMethod("mytype", "int get_array(uint) property", asFUNCTION(MyStruct_get_array), asCALL_CDECL_OBJLAST); assert( r >= 0 );

r = engine->RegisterObjectMethod("mytype", "void set_array(uint, int) property", asFUNCTION(MyStruct_set_array), asCALL_CDECL_OBJLAST); assert( r >= 0 );

asCALL_CDECL_OBJLAST

@ asCALL_CDECL_OBJLAST

A cdecl function that takes the object pointer as the last parameter.

Definition: angelscript.h:238

asFUNCTION

#define asFUNCTION(f)

Returns an asSFuncPtr representing the function specified by the name.

Definition: angelscript.h:685

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Registering operator behaviours</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Registering operator behaviours

In order for AngelScript to know how to work with the application registered types, it is necessary to register some behaviours, for example for memory management.

The memory management behaviours are described with the registration of reference types and value types.

Other advanced behaviours are described with the advanced types.

Most behaviours are implemented as ordinary class methods, except with specific names that the compiler can understand.

Operator overloads

In AngelScript all operator overloads are implemented as class methods with predefined names, which is different from C++ where both class methods and global functions may be used. Especially the dual operators, i.e. those that take two operands, usually has one implemented as a class method, and a global function for the reverse order.

To register C++ operator overloads you'll use the methods described in How to get the address of the application function or method.

Example on how to register operator overloads

class MyClass

{

  ...

  // The operator 'MyClass - int' has been implemented as a method

  MyClass operator-(int) const;

  // The operator 'int - MyClass' has been implemented as a global function

  static MyClass operator-(int, const MyClass &);

}

void RegisterMyClass(asIScriptEngine *engine)

{

  // Registering the operator 'MyClass - int'

  engine->RegisterObjectMethod("MyClass", "MyClass opSub(int) const", asMETHODPR(MyClass, operator-, (int) const, MyClass), asCALL_THISCALL);

  // Registering the operator 'int - MyClass'

  engine->RegisterObjectMethod("MyClass", "MyClass opSub_r(int) const", asFUNCTIONPR(operator-, (int, const MyClass &), MyClass), asCALL_CDECL_OBJLAST);

}

asFUNCTIONPR

#define asFUNCTIONPR(f, p, r)

Returns an asSFuncPtr representing the function specified by the name, parameter list,...

Definition: angelscript.h:694

asCALL_CDECL_OBJLAST

@ asCALL_CDECL_OBJLAST

A cdecl function that takes the object pointer as the last parameter.

Definition: angelscript.h:238

asCALL_THISCALL

@ asCALL_THISCALL

A thiscall class method.

Definition: angelscript.h:236

asMETHODPR

#define asMETHODPR(c, m, p, r)

Returns an asSFuncPtr representing the class method specified by class, method name,...

Definition: angelscript.h:752

asIScriptEngine

The engine interface.

Definition: angelscript.h:1102

asIScriptEngine::RegisterObjectMethod

virtual int RegisterObjectMethod(const char *obj, const char *declaration, const asSFuncPtr &funcPointer, asDWORD callConv, void *auxiliary=0, int compositeOffset=0, bool isCompositeIndirect=false)=0

Registers a method for the object type.

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: What can be registered</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

What can be registered

AngelScript requires the application developer to register the interface that the scripts should use to interact with anything outside the script itself.

It's possible to register global functions and global properties that can be used directly by the scripts.

For more complex scripts it may be useful to register new object types to complement the built-in data types.

AngelScript doesn't have a built-in string type as there is no de-facto standard for string types in C++. Instead AngelScript permits the application to register its own preferred string type, and a string factory that the script engine will use to instanciate the strings.

There is also no default built-in array type as this too is something that most developers may want to have their own version of. The array type is registered as a template, which is then set as the default array type. A standard array add-on is provided for those that do not want to implement their own array type.

Class interfaces can be registered if you want to guarantee that script classes implement a specific set of class methods. Interfaces can be easier to use when working with script classes from the application, but they are not necessary as the application can easily enumerate available methods and properties even without the interfaces.

Function definitions can be registered when you wish to allow the script to pass function pointers to the application, e.g. to implement callback routines.

Enumeration types and typedefs can also be registered to improve readability of the scripts.

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Registering the application interface</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Registering the application interface

What can be registered

Registering a function

Registering global properties

Registering an object type

Advanced application interface

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
var doc_register_api_topic =
[
    [ "What can be registered", "doc_register_api.html", null ],
    [ "Registering a function", "doc_register_func.html", [
      [ "How to get the address of the application function or method", "doc_register_func.html#doc_register_func_1", null ],
      [ "Calling convention", "doc_register_func.html#doc_register_func_2", null ],
      [ "A little on type differences", "doc_register_func.html#doc_register_func_3", null ],
      [ "Virtual inheritance is not supported", "doc_register_func.html#doc_register_func_4", null ]
    ] ],
    [ "Registering global properties", "doc_register_prop.html", null ],
    [ "Registering an object type", "doc_register_type.html", "doc_register_type" ],
    [ "Advanced application interface", "doc_advanced_api.html", "doc_advanced_api" ]
];


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Registering global properties</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Registering global properties

By registering global properties with the script engine you can allow the scripts to inspect and/or modify variables within the application directly, without the need to write special functions to do this.

To register the property, you just need to call the RegisterGlobalProperty method, passing the declaration and a pointer to the property. Remember that the registered property must stay alive as long as its registration is valid in the engine.

Make sure you give the correct pointer to AngelScript. The pointer should be to value that the declaration refers to, i.e. if the declaration is an integer then the pointer should be to the integer value, if the declaration is an object handle then the pointer should be to the pointer to the object, etc. Unfortunately there is no way for AngelScript to validate that the pointer is correct, so if the wrong pointer is given, you will only detect it at runtime when seeing unexpected behaviours from the application.

// Variables that should be accessible through the script.

int      g_number       = 0;

CObject *g_object       = 0;

Vector3  g_vector       = {0,0,0};

bool     g_readOnlyFlag = false;

// A function to register the global properties.

void RegisterProperties(asIScriptEngine *engine)

{

    int r;

    // Register a primitive property that can be read and written to from the script.

    r = engine->RegisterGlobalProperty("int g_number", &g_number); assert( r >= 0 );

    // Register variable where the script can store a handle to a CObject type.

    // Assumes that the CObject type has been registered with the engine already as a reference type.

    r = engine->RegisterGlobalProperty("CObject @g_object", &g_object); assert( r >= 0 );

    // Register a 3D vector variable.

    // Assumes that the Vector3 type has been registered already as a value type.

    r = engine->RegisterGlobalProperty("Vector3 g_vector", &g_vector); assert( r >= 0 );

    // Register a boolean flag that can be read, but not modified by the script.

    r = engine->RegisterGlobalProperty("const bool g_readOnlyFlag", &g_readOnlyFlag); assert( r >= 0 );

}

asIScriptEngine

The engine interface.

Definition: angelscript.h:1102

asIScriptEngine::RegisterGlobalProperty

virtual int RegisterGlobalProperty(const char *declaration, void *pointer)=0

Registers a global property.

It is also possible to expose properties through property accessors, which are a pair of functions with the prefixes 'get_' and 'set_' and the function decorator 'property' for getting and setting the property value. These functions should be registered with RegisterGlobalFunction. This is especially useful when the offset of the property cannot be determined, or if the type of the property is not registered in the script and some translation must occur, i.e. from char* to string.

Note

The behaviour of virtual properties can be customized with the engine property asEP_PROPERTY_ACCESSOR_MODE.

See also

Registering an object type

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Registering an object type</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Registering an object type

The are two principal paths to take when registering a new type, either the type is a reference type that is located in dynamic memory, or the type is a value type that is located on the stack or locally as members of other objects. A reference type support object handles (unless restricted by application) but cannot be passed by value to application registered functions, a value type doesn't support handles and can be passed by value or reference to application registered functions.

There is no given rule when to use one or the other, but in general you'll use reference types when the type must be able to outlive the scope in which it is created, and value types when the type is normally used to perform quick calculations after which the object can be discarded. If the type is large or complex, then it is likely it should be a reference type.

Registering a reference type

Registering a value type

Registering operator behaviours

Registering object methods

Registering object properties

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
var doc_register_type =
[
    [ "Registering a reference type", "doc_reg_basicref.html", [
      [ "Factory function", "doc_reg_basicref.html#doc_reg_basicref_1", null ],
      [ "Addref and release behaviours", "doc_reg_basicref.html#doc_reg_basicref_2", null ],
      [ "Reference types without reference counting", "doc_reg_basicref.html#doc_reg_nocount", null ],
      [ "List factory function", "doc_reg_basicref.html#doc_reg_basicref_4", null ],
      [ "Registering an uninstantiable reference type", "doc_reg_basicref.html#doc_reg_noinst", null ]
    ] ],
    [ "Registering a value type", "doc_register_val_type.html", [
      [ "Constructor and destructor", "doc_register_val_type.html#doc_reg_val_1", null ],
      [ "Value types and native calling conventions", "doc_register_val_type.html#doc_reg_val_2", [
        [ "For compilers that don't support C++11", "doc_register_val_type.html#doc_reg_val_2_nocpp11", null ]
      ] ],
      [ "List constructor", "doc_register_val_type.html#doc_reg_val_3", null ]
    ] ],
    [ "Registering operator behaviours", "doc_reg_opbeh.html", [
      [ "Operator overloads", "doc_reg_opbeh.html#doc_reg_opbeh_1", null ]
    ] ],
    [ "Registering object methods", "doc_reg_objmeth.html", [
      [ "Composite members", "doc_reg_objmeth.html#doc_reg_objmeth_composite", null ]
    ] ],
    [ "Registering object properties", "doc_reg_objprop.html", [
      [ "Composite members", "doc_reg_objprop.html#doc_reg_objprop_composite", null ],
      [ "Property accessors", "doc_reg_objprop.html#doc_reg_objprop_accessor", null ]
    ] ]
];


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Reserved keywords and tokens</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Reserved keywords and tokens

These are the keywords that are reserved by the language, i.e. they can't be used by any script defined identifiers. Remember that the host application may reserve additional keywords that are specific to that application.

 and

 abstract*

 auto

 bool

 break

 case

 cast

 catch

 class

 const

 continue

 default

 do

  	 double

 else

 enum

 explicit*

 external*

 false

 final*

 float

 for

 from*

 funcdef

 function*

 get*

  	 if

 import

 in

 inout

 int

 interface

 int8

 int16

 int32

 int64

 is

 mixin

 namespace

  	 not

 null

 or

 out

 override*

 private

 property*

 protected

 return

 set*

 shared*

 super*

 switch

  	 this*

 true

 try

 typedef

 uint

 uint8

 uint16

 uint32

 uint64

 void

 while

 xor

* Not really a reserved keyword, but is recognized by the compiler as a built-in keyword.

These are the non-alphabetical tokens that are also used in the language syntax.

 *

 **

 /

 %

 +

 -

 <=

 <

 >=

 >

 (

 	 )

 ==

 !=

 ?

 :

 =

 +=

 -=

 *=

 /=

 %=

 	 **=

 ++

 --

 &

 ,

 {

 }

 ;

 |

 ^

 	 ~

 <<

 >>

 >>>

 &=

 |=

 ^=

 <<=

 >>=

 >>>=

 	 .

 &&

 ||

 !

 [

 ]

 ^^

 @

 !is

 ::

Other than the above tokens there are also numerical, string, identifier, and comment tokens.

123456789
123.123e123
123.123e123f
0x1234FEDC
0d123987
0o1276
0b1010
'abc'
"abc"
"""heredoc"""
_Abc123
//
/*
*/

The characters space (32), tab (9), carriage return (13), line feed (10), and the UTF8 byte-order-mark (U+FEFF) are all recognized as whitespace.

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Samples</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Samples

This page gives a brief description of the samples that you'll find in the /sdk/samples/ folder.

Tutorial

Concurrent scripts

Console

Co-routines

Events

Include directive

Generic compiler

Game

Command line runner

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
var doc_samples =
[
    [ "Tutorial", "doc_samples_tutorial.html", null ],
    [ "Concurrent scripts", "doc_samples_concurrent.html", null ],
    [ "Console", "doc_samples_console.html", null ],
    [ "Co-routines", "doc_samples_corout.html", null ],
    [ "Events", "doc_samples_events.html", null ],
    [ "Include directive", "doc_samples_incl.html", null ],
    [ "Generic compiler", "doc_samples_asbuild.html", null ],
    [ "Game", "doc_samples_game.html", null ],
    [ "Command line runner", "doc_samples_asrun.html", "doc_samples_asrun" ]
];


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Generic compiler</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Generic compiler

Path: /sdk/samples/asbuild/

This sample shows how a generic bytecode compiler can be built to provide offline compilation of scripts. It takes as input a configuration file that defines the application interface, registers it using dummy functions and properties, then it compiles the script and saves the bytecode to a file on disk.

The configuration file should preferably be created automatically by calling the WriteConfigToFile helper function. This function should be called from the application that will execute the bytecode, after the application interface has been fully registered.

Pre-compiled byte code

Script builder

asIScriptEngine::SetMessageCallback

asEP_INIT_GLOBAL_VARS_AFTER_BUILD

asIScriptEngine::ParseToken

asIScriptModule::SaveByteCode

asIBinaryStream

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Command line runner</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Command line runner

Path: /sdk/samples/asrun/

This samples gives a very basic command line runner for AngelScripts.

It also implements a fully functional command line debugger, with support for setting breakpoints, stepping through the code, examining variables, etc.

Debugging scripts

Debugger

string object

array template object

dictionary object

file object

filesystem object

datetime object

Context manager

Script builder

Exception routines

asIScriptEngine::SetContextCallbacks

System functions

Implementing a #pragma callback

See also

asrun manual

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
var doc_samples_asrun =
[
    [ "asrun manual", "doc_samples_asrun_manual.html", [
      [ "Usage", "doc_samples_asrun_manual.html#doc_samples_asrun_usage", null ],
      [ "Scripts", "doc_samples_asrun_manual.html#doc_samples_asrun_script", null ],
      [ "How to debug scripts", "doc_samples_asrun_manual.html#doc_samples_asrun_debug", null ]
    ] ]
];


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: asrun manual</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

asrun manual

asrun is a simple command-line tool that supports executing AngelScript files directly in order to perform simple batch tasks. The API provided by the tool allow the script to interact with the system to read and write files, and execute other system commands.

On Windows it can be associated, for example with the file extension .as, to allow scripts to be executed directly from the file browser with a double click. This makes it a handy tool even without a terminal for command-line input. On Linux and UNIX based systems the shebang interpreter directive can be added as the first line on the script to make the script files executable.

Usage

asrun [-d] <script file> [<args>]
 -d             inform if the script should be runned with debug
 <script file>  is the script file that should be runned
 <args>         zero or more args for the script

These usage instructions are also presented if the tool is executed without any arguments.

Scripts

As entry point for executing the scripts, asrun looks for one of the functions int main() or void main(). If neither of these functions are found an error will be reported.

The scripts can use the full set of the script language and standard library described in the script language section of this manual.

The script file informed as input on the command line may include additional files with the include directive #include "<file name>", so that the script files can be better organized and common logic shared between multiple scripts.

How to debug scripts

To run a script with the debugger, either add the command line argument -d or include #pragma debug in the script. When this is done, the debugger will show a prompt like this:

Debugging, waiting for commands. Type 'h' for help.
[dbg]>

This will then let you set up breakpoints, step through the code, inspect variables, etc. Type h on the prompt to get the list of commands available.

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Concurrent scripts</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Concurrent scripts

Path: /sdk/samples/concurrent/

This sample shows how to execute two or more long running scripts concurrently. The scripts voluntarily hand over the control to the next script in the queue by calling the function sleep().

Context manager

Multiple scripts running in parallel

sleep()

Strings

Registered global functions

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Console</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Console

Path: /sdk/samples/console/

This sample implements a simple interactive console, which lets the user type in commands and also evaluate simple script statements to manipulate the application.

The user is also able to define new variables and functions from the command line. These functions can then be executed to perform automated tasks.

ExecuteString

CompileFunction, CompileGlobalVar, RemoveFunction, RemoveGlobalVar

Enumerate global functions and variables

Strings

Registered global functions and properties

Special function _grab() with overloads to receive and print resulting value from script statements

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Co-routines</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Co-routines

Path: /sdk/samples/coroutine/

This sample shows how co-routines can be implemented with AngelScript. Co-routines are threads that can be created from the scripts, and that work together by voluntarily passing control to each other by calling yield().

Context manager

Co-routines created from the scripts with variable parameter structure.

string object

Registered global functions

Handling the variable argument type

Passing arguments to script functions

dictionary object

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Events</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Events

Path: /sdk/samples/events/

This sample has the script engine execute a long running script. The script execution is regularly interrupted by the application so that keyboard events can be processed, which execute another short script before resuming the execution of the main script. The event handling scripts change the state of the long running script.

LineCallback() function which suspends execution when the time is up

string object

Registered global functions

Scripted event handlers

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Game</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Game

Path: /sdk/samples/game/

This sample shows one way of integrating the scripting library in a game engine. It is a simple game where the player is trying to avoid getting eaten by zombies. Each game object type has it's own script that controls its behaviour, these are loaded independently into separately modules.

asIScriptModule

asITypeInfo::SetUserData

Interfaces

Script classes

Script builder

ref object

Shared script entities

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Include directive</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Include directive

Path: /sdk/samples/include/

This sample shows how to implement a very simple preprocessor to add support for the #include directive, which allow the script writer to reuse common script code. The preprocessor simply adds the included scripts as multiple script sections, which is ok as AngelScript is able to resolve global declarations independently of their order. The preprocessor also makes sure that a script file is only included once, so the script writer doesn't have to take extra care to avoid multiple includes or even complicated circular includes.

Script builder

LineCallback() functions which aborts execution when the time is up

Processing the #include directive

Circular #includes are resolved automatically

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Tutorial</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Tutorial

Path: /sdk/samples/tutorial/

This sample was written with the intention of explaining the basics of AngelScript, that is, how to configure the engine, load and compile a script, and finally execute a script function with parameters and return value.

asIScriptEngine::SetMessageCallback

LineCallback() function which aborts execution when the time is up

Strings

Registered global functions

Script function parameters and return value

Retrieving information about script exceptions

asIScriptGeneric for when the library doesn't support native calling convention

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: The script language</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

The script language

This is the reference documentation for the AngelScript scripting language.

Global entities

Statements

Expressions

Data types

Functions

Script classes

Object handles

Shared script entities

Operator precedence

Reserved keywords and tokens

Script language grammar

Standard library

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6


code:
var doc_script =
[
    [ "Global entities", "doc_script_global.html", "doc_script_global" ],
    [ "Statements", "doc_script_statements.html", [
      [ "Variable declarations", "doc_script_statements.html#variable", null ],
      [ "Expression statement", "doc_script_statements.html#expression", null ],
      [ "Conditions: if / if-else / switch-case", "doc_script_statements.html#if", null ],
      [ "Loops: while / do-while / for", "doc_script_statements.html#while", null ],
      [ "Loop control: break / continue", "doc_script_statements.html#break", null ],
      [ "Return statement", "doc_script_statements.html#return", null ],
      [ "Statement blocks", "doc_script_statements.html#block", null ],
      [ "Try-catch blocks", "doc_script_statements.html#try", null ]
    ] ],
    [ "Expressions", "doc_expressions.html", [
      [ "Assignments", "doc_expressions.html#assignment", null ],
      [ "Function call", "doc_expressions.html#function", null ],
      [ "Math operators", "doc_expressions.html#math", null ],
      [ "Bitwise operators", "doc_expressions.html#bits", null ],
      [ "Compound assignments", "doc_expressions.html#compound", null ],
      [ "Logic operators", "doc_expressions.html#logic", null ],
      [ "Equality comparison operators", "doc_expressions.html#equal", null ],
      [ "Relational comparison operators", "doc_expressions.html#relation", null ],
      [ "Identity comparison operators", "doc_expressions.html#identity", null ],
      [ "Increment operators", "doc_expressions.html#increment", null ],
      [ "Indexing operator", "doc_expressions.html#opindex", null ],
      [ "Conditional expression", "doc_expressions.html#condition", null ],
      [ "Member access", "doc_expressions.html#member", null ],
      [ "Handle-of", "doc_expressions.html#handle", null ],
      [ "Parenthesis", "doc_expressions.html#parenthesis", null ],
      [ "Scope resolution", "doc_expressions.html#scope", null ],
      [ "Type conversions", "doc_expressions.html#conversion", null ],
      [ "Anonymous objects", "doc_expressions.html#anonobj", null ]
    ] ],
    [ "Data types", "doc_datatypes.html", "doc_datatypes" ],
    [ "Functions", "doc_script_func.html", "doc_script_func" ],
    [ "Script classes", "doc_script_class.html", "doc_script_class" ],
    [ "Object handles", "doc_script_handle.html", [
      [ "General usage", "doc_script_handle.html#doc_script_handle_1", null ],
      [ "Object life times", "doc_script_handle.html#doc_script_handle_2", null ],
      [ "Object relations and polymorphing", "doc_script_handle.html#doc_script_handle_3", null ],
      [ "Const handles", "doc_script_handle.html#doc_script_handle_4", null ]
    ] ],
    [ "Shared script entities", "doc_script_shared.html", [
      [ "How to declare shared entities", "doc_script_shared.html#doc_script_shared_1", null ],
      [ "External shared entities", "doc_script_shared.html#doc_script_shared_external", null ],
      [ "What can be shared", "doc_script_shared.html#doc_script_shared_2", null ]
    ] ],
    [ "Operator precedence", "doc_operator_precedence.html", [
      [ "Unary operators", "doc_operator_precedence.html#unary", null ],
      [ "Binary and ternary operators", "doc_operator_precedence.html#binary", null ]
    ] ],
    [ "Reserved keywords and tokens", "doc_reserved_keywords.html", null ],
    [ "Script language grammar", "doc_script_bnf.html", null ],
    [ "Standard library", "doc_script_stdlib.html", "doc_script_stdlib" ]
];


code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Anonymous functions</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

AngelScript

          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Loading...

Searching...

No Matches

Anonymous functions

Anonymous functions, or lambdas as they are sometimes called, are functions that are declared locally for use with function handles.

The following is a quick demonstration on how to use anonymous functions.

  funcdef bool CMP(int first, int second);

  void main()
  {
    int valueA = 1, valueB = 2;

    bool result1 = func(valueA, valueB, function(a,b){ return a == b; });
    bool result2 = func(valueA, valueB, function(a,b){ return a != b; });
  }

  bool func(int a, int b, CMP @f)
  {
    return f(a,b);
  }

The anonymous function takes on the signature of the function handle it is assigned to, so the type of the arguments and the return type doesn't have to be explicitly declared.

It is not yet possible for anonymous functions to access variables declared in the same scope as the function, i.e. they cannot be used as closures.

If there are multiple matching uses for the anonymous function it will be necessary to explicitly inform the parameter types, so the ambiguity can be resolved.

  funcdef void A(int);
  funcdef void B(float);
  void func(A@) {}
  void func(B@) {}

  void main()
  {
    // Explicitly specify the type to tell the compiler that A is wanted
    func(function(int a) {});
  }

Generated on Sun May 21 2023 10:12:40 for AngelScript by  1.9.6