Skip to content

Variables Scope

This section needs improvements.

Certain parts of this section are poorly worded, poorly illustrated and might be confusing. Those will be updated at some point.

Variable scope refers to the region of script from where a variable can be accessed. There are a few different scopes in XS:

  • File scope.
  • Global scope.
  • Local scope.

1. File Scope

Variables defined in a file, outside of any function or rule, are file scoped. They can be accessed from any function or rule in the same file, provided that such function or rule is defined after the variable's definition. They cannot be accessed from any other file.

File scoped variables.

Structure of the AI folder
1
2
├── Age3AI.xs
├── file-scope-test.xs
file-scope-test.xs
1
2
3
4
5
6
7
int foo = 0;

void scopeTest(void)
{
    // foo is accessible here.
    foo = 10;
}
Age3AI.xs
1
2
3
4
5
6
7
include "./file-scope-test.xs";

void main(void)
{
    // foo cannot be accessed here.
    foo = 20; // This will cause an error.
}

Lifetime

File-scoped variables keep their values between function calls:

Lifetime of file-scoped variables.

Structure of the AI folder
1
2
├── Age3AI.xs
├── file-scope-test.xs
file-scope-test.xs
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
// In the beginning, the value of foo is 0.
int foo = 0;

void function1(void)
{
    // When this function is called, the value of foo
    // becomes -1.
    foo = -1;
}

void function2(void)
{
    // When this function is called, the value of foo
    // becomes 10;
    foo = 10;
}

void echoFoo(void)
{
    aiEcho("foo = " + foo);
}
Age3AI.xs
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
include "./file-scope-test.xs";

void main(void)
{
    echoFoo();
    function1();
    echoFoo();
    function2();
    echoFoo();
}

2. Global Scope

Variables defined in a file, outside of any function or rule, and marked with the extern keyword, are global scoped. They can be accessed from any function or rule in any file where the file containing the variable is included, provided that such function or rule is defined after the variable's definition.

These variables are commonly referred to as global variables.

Global scoped variables.

Structure of the AI folder
1
2
├── Age3AI.xs
├── global-scope-test.xs
global-scope-test.xs
1
2
3
4
5
6
7
extern int foo = 0;

void scopeTest(void)
{
    // foo is accessible here.
    foo = 10;
}
Age3AI.xs
1
2
3
4
5
6
7
include "./global-scope-test.xs";

void main(void)
{
    // foo is accessible here.
    foo = 20;
}

Lifetime

Like file-scoped variables, global variables also keep their values between function calls.

3. Local Scope

Variables defined inside a function are local to that function. They can only be accessed from within that function.

These variables are commonly referred to as local variables.

There are two types of local variables:

  • non-static variables
  • static variables

3.1. Non-static variables

Non-static local variable.

Age3AI.xs
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
void scopeTest(void)
{
    int foo = 0;

    // foo is accessible here.
    foo = 10;
}

void main(void)
{
    // foo cannot be accessed here.
    foo = 20; // This will cause an error.
}

Lifetime

Non-static variables lose their values between function calls.

Lifetime of non-static local variables.

Age3AI.xs
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
void lifetimeTest(void)
{
    int foo = 0;

    aiEcho("foo = " + foo);

    foo = aiRandInt(10);
}

void main(void)
{
    aiRandSetSeed(-1);
    lifetimeTest();
    lifetimeTest();
    lifetimeTest();
}

3.2. static variables

These variables are marked with the static keyword. They keep their values between function calls.

Lifetime of static local variables.

Age3AI.xs
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
void lifetimeTest(void)
{
    static int foo = 0;

    aiEcho("foo = " + foo);

    foo = aiRandInt(10);
}

void main(void)
{
    aiRandSetSeed(-1);
    lifetimeTest();
    lifetimeTest();
    lifetimeTest();
}