From 905193401a8ea38a3b78d93e498325f86e8e5248 Mon Sep 17 00:00:00 2001 From: Ashleyanna Rivers Date: Thu, 19 Mar 2026 12:57:25 -0600 Subject: [PATCH 1/4] Rephrasing and grammar changes Changed a few misspellings and edited the grammar to make the flow more natural. --- docs/angelscript/guide/chapter1.md | 76 +++++++++++++++--------------- docs/angelscript/guide/meta.json | 2 +- 2 files changed, 39 insertions(+), 39 deletions(-) diff --git a/docs/angelscript/guide/chapter1.md b/docs/angelscript/guide/chapter1.md index 8d4d1480..ef8deb92 100644 --- a/docs/angelscript/guide/chapter1.md +++ b/docs/angelscript/guide/chapter1.md @@ -5,42 +5,42 @@ weight: 0 # Chapter 1 - Introduction -## What will you learn in this chapter +## What You Will Learn In this chapter you will learn about: -- [AngelScript as a programming language](#angelscript), -- [Purpose of AngelScript in Strata Source](#what-can-you-do-with-angelscript), -- [Client - Server model of the engine](#client---server-model), -- [How to load code in the game](#loading-code), -- [Writing your own Hello World program](#your-first-script), -- [Testing out your own code](#how-to-test-out-your-code-in-a-basic-way) -- [Additional tips that might help you](#additional-tips). +- [AngelScript as a programming language](#angelscript) +- [Purpose of AngelScript in Strata Source](#what-can-you-do-with-angelscript) +- [Client-Server model of the engine](#client---server-model) +- [How to load code in the game](#loading-code) +- [Writing your own Hello World program](#your-first-script) +- [Testing out your own code](#how-to-test-out-your-code-the-simple-way) +- [Additional tips that might help you](#additional-tips) > [!TIP] -> In each chapter, you can easily navigate the page by clicking links in the "What will you learn in this chapter" section. +> In each chapter, you can easily navigate the page by clicking the links in the "What You Will Learn" section. > [!CAUTION] -> This guide assumes you have basic skills of programming in languages like Python, C/C++, Squirrel (VScript), etc. -> It is recommended you already have *some* experience in programming, although this guide aims to be as begineer's friendly as possible. +> This guide assumes you have basic programming skills in languages such as Python, C, C++, Squirrel (VScript), etc. +> It is recommended you already have *some* experience in programming, although this guide aims to be as beginner-friendly as possible. > Basic concepts will **not** be taught. > [!NOTE] -> It is recommended that while reading this guide, you will try out the things you have learned. This guide will include example tasks for you to do as a practice. +> It is recommended to try out what you learn in this guide as you go through it. This guide will include example tasks for you to attempt as practice. --- ## AngelScript -The [AngelScript's home page](https://www.angelcode.com/angelscript/) describes AngelScript as: +[AngelScript's home page](https://www.angelcode.com/angelscript/) describes AngelScript as: > The AngelCode Scripting Library, or AngelScript as it is also known, is an extremely flexible cross-platform scripting library designed to allow applications to extend their functionality through external scripts. -Besides that, you can treat AngelScript as some sort of hybrid between C++ and Python. In some areas it behaves like C++, for example it is statically typed, meaning that when you are declaring a variable you also have to declare it's types, and it also implements it's own version of pointers (called handles); it also aims to help out users in writing code, whether by dissallowing certain operations or by assuming. More on that will be explained in later parts of the guide. +Besides that, you may treat AngelScript as a sort of hybrid between C++ and Python. It behaves like C++ in some areas - for example, when it is statically typed. Just as in C++, when you declare a variable in AngelScript, you also must declare its types. In addition, AngelScript also implements its own version of pointers (called handles). It also aims to help users in writing its code, whether by disallowing certain operations or by assuming. More on that will be explained in later parts of the guide. -Its use cases vary, it is much closer to pure engine code than VScript, meaning that you can for example program in custom entities, or custom commands. +Use cases for AngelScript vary heavily. It is much closer to pure engine code than VScript, meaning that you can achieve outputs not possible in VScript, such as programming in custom entities and custom commands. -Its official documentation can be found here: [AS Official Docs](https://www.angelcode.com/angelscript/sdk/docs/manual/doc_script.html). +AngelScript's official documentation can be found here: [AS Official Docs](https://www.angelcode.com/angelscript/sdk/docs/manual/doc_script.html). -## What can you do with AngelScript -This question is not properly asked, because AngelScript will allow you to do mostly anything you want, however it's main task in Strata Source is to allow users to create custom entities, create custom commands, bind to in-game events, and more. +## What Can You Do With AngelScript +This question is not asked properly; AngelScript will allow you to do most anything you would like it to. However, its main purpose in Strata Source is to allow users to create custom entities, custom commands, bind to in-game events, and more. While VScript (mainly) sits between entities and handles the interactions between them, AngelScripts sits in a level above, where AS can be treated as entities *themselves*. @@ -48,26 +48,26 @@ While VScript (mainly) sits between entities and handles the interactions betwee ## AngelScript in Strata Source -### Client - Server model -Before we get into writing your first script, there is one more thing you need to know. Most engines including Source in general, operate on the client-server model. Meaning that client code is separate from the server code, even on singleplayer. When you start a map in singleplayer you essentially create a one-player server that runs beside the client. This is very important because AS code can be loaded on both. Some functionality will only be available on the server (like entities) and some functionality will only be available on the client (like Panorama/UI). +### Client - Server Model +Before you write your first script, there is one more thing you need to know. Most engines, including the Source engine, operate on the client-server model. This means that client code is separate from the server code, even in singleplayer. When starting a map in singleplayer, you essentially create a one-player server that runs beside the client. This is very important to remember as AS code can be loaded on both. Some functionality will only be available on the server (such as entities) and some functionality will only be available on the client (such as Panorama/UI). -### Loading code -Your first question might be: Where do I place the files containing my code? -The answer is pretty simple, each file that contains your code should be ended with the **.as** extension and be placed in the **code/** folder of a respective `Game` searchpath. Example locations would be `p2ce/custom/my-addon/code/` or just `p2ce/code/` (the latter not being recommended). +### Loading Code +Where should you place the files containing your code? +The answer is quite simple. Each file that contains your code should end with the **.as** extension and be placed in the **code/** folder of your respective `Game` searchpath. Example locations would be `p2ce/custom/my-addon/code/` or just `p2ce/code/` (the latter is not recommended). -You can name your files however you'd like. You can create custom directories, you can loosely place files, it all depends on what you're trying to achieve; in the long run it doesn't matter. What does matter are the "starting points" of sorts. The engine will not attempt to load any files besides 3 files placed **directly** in the **code/** folder: +You may name your files however you'd like. You can create custom directories or you can place your files loosely - it all depends on what you're trying to achieve. In the long run, it's not important. What *is* important is where you place the "starting points". The engine will not attempt to load any files except for these 3 files placed **directly** in the **code/** folder: 1. `init.as` - Will get loaded by server and client. 2. `sv_init.as` - Will only get loaded by the server. 3. `cl_init.as` - Will only get loaded by the client. -### IDE and testing environment -It is suggested to use Visual Studio Code with the [AngelScript Language Server (sashi0034.angel-lsp)](https://marketplace.visualstudio.com/items?itemName=sashi0034.angel-lsp) extension. From there you can open the `code/` folder of your choice as a project and develop there. +### IDE and Testing Environment +It is suggested to use Visual Studio Code with the [AngelScript Language Server (sashi0034.angel-lsp)](https://marketplace.visualstudio.com/items?itemName=sashi0034.angel-lsp) extension. From there, you can open the `code/` folder of your choice as a project and begin development. The engine compiles scripts on every map load (you can use the `reload` command to recompile the scripts). -### Your first script -Now, you should be ready to write your very first and own program that will print a Hello World message to the console. You might not know everything in the code below but don't get dissappointed! You should place this code into `cl_init.as` as it is a client command. +### Your First Script +You should now be ready to begin writing your very first program. For now, let's just print a Hello World message to the console. Though the code below may look foreign for now, don't be dissuaded! Place this code into `cl_init.as` as it is a client command. ```cpp [ClientCommand("HelloWorld", "")] @@ -76,13 +76,13 @@ void MyCommand(const CommandArgs@ args) { } ``` -Now, the only thing left is to launch up the game, open the console and execute the *HelloWorld* command. +Now, the only thing left to do now is launch the game, open the console, and execute the *HelloWorld* command. > ### TASK 1: > Run the HelloWorld program mentioned above. -## How to test out your code in a basic way -For now you need to know how to run your code so that you will be able to solve tasks given to you with this guide. +## How To Test Your Code the Simple Way +For now, you will need to know how to run your code so that you can complete the tasks given to you within this guide. In `sv_init.as` include: ```cpp [ServerCommand("CodeTest", "")] @@ -92,19 +92,19 @@ void CodeTest(const Command@ args) { ``` The code in this function will run whenever you run the `CodeTest` command in game. Remember to `reload` to see the changes! -The `Msg(string)` function will serve you as a way to view your variables (like print or cout), just do `Msg(a)` where a is your variable and a will get printed to the console! -Remember to add `"\n"` to the input of Msg (or just call `Msg("\n");` after your message), otherwise everything will print in one line! +The `Msg(string)` function will serve as a way to view your variables (like print or cout). Just type `Msg(a)` where *a* is your variable, and *a* will be printed to the console. +Remember to add `"\n"` to the input of Msg (or just call `Msg("\n");` after your message), otherwise everything will print in one line. > [!BUG] -> Some types such as `int` cannot be directly converted to string, and so you won't be able to put them directly into Msg(). +> Some types such as `int` cannot be directly converted to string, and as such, you won't be able to put them directly into Msg(). > > [!TIP] -> > In order to avoid that problem you can append to an empty string, just do `"" + a` and in most cases this will work: `Msg("" + a);` +> > In order to avoid this issue, you can append to an empty string. Just do `"" + a` and in most cases this will work: `Msg("" + a);` -### Compilation errors -Most of times scripts will report errors before they are ran, on map load. This is why if you don't see your functionality (like when a command is not there in the console), scroll up and check the error. Additionally you can use the first tip in the [tip section](#additional-tips) and then use `reload`. +### Compilation Errors +Scripts will often report errors before they are ran, usually on map load. If you don't see your functionality (such as a command not being the console), scroll up and check the error. Additionally, you can use the first tip in the [tip section](#additional-tips) and then use `reload`. ## Additional Tips > [!TIP] -> Reading console output can be tiresome as much more is happening in the console than just the script system. However, there is an easy way to just listen to the script system output. You can run `con_filter_text scriptsys; con_filter_enable 1` filter out anything that is not the script system. +> Reading console output can be tiresome, as much more is happening in the console than just the script system. To overcome this problem, you can run `con_filter_text scriptsys; con_filter_enable 1` to filter out anything that is not the script system. diff --git a/docs/angelscript/guide/meta.json b/docs/angelscript/guide/meta.json index 76da0b32..fa31d875 100644 --- a/docs/angelscript/guide/meta.json +++ b/docs/angelscript/guide/meta.json @@ -1,4 +1,4 @@ { - "title": "Begineer's Guide", + "title": "Beginner's Guide", "weight": 0 } From 118eadb53af8a2e81c785aa7d18eb15d55cc4067 Mon Sep 17 00:00:00 2001 From: Ashleyanna Rivers Date: Thu, 19 Mar 2026 13:33:29 -0600 Subject: [PATCH 2/4] Broken link fixed Fixed the broken link. Also edited one more sentence to align with the rest of the doc. --- docs/angelscript/guide/chapter1.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/angelscript/guide/chapter1.md b/docs/angelscript/guide/chapter1.md index ef8deb92..fae9d263 100644 --- a/docs/angelscript/guide/chapter1.md +++ b/docs/angelscript/guide/chapter1.md @@ -12,7 +12,7 @@ In this chapter you will learn about: - [Client-Server model of the engine](#client---server-model) - [How to load code in the game](#loading-code) - [Writing your own Hello World program](#your-first-script) -- [Testing out your own code](#how-to-test-out-your-code-the-simple-way) +- [Testing out your own code](#how-to-test-out-your-code-in-a-basic-way) - [Additional tips that might help you](#additional-tips) > [!TIP] @@ -42,7 +42,7 @@ AngelScript's official documentation can be found here: [AS Official Docs](https ## What Can You Do With AngelScript This question is not asked properly; AngelScript will allow you to do most anything you would like it to. However, its main purpose in Strata Source is to allow users to create custom entities, custom commands, bind to in-game events, and more. -While VScript (mainly) sits between entities and handles the interactions between them, AngelScripts sits in a level above, where AS can be treated as entities *themselves*. +While VScript (mainly) sits between entities and handles the interactions between them, AngelScripts sits in a level above, being able to *create* entities and define their behavior. --- @@ -81,7 +81,7 @@ Now, the only thing left to do now is launch the game, open the console, and exe > ### TASK 1: > Run the HelloWorld program mentioned above. -## How To Test Your Code the Simple Way +## How To Test Out Your Code in a Basic Way For now, you will need to know how to run your code so that you can complete the tasks given to you within this guide. In `sv_init.as` include: ```cpp From e3ed54fd3d624c6dc8414fd6fe33e1d520c5ca13 Mon Sep 17 00:00:00 2001 From: Ashleyanna Rivers Date: Thu, 26 Mar 2026 20:25:09 -0600 Subject: [PATCH 3/4] Most requested changes added --- docs/angelscript/guide/chapter1.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/angelscript/guide/chapter1.md b/docs/angelscript/guide/chapter1.md index fae9d263..0831bdc1 100644 --- a/docs/angelscript/guide/chapter1.md +++ b/docs/angelscript/guide/chapter1.md @@ -32,7 +32,7 @@ In this chapter you will learn about: [AngelScript's home page](https://www.angelcode.com/angelscript/) describes AngelScript as: > The AngelCode Scripting Library, or AngelScript as it is also known, is an extremely flexible cross-platform scripting library designed to allow applications to extend their functionality through external scripts. -Besides that, you may treat AngelScript as a sort of hybrid between C++ and Python. It behaves like C++ in some areas - for example, when it is statically typed. Just as in C++, when you declare a variable in AngelScript, you also must declare its types. In addition, AngelScript also implements its own version of pointers (called handles). It also aims to help users in writing its code, whether by disallowing certain operations or by assuming. More on that will be explained in later parts of the guide. +Besides that, AngelScript commonly behaves like C++ - for example, when it is statically typed. Just as in C++, when you declare a variable in AngelScript, you also must declare its types. In addition, AngelScript also implements its own version of pointers (called handles). It also aims to help users in writing its code, whether by disallowing certain operations or by assuming. More on that will be explained in later parts of the guide. Use cases for AngelScript vary heavily. It is much closer to pure engine code than VScript, meaning that you can achieve outputs not possible in VScript, such as programming in custom entities and custom commands. @@ -40,7 +40,7 @@ AngelScript's official documentation can be found here: [AS Official Docs](https ## What Can You Do With AngelScript -This question is not asked properly; AngelScript will allow you to do most anything you would like it to. However, its main purpose in Strata Source is to allow users to create custom entities, custom commands, bind to in-game events, and more. +ngelScript allows for a closer connection to the internal engine code by having the engine provide various APIs to its internal classes. This allows you to do various things, such as creating custom entities, creating your own ConCommands and ConVars, making custom weapons - all things that aren't normally easy to do with VScript. While VScript (mainly) sits between entities and handles the interactions between them, AngelScripts sits in a level above, being able to *create* entities and define their behavior. @@ -54,7 +54,8 @@ Before you write your first script, there is one more thing you need to know. Mo ### Loading Code Where should you place the files containing your code? -The answer is quite simple. Each file that contains your code should end with the **.as** extension and be placed in the **code/** folder of your respective `Game` searchpath. Example locations would be `p2ce/custom/my-addon/code/` or just `p2ce/code/` (the latter is not recommended). +Each file that contains your code should end with the **.as** extension and be placed in the **code/** folder of your respective `Game` searchpath. Example locations would be `p2ce/custom/my-addon/code/` or just `p2ce/code/` (the latter is not recommended). +Code can also be placed inside the `code` folder of an addon created with the SDK Launcher. You may name your files however you'd like. You can create custom directories or you can place your files loosely - it all depends on what you're trying to achieve. In the long run, it's not important. What *is* important is where you place the "starting points". The engine will not attempt to load any files except for these 3 files placed **directly** in the **code/** folder: @@ -93,7 +94,7 @@ void CodeTest(const Command@ args) { The code in this function will run whenever you run the `CodeTest` command in game. Remember to `reload` to see the changes! The `Msg(string)` function will serve as a way to view your variables (like print or cout). Just type `Msg(a)` where *a* is your variable, and *a* will be printed to the console. -Remember to add `"\n"` to the input of Msg (or just call `Msg("\n");` after your message), otherwise everything will print in one line. +Remember to add `"\n"` to the input of Msg (or just call `Msg("\n");` after your message), otherwise everything will print in one line. To avoid having to do this, you can use the `Msgl(string)` which will automatically append an `"\n"` to the end of each message. > [!BUG] > Some types such as `int` cannot be directly converted to string, and as such, you won't be able to put them directly into Msg(). From d6cdfcf53beca67e673c52daf0546dbfdd08705a Mon Sep 17 00:00:00 2001 From: Ashleyanna Rivers Date: Fri, 3 Apr 2026 00:32:52 -0600 Subject: [PATCH 4/4] Chapters 2 and 3 grammar reformatting Minor grammatical changes to chapters 2 and 3. Fixed one minor typo in Chapter 1. --- docs/angelscript/guide/chapter1.md | 3 +- docs/angelscript/guide/chapter2.md | 30 ++++++------- docs/angelscript/guide/chapter3.md | 67 +++++++++++++++--------------- 3 files changed, 50 insertions(+), 50 deletions(-) diff --git a/docs/angelscript/guide/chapter1.md b/docs/angelscript/guide/chapter1.md index 0831bdc1..f5c29520 100644 --- a/docs/angelscript/guide/chapter1.md +++ b/docs/angelscript/guide/chapter1.md @@ -27,7 +27,6 @@ In this chapter you will learn about: > It is recommended to try out what you learn in this guide as you go through it. This guide will include example tasks for you to attempt as practice. --- - ## AngelScript [AngelScript's home page](https://www.angelcode.com/angelscript/) describes AngelScript as: > The AngelCode Scripting Library, or AngelScript as it is also known, is an extremely flexible cross-platform scripting library designed to allow applications to extend their functionality through external scripts. @@ -40,7 +39,7 @@ AngelScript's official documentation can be found here: [AS Official Docs](https ## What Can You Do With AngelScript -ngelScript allows for a closer connection to the internal engine code by having the engine provide various APIs to its internal classes. This allows you to do various things, such as creating custom entities, creating your own ConCommands and ConVars, making custom weapons - all things that aren't normally easy to do with VScript. +AngelScript allows for a closer connection to the internal engine code by having the engine provide various APIs to its internal classes. This allows you to do various things, such as creating custom entities, creating your own ConCommands and ConVars, making custom weapons - all things that aren't normally easy to do with VScript. While VScript (mainly) sits between entities and handles the interactions between them, AngelScripts sits in a level above, being able to *create* entities and define their behavior. diff --git a/docs/angelscript/guide/chapter2.md b/docs/angelscript/guide/chapter2.md index feafadcd..bb8f8729 100644 --- a/docs/angelscript/guide/chapter2.md +++ b/docs/angelscript/guide/chapter2.md @@ -13,23 +13,23 @@ In this chapter you will learn about: - [Constants and the const keyword](#constants), - [Integer size reference table](#integer-size-reference-table). -> Unfortunately, in this chapter you won't learn anything really interesting, but this knowledge is crucial to continue further. Data types in general are a very extensive subject, but you don't need to know everything. This chapter is supposed to teach you how to handle value types in your script. +> The knowledge in this chapter is crucial to continue further. Data types are an extensive subject, but you don't need to know everything. This chapter's goal is to teach you how to handle value types in your script. > [!NOTE] -> This chapter won't cover every detail about any of data types, it is recommended you visit the [Data Types Section](../game/type) of the wiki for more information. -> Alternatively, you can find references on the [AS Official Documentation](https://www.angelcode.com/angelscript/sdk/docs/manual/doc_datatypes.html), however please note that Strata's wiki will be the most representative, some functionality might have been changed! +> This chapter won't cover every detail of every data type. It is recommended you visit the [Data Types Section](../game/type) of the Wiki for more information. +> Alternatively, you can find references on the [AS Official Documentation](https://www.angelcode.com/angelscript/sdk/docs/manual/doc_datatypes.html). Please note, however, that the Strata Wiki is a better reference, as some functionality may have been changed. --- ## Value Types -Value types are the more "primitive" types, and are only implemented in the backend by the Strata Team inside the engine itself. These types include: `int`, `string`, `bool`, `float`, `double`, etc. +Value types are a more "primitive" type, and are only implemented in the backend inside the engine itself. These types include: `int`, `string`, `bool`, `float`, `double`, etc. > [!WARNING] > It is assumed you already know about these data types from other languages (mainly C++). This subsection will only provide information relevant to AngelScript itself. -### Declaration and assignment -Value types can easily get assigned and can be passed by value to functions (more on that later). -To create a value type you usually perform a declaration and an assignment, or both at once: +### Declaration and Assignment +Value types can be easily assigned and can passed by value to functions. We'll get into that more later. +To create a value type, you will usually perform a declaration, an assignment, or both at once: ```cpp int myInt; // Declaration myInt = 20; // Assignment @@ -42,7 +42,7 @@ You can declare multiple variables of the same type at once: int myInt1, myInt2, myInt3; ``` -Once declared, variables cannot change their type without redeclaration. This is not allowed: +Once declared, variables cannot change their type without redeclaration. This, for example, is not allowed: ```cpp int myInt; myInt = 3.2; // myInt is of type int, not float/double! @@ -50,9 +50,9 @@ myInt = 3.2; // myInt is of type int, not float/double! > ### TASK 1: > 1. Create a program that will declare and assign variables of types `string`, `int`, `bool`, `double`, and then print them out to the console. -> 2. Do the same but use variable initialization. +> 2. Do the same using variable initialization. -### Auto keyword +### Auto Keyword Although not recommended, the `auto` keyword will make the compiler automatically determine the data type of the variable: ```cpp auto i = 1; // Will set type of i to integer @@ -63,7 +63,7 @@ auto var = functionThatWillReturnAnObjectWithAVeryLongName(); auto@ handle = @obj; ``` -The `auto` keyword is not recommended for several cases. The main one of them is that you cannot immediately see the data type of a returned object especially from functions, like the one above. We don't know what that function will return. Another reason is that sometimes the compiler might guess wrong, especially in cases like integers, where you have multiple ways that `1` could have been described (e.g. int8/int16, both can describe `1`, even `bool` can). +The `auto` keyword is not recommended in many cases. Using `auto`, you cannot immediately see the data type of a returned object, especially from functions such the one above. We don't know what that function will return. Additionally, there is always a chance the compiler may guess incorrectly. This issue is especially prominent in cases such as integers, where there are multiple ways `1` could be described (e.g. int8/int16, both can describe `1`, as can `bool`). --- @@ -75,7 +75,7 @@ const int size = 31; const auto st = "string"; // const also works with the auto keyword ``` -Constants can be useful as a sort of configuration of the script itself. If you reuse a statically defined value you can instead define a global constant and then changing one value will change everything at once: +Constants can be useful as a sort of configuration of the script itself. Instead of reusing a statically-defined variable, you can define a global constant in its place. Changing one value will then change everything at once: ```cpp const int MAX_SIZE = 16; @@ -84,7 +84,7 @@ my_func1(mystring, MAX_SIZE); // A function that does something with mystring, b my_func2(mystring, MAX_SIZE) // Another function that does something else with mystring, but it also needs the same additional information ``` -Constants are also a way to optimize your code. If you know that a variable won't change (or shouldn't change) after it's initialization, always make it a constant. +Constants also function as a way to optimize your code. If you know that a variable won't change (or shouldn't change) after its initialization, you should always make it a constant. ```cpp bool function(string s, float i) { const float value = s.length() - i; @@ -97,8 +97,8 @@ bool function(string s, float i) { --- -### Integer size reference table -The table below shows the minimum and maximum values for each integer subtype (don't worry about remembering this, just remember that it exists here): +### Integer Size Reference Table +The table below shows the minimum and maximum values for each integer subtype. It is not necessary to memorize this chart as you can always refer back to this page when necessary. |Type|Short description|Minimum Value|Maximum Value| |---|---|---|---| |int8| Signed, 8 bits |-128 | 127 | diff --git a/docs/angelscript/guide/chapter3.md b/docs/angelscript/guide/chapter3.md index 9d8e12d0..b0f9f055 100644 --- a/docs/angelscript/guide/chapter3.md +++ b/docs/angelscript/guide/chapter3.md @@ -17,44 +17,44 @@ In this chapter you will learn about: > Statements, expressons, conditions and the variable scope are the foundation of every program or script. --- -## Basic statements +## Basic Statements -Your code is like a recipe, and statements are the individual steps. +If your code is a recipe, the statements are the individual steps. -Statements are a way to tell the script engine what it needs to do, we already used them in previous chapters, such as the assignment or declaration. +Statements are a way to tell the script engine what it needs to do. We've already used statements in previous chapters, such as when we performed assignment and declaration. -### Expression statements +### Expression Statements Any expression can be placed on a line as a statement. Examples of expressions include: - Function call **()** operator - calls a function (more on functions later), - Equals **=** operator - performs assignment, - Add **+** operator - adds two values together, -- Substraction **-** operator - substracts two values from each other, +- Subtraction **-** operator - subtracts two values from each other, - Many more, such as **+=**, **-=**, **++**, etc. are available. More about them can be found in the [expression reference table](https://www.angelcode.com/angelscript/sdk/docs/manual/doc_expressions.html). -Such statements need to end with the semicolon (`;`): +Such statements need to end with a semicolon (`;`): ```cpp b = a + b; func(); a += b; ``` -AngelScript follows a specific instruction of operation order. Function calls are evaluated first bottom to top, then AS sticks to order of operations as specified in the [Operator Precedence](https://www.angelcode.com/angelscript/sdk/docs/manual/doc_operator_precedence.html) reference. +AngelScript follows a specific instruction of operation order. First, function calls are evaluated bottom to top. AngelScript then sticks to the order of operations as specified in the [Operator Precedence](https://www.angelcode.com/angelscript/sdk/docs/manual/doc_operator_precedence.html) reference. -You can force an order of operations by using parenthesis: +You can force an order of operations by using parentheses: ```cpp float a = 1 + 1.0 / 2; // This will return 1,5 float b = (1 + 1.0) / 2; // This will return 1 ``` > [!TIP] -> Order of how operators are evaluated for standard math operators such as **+**, **-**, **\***, **/**, etc. follow the standard Order of Operations. +> The order of how operators are evaluated for standard math operators such as **+**, **-**, **\***, **/**, etc. follow the standard Order of Operations. > ### TASK 1: -> Given `float a = 4; float b = 5;` Write a program that calculates the number c given by the equation: `c = (a - 2)^2 + (b + 1) / 2`. +> Given `float a = 4; float b = 5;`, write a program that calculates the value of `c` given by the equation `c = (a - 2)^2 + (b + 1) / 2`. -### Comparison operators -Comparison operators are operators of which expressions evaluate to the `true` or `false` boolean values. An example of a comparsion operator is the equals (**==**) operator, which checks if the two values on boths sides of such operator are equal. Another type of a condition operator is the greater than operator (**>**), which checks if the value on the left side is greater than the value on the right side. For comparison operator reference please check the [expression reference table](https://www.angelcode.com/angelscript/sdk/docs/manual/doc_expressions.html). +### Comparison Operators +Comparison operators are operators that compare two values, such as with the `true` or `false` boolean values. An example of a comparsion operator is the **equals** (**==**) operator, which checks if the values on both sides of the operator are equal. Another example is the **greater than** operator (**>**), which checks if the value on the left side is greater than the value on the right side. For a more comprehensive comparison operator reference, please check the [expression reference table](https://www.angelcode.com/angelscript/sdk/docs/manual/doc_expressions.html). ```cpp int a = 1; int b = 2; @@ -64,27 +64,27 @@ b = 1; bool result = a == b; // Result now stores the information if a and b were equal when it was defined. ``` -### Logic operators +### Logic Operators Logic operators are a way to combine comparison expressions in order to achieve one result: -- NOT - denoted as `!`, evaluates to true, if value is false and vice versa, -- AND - denoted as `&&`, evaluates to true, if both values are true, -- OR - denoted as `||`, evaluates to true, if even one of the values is true, else false if both are false, -- XOR - denoted as `^^`, evaluates to true, if and only if **one** of the values is true. +- NOT - denoted as `!`. Evaluates to true if value is false and vice versa. +- AND - denoted as `&&`. Evaluates to true if both values are true. +- OR - denoted as `||`. Evaluates to true, if even one only of the values is true. Otherwise evaluates to false if both values are false. +- XOR - denoted as `^^`. Evaluates to True if and only if **one** of the values is True. ```cpp a && b; // AND -a && b || c; // A combination of AND and OR, a AND b is going to get evaluated first -a && (b || c); // You can use parenthesis to specify which operator should get evaluated first, here OR will get evaluated first +a && b || c; // A combination of AND and OR. a AND b will be evaluated first. +a && (b || c); // You can use parentheses to specify which operator should get evaluated first. Here, OR will get evaluated first. ``` > [!NOTE] -> Although AngelScript supports Python-like logic operator notation (and, or, ...) it is recommended to stick to the C-like notation. This is mainly because AS is much more similar to C in it's syntax, and also not every extension adding AS support for your IDE has support for the Python-like notation. +> Although AngelScript supports Python-like logic operator notation (and, or, ...) it is recommended to stick to C-like notation. This is mainly because AS is much more similar to C in its syntax. In addition, not every extension adding AS support for your IDE has support for the Python-like notation. --- ## Conditions -Conditions are a way to tell the engine to execute specific code only if a specific condition is met. For example, only add numbers if they are positive. -They should contain an expression that evalues to true or false, and they can be any sort of valid combination of comparison operators and logic operators, etc. +Conditions are a way to tell the engine to execute specific code only if a specific condition is met. For example, conditions will allow you to tell the engine to only add numbers together if they are positive. +Conditions should contain an expression that evaluates to true or false. They can be any valid combination of comparison operators and logic operators, etc. ### If/else block The `if`/`else if`/`else` block is used to run specific code only on certain conditions. The `else if` and `else` are not required, but the block must start with an `if` statement. @@ -92,19 +92,20 @@ The `if`/`else if`/`else` block is used to run specific code only on certain con if ( a > 10 ) { // Condition 1 // Run the code in here } else if ( a < 10 ) { // Condition 2 - // If we haven't met condition 1, but have met condition 2, execute the code in here + // If we haven't met condition 1, but have met condition 2, execute this code } else if ( condition3 ) { - // We haven't met neither condition 1, nor condition 2, but we have met condition 3 + // We haven't met neither condition 1, nor condition 2, but we have met condition 3, execute this code } else { // If none of the conditions were met, execute this code } ``` > ### TASK 2: -> Given two numerical values *a* and *b* (defined statically in your script) prints out an absolute value of their difference. +> Given two numerical values *a* and *b* (defined statically in your script), print out an absolute value of their difference. -### Switch statement +### Switch Statement + The switch statement is a very useful tool for situations where you need to compare to a lot of different cases. It performs the *is equal* operation comparing a value to every value specified in case blocks. It is also much faster than a block of the `if`/`else if`/`else` statements. ```cpp switch ( value ) { @@ -122,22 +123,22 @@ switch ( value ) { } ``` > [!CAUTION] -> Each case requires a `break` statement after finishing code execution. This is because switch behaves more like the `goto` (C++) functionality, meaning that it doesn't stop executing code after finishing a specific case. The `break` statement will tell the code to go out of the `switch` block. This is also why in the upper example `case 2:` and `case 3:` can be used to both execute the same lines of code. +> Each case requires a `break` statement after finishing code execution. This is because switch statements behave more like the `goto` (C++) functionality, meaning that it doesn't stop executing code after finishing a specific case. The `break` statement will tell the code to go out of the `switch` block. This is also why in the upper example `case 2:` and `case 3:` can be used to both execute the same lines of code. > ### TASK 3: > Given a string as a value (statically defined), write a program that would simulate a command-like behaviour using the switch statement. If the string is equal to: > - "hello" - print "HelloWorld" to the console > - "engine" - print "Strata Source" to the console > - "name" - print "My name is Chell" to the console -> - on any other string - print "Command not recognized!" to the console +> - Any other string - print "Command not recognized!" to the console --- ## Variable Scope -Variable Scope determines which data can be accessed from where. In AngelScript the Variable Scope behaves exactly as the one in C++. -In general the Variable Scope makes programs use less memory by not holding expired (not useful anymore) information inside the memory, as an example: +Variable Scope determines which data can be accessed from where. In AngelScript, Variable Scope behaves exactly as the one in C++. +In general, the Variable Scope makes programs use less memory by not holding expired information inside the memory. As an example: ```cpp int number = 10; @@ -150,11 +151,11 @@ void my_func2() { my_number = 80; // Error, my_number has not been declared } ``` -In this case my_number doesn't exist inside *my_func2*, it only exists inside *my_func1* and only for the duration of that function's execution. +In this case, `my_number` doesn't exist inside *my_func2*, it only exists inside *my_func1* and only for the duration of that function's execution. -Statements such as `if`, `else`, `for`, `while`, `try`, etc. create local variable scopes each time, meaning that variables declared inside them cannot be accessed outside of them, contrary to how for example Python handles it (where scopes are only created inside functions). +Statements such as `if`, `else`, `for`, `while`, `try`, etc. create local variable scopes each time, meaning that variables declared inside them cannot be accessed outside of them, contrary to how, for example, Python handles it (where scopes are only created inside functions). -In AS, global variables are allowed, however: +In AngelScript, global variables are allowed. However: > [!NOTE] > From the official documentation: *Variables of primitive types are initialized before variables of non-primitive types. This allows class constructors to access other global variables already with their correct initial value. The exception is if the other global variable also is of a non-primitive type, in which case there is no guarantee which variable is initialized first, which may lead to null-pointer exceptions being thrown during initialization.*