AngelScript Guide for Begineers

docs/angelscript/game/meta.json

@@ -1,5 +1,5 @@
 {
     "title": "Game",
     "type": "angelscript",
-	"weight": 0
+	"weight": 1
 }

docs/angelscript/guide/chapter1.md

@@ -0,0 +1,111 @@
+---
+title: Chapter 1 - Introduction
+weight: 0
+---
+
+# Chapter 1 - Introduction
+
+## 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)
+
+> [!TIP]
+> 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 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 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.
+
+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.
+
+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
+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.
+
+---
+
+## AngelScript in Strata Source
+
+### 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
+Where should you place the files containing your code?
+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/<files>` or just `p2ce/code/<files>` (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:
+
+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 begin development.
+The engine compiles scripts on every map load (you can use the `reload` command to recompile the scripts).
+
+### 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", "")]
+void MyCommand(const CommandArgs@ args) {
+    Msg("Hello world from AngelScript!\n"); // You can place your own text here!
+}
+```
+
+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 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", "")]
+void CodeTest(const Command@ args) {
+    // Here you can put your code
+}
+```
+
+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. 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().
+> > [!TIP]
+> > 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
+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. 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.

docs/angelscript/guide/chapter2.md

@@ -0,0 +1,116 @@
+---
+title: Chapter 2 - Primitive Types, Declaration & Assignment
+weight: 1
+---
+
+# Chapter 2 - Primitive Types, Declaration & Assignment
+
+## What will you learn in this chapter
+In this chapter you will learn about:
+- [Primitive Types](#primitive-types),
+- [Declaration and assignment of primitive types](#primitive-types),
+- [Auto keyword](#auto-keyword),
+- [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 primitive 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!
+
+---
+
+## Primitive Types
+Primitive types are the more "simpler" types, and are only implemented in the backend by the Strata Team inside the engine itself. These types include: `int`, `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
+Primitive types can easily get assigned and can be passed by primitive to functions (more on that later).
+To create a primitive type you usually perform a declaration and an assignment, or both at once:
+```cpp
+int myInt; // Declaration
+myInt = 20; // Assignment
+
+int myInt2 = 2; // Initialization
+```
+
+You can declare multiple variables of the same type at once:
+```cpp
+int myInt1, myInt2, myInt3;
+```
+
+Once declared, variables cannot change their type without redeclaration. This is not allowed:
+```cpp
+int myInt;
+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 `int`, `bool`, `double`, and then print them out to the console.
+> 2. Do the same but use variable initialization.
+
+### 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
+auto s = 3.14; // Will set type s to float
+auto var = functionThatWillReturnAnObjectWithAVeryLongName();
+
+// Handles (described in later chapters) can also be declared with auto
+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).
+
+--- 
+
+### Constants
+Constant variables are variables that cannot change over the lifetime of the [variable scope](chapter3) they are created in.
+You can define a constant variable using the `const` keyword:
+```cpp
+const int size = 31;
+const auto w = true; // 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:
+```cpp
+const int MAX_SIZE = 16;
+
+int myint = 27;
+my_func1(myint, MAX_SIZE); // A function that does something with myint, but also needs to have additional information
+my_func2(myint, MAX_SIZE) // Another function that does something else with myint, 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.
+```cpp
+bool function(int s, float i) {
+    const float value = s - i;
+    return i > value;
+}
+```
+
+> ### TASK 2:
+> Write a program that initializes a constant variable with the `auto` keyword, and then tries to change it after. Observe the compilation error in the console.
+
+---
+
+### 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):
+|Type|Short description|Minimum Value|Maximum Value|
+|---|---|---|---|
+|int8| Signed, 8 bits |-128 | 127 |
+|int16| Signed, 16 bits |-32,768 | 32,767 |
+|int| Signed, 32 bits |-2,147,483,648 | 2,147,483,647 |
+|int64| Signed, 64 bits |-9,223,372,036,854,775,808 | 	9,223,372,036,854,775,807 |
+|uint8| Unsigned, 8 bits, also represents characters (char) | 0 | 255 |
+|uint16| Unsigned, 16 bits | 0 | 65,535 |
+|uint| Unsigned, 32 bits | 0 | 4,294,967,295 |
+|uint64| Unsigned, 64 bits | 0 | 18,446,744,073,709,551,615 |
+
+> [!TIP]
+> The official AngelScript documentation mentions that the scripting engine has been mostly optimized for 32 bit datatypes (int/uint). Using these is recommended for the most part (unless you are dealing with numbers that don't fit into int/uint).
+
+