From e65687a3d54fe6319b470ac317f24b933a12f6f5 Mon Sep 17 00:00:00 2001 From: YYBartT Date: Fri, 11 Oct 2024 16:45:17 +0200 Subject: [PATCH 01/11] docs(feature): [GX.games] Add a "save as .zip" output type which avoids uploading to the GXC YoYoGames/GameMaker-Bugs#7454 * Compiling page: * Updated screenshot and description as well as other text referring to GX.games target * Renamed GX.Games => GX.games --- Manual/contents/Introduction/Compiling.htm | 15 ++++++++------- .../General/GXgames_Environments.htm | 6 +++--- .../QS_GX.Games_Compile_Options.png | Bin 10876 -> 14949 bytes 3 files changed, 11 insertions(+), 10 deletions(-) diff --git a/Manual/contents/Introduction/Compiling.htm b/Manual/contents/Introduction/Compiling.htm index 514f02d6e..abefd0f06 100644 --- a/Manual/contents/Introduction/Compiling.htm +++ b/Manual/contents/Introduction/Compiling.htm @@ -26,7 +26,7 @@

Compiling for Testing

Compiling your game for testing can be done by simply pressing the Play button Play Icon at the top of the IDE, which will launch the game for testing using the specified target. You can also run the game in Debug Mode by testing using the Debug button Debug Icon. This will run the game, but also open up the Debug Window, where you can monitor how your game performs and see any issues (see the section on Debugging for more information).

Target Settings

By default GameMaker will run and debug using the built-in Virtual Machine (VM), which is more or less the same as running on the desktop OS being used. However, GameMaker is a cross-platform engine and you can test, debug and compile executable packages of your projects on a number of different target platforms (the exact platforms available will depend on the details of your licence). To change the current target platform you can click  on the Targets button Target Manager Icon to open the Targets Window, which will look something like this (exact details will vary based on your licence type):

-

Target ListAt the top, beside the Targets button, you have the current settings which tells you the platform and the specific settings actually being used, and then the rest of the window is taken up with the details and options for all the available targets which you can select to use instead. Each section of this window is explained below: 

+

Target ListAt the top, beside the Targets button, you have the current settings which tells you the platform and the specific settings actually being used, and then the rest of the window is taken up with the details and options for all the available targets which you can select to use instead. Each section of this window is explained below: 

@@ -71,17 +71,17 @@

Target Settings

There are also a number or preferences that can be set to modify and customise the compile workflow, explained on the following page:

Creating A Final Executable Package

You can click the Create Executable button Compile Icon in the IDE to start the compiler build or select Create Executable from The Build Menu. Either process will start the build process which will depend on the target platform selected.

-

On the GX.games target, it will open a special window allowing you to compile and upload your game to GX.games; on all other targets it will open a file explorer window where you can give the final name that you wish to use for your game executable, before clicking Save to start the compile and build process. Once you have done this, the necessary files will be generated so that you can distribute it as you wish.

+

On the GX.games target, it will open a special window allowing you to compile and upload your game to GX.games; on all other targets as well as when you save locally as zip on GX.games, it will open a file explorer window where you can give the final name that you wish to use for your game executable, before clicking Save to start the compile and build process. Once you have done this, the necessary files will be generated so that you can distribute it as you wish.

You Should Know

Here are some things to keep in mind when creating executables:

@@ -93,8 +93,9 @@

How Different Targets Build

  • GX.games - When compiling for the "GX.games" target, you will see the "GX.games Packaging" window which will first ask you to sign in using your Opera account:You won't need to sign in here if you've already signed into GameMaker using Opera Single Sign-In.

    Next you will be asked the packaging option to use: 
    -
    - After you have signed in, it will start compiling your game and proceed to upload it to GX.games. You can then click on "Edit Game on Opera" to edit it on GX.create and publish it:
    + You'll be asked to sign in if you select any of the upload options, though this isn't needed if you save locally as a ZIP.
    +
    + After you have signed in, GameMaker will start compiling your game and proceed to upload it to GX.games. You can then click on "Edit Game on Opera" to edit it on GX.create and publish it:
    Please refer to this page to learn more about the GX.games upload process, and this page for setting up the various exports, such as YYC and Mobile.
  • Windows - Compiling for the general Windows OS will first request that you choose between creating an Installer or a Zip package, where the installer will be a single executable that will install your game, and the Zip file will be a single *.zip format compressed file with all your game files stored within (the files will need extracted for the game to run). Windows Compile OptionsIf you check the box marked Remember Packaging Option then GameMaker will remember the choice for all future compiles (this can be reset or changed from the Windows Preferences). You can find out more from the YoYo Games Help Center.
    @@ -104,7 +105,7 @@

    How Different Targets Build

  • Ubuntu (Linux) - Compiling for Ubuntu will ask you to choose between creating an .AppImage or a .zip file, containing either an x64 or an ARM executable (however AppImage does not support ARM). You can find out more from the YoYo Games Help Center.
    .AppImage is used for sharing as a package via any distributor except Steam, while .zip is used only for uploading to Steam (as it uses the Steam Runtime specifically). Because of this, the created .zip cannot be opened as a regular zip file.
    • -
  • HTML5 - If you have chosen to build HTML5, then an index.html file (this is the default name, but you can give your own name too in the Platform Preferences) along with a folder containing your game files will be created and saved to the specified location. For your game to work you will need both of these to be uploaded to a server. The index.html can also be customised to show your game with a different background colour, or at a different position etc... but a knowledge of HTML is necessary for this, and you can also specify your own custom index file when you build the package (see the HTML5 Game Options). You can find out more from the YoYo Games Help Center.
    • +
  • HTML5 - If you have chosen to build HTML5, then an index.html file (this is the default name, but you can give your own name too in the Platform Preferences) along with a folder containing your game files will be created and saved to the specified location. For your game to work you will need both of these to be uploaded to a server. The index.html can also be customised to show your game with a different background colour, at a different position, etc. but a knowledge of HTML is necessary for this, and you can also specify your own custom index file when you build the package (see the HTML5 Game Options). You can find out more from the YoYo Games Help Center.
  • Android - For Android devices, you can choose to build an *.apk or an *.aab (Android App Bundle) file from the window that is shown for saving the game:

    Andoird APK or AAB File SelectorThe type of file you choose will depend on the store that you wish to target, with the *.aab file being required for Google Play, while the *.apk file can be used on other stores. You can find out more from the YoYo Games Help Center. diff --git a/Manual/contents/Setting_Up_And_Version_Information/IDE_Preferences/General/GXgames_Environments.htm b/Manual/contents/Setting_Up_And_Version_Information/IDE_Preferences/General/GXgames_Environments.htm index f4c696e74..52dcef64f 100644 --- a/Manual/contents/Setting_Up_And_Version_Information/IDE_Preferences/General/GXgames_Environments.htm +++ b/Manual/contents/Setting_Up_And_Version_Information/IDE_Preferences/General/GXgames_Environments.htm @@ -4,7 +4,7 @@ GX.games Environments - + @@ -14,7 +14,7 @@ -

    GX.Games Environments Preferences

    +

    GX.games Environments Preferences

    Help Prefs

    This section allows you to change the currently selected environment for GX.games. You can choose between the main production environment, and the sandbox environment.

    You can also set a path that contains custom environment JSON files.

    @@ -28,7 +28,7 @@

    GX.Games Environments Preferences

    Next: Help
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved

    GML Code Overview

    -

    This section of the manual contains all the information required to understand and use GML Code. The runtime functions in this language can be used to create your games and is added into objects from the Object Editor, although it can also be used along with GML Visual. Below you can see a typical image of an object with the code editor open on an event:

    -

    Object, Events and Code OverviewEach event has its own tab in the editor and you can add, edit, or remove code from them at any time (for more information on events see Object Events). The code itself must have a basic structure and can contain resource indices, variables, functions, expressions, keywords, etc. all of which are explained in the sections below. If you are a novice to programming or making the switch from GML Visual, it is recommended that you start with the page on Basic Code Structure and then read through all the other pages in this section, testing code from each one within GameMaker itself.

    -

    You can use Feather for intelligent code completion and error reporting in your GML Code scripts.

    +

    This section of the manual contains all the information required to understand and use GML Code. The runtime functions in this language can be used to create your games and is added into objects from The Object Editor, although it can also be used along with GML Visual. Below you can see a typical image of an object with the code editor open on an event:

    +

    Object, Events and Code OverviewEach event has its own tab in the editor and you can add, edit, or remove code from them at any time (for more information on events see Object Events). The code itself must have a basic structure and can contain resource indices, variables, functions, expressions, keywords, etc. all of which are explained in the sections below. If you are a novice to programming or making the switch from GML Visual, it is recommended that you start with the page on Basic Code Structure and then read through all the other pages in this section, testing code from each one within GameMaker itself.

    +

    You can use Feather for intelligent code completion and error reporting in your GML Code scripts.

     

    Basics of GML Code

     

    +

    Language Features

    +

     

     

    @@ -66,7 +67,7 @@

    More about GML Code

    Next: GML Code Reference
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved

    Language Features

    The GameMaker Language (GML) has a number of features which are part of the essential structure of all programs written with the language. Each of these will be used in any code you write multiple times, so you should know what they are and how they work before getting started with programming a project.

    - +

     

     

    - +
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -

    Arrays

    -

    Arrays can be extremely useful and are an essential part of making games. It is essentially a type of variable that can hold multiple values as a "list" -- consider the following code:

    +

    Arrays

    +

    Arrays are essentially a type of variable that can hold multiple values as a "list". They can be extremely useful and are an essential part of making games. Consider the following code:

    numbers = [ 0, 1, 2, 3, 4, 5 ];

    fruits = [ "Apples", "Oranges", "Mangoes" ];

    -

    Using the [item, item, item] syntax we are creating an array that is stored in a variable. The items stored in an array can later be accessed through that variable using an integer number, starting at 0, which is placed inside [] brackets:

    +

    Using the [item, item, item] syntax we are creating an array that is stored in a variable. The items stored in an array can later be accessed through that variable using an integer number, starting at 0, which is placed inside [ ] brackets:

    first_fruit = fruits[ 0 ];
    second_fruit = fruits[ 1 ];
    // ...and so on.

    @@ -29,16 +29,16 @@

    Arrays

    Before going any further let's clarify what an array actually is and how it's structured. An array is simply a data type that is assigned to a variable, and it can contain not just one value, but multiple values. The image below shows a schematic for a basic array:

    -

    This is called a 1D (one-dimensional) array, and as you can see the array is stored in the variable "a" and contains multiple values. To access the array you would do something like the following:

    +

    This is called a 1D (one-dimensional) array, and as you can see the array is stored in the variable a and contains multiple values. To access the array you would do something like the following:

    var _val = a[0];
    show_debug_message(_val);

    -

    The above code gets the value from position 0 of the array "a" then outputs it to the console, which - based on the contents of the array shown in the image above - would output 125. If you did the following:

    +

    The above code gets the value from position 0 of the array a then outputs it to the console, which - based on the contents of the array shown in the image above - would output 125. If you did the following:

    var _val = a[3];
    show_debug_message(_val);

    -

    The output would show "Hi!".

    -

    As you can see, you give the array a variable name and then a value in square brackets [], where the value is the position in the array to get the data from. So essentially, an array is a container with a number of slots to store values, and each position in the container has a specific number to identify it, which is what we put in the []. It's worth noting that the contents of an array always start at 0 and can never be negative!

    +

    The output would show "Hi!".

    +

    As you can see, you give the array a variable name and then a value in square brackets [ ], where the value is the position in the array to get the data from. So essentially, an array is a container with a number of slots to store values, and each position in the container has a specific number to identify it, which is what we put in the [ ]. It's worth noting that the contents of an array always start at 0 and can never be negative!

           Creating Arrays

    -

    We've shown how to check an array for data, but how do we create the array to start with? First it has to be initialized before we can use it or GameMaker will give us an error. Initializing an array just means that we give each slot of the array an initial value in preparation for it to be used elsewhere in the project code. This is important to remember as it means that you have to do a certain amount of planning before using arrays, but it is easy enough to initialize one using a repeat loop like this:

    +

    We've shown how to check an array for data, but how do we create the array to start with? First it has to be initialised before we can use it or GameMaker will give us an error. Initialising an array just means that we give each slot of the array an initial value in preparation for it to be used elsewhere in the project code. This is important to remember as it means that you have to do a certain amount of planning before using arrays, but it is easy enough to initialise one using a repeat loop like this:

    var i = 9;

    repeat(10)
    @@ -47,25 +47,25 @@

           Creating Arrays

        i -= 1;
    }

    -

    This simple code will initialize a ten-slot array (from 0 to 9) to hold 0, ie: each slot in the array contains the value 0. You will notice that the array has been initialised backwards, with the last value being defined first. This is not strictly necessary but is the optimal way to do it as it will reserve a space in memory that is the exact size of the array, whereas if you initialize an array from 0 upwards, the memory has to be re-allocated for every additional value added (so for a ten-slot array, initialising it in a loop would change the memory allocation ten times). The speed difference is negligible for smaller arrays, but larger ones should be optimised as much as possible in this way.

    -

    NOTE: The HTML5 export is the exception to the above rule, and when targeting that you should initialise arrays in consecutive order from 0 upwards.

    -

    You can also use the GML function array_create() to initialize an array with a fixed size, and you can even create "empty" arrays with no values, for example:

    +

    This simple code will initialise a ten-slot array (from 0 to 9) to hold 0, i.e.: each slot in the array contains the value 0. You will notice that the array has been initialised backwards, with the last value being defined first. This is not strictly necessary but is the optimal way to do it as it will reserve a space in memory that is the exact size of the array, whereas if you initialise an array from 0 upwards, the memory has to be re-allocated for every additional value added (so for a ten-slot array, initialising it in a loop would change the memory allocation ten times). The speed difference is negligible for smaller arrays, but larger ones should be optimised as much as possible in this way.

    +

     The HTML5 export is the exception to the above rule, and when targeting that you should initialise arrays in consecutive order from 0 upwards.

    +

    You can also use the GML function array_create to initialise an array with a fixed size, and you can even create "empty" arrays with no values, for example:

    my_array = [];

    -

    This tells GameMaker that the variable "my_array" is an array, and you can then add values to it at any time in the future. However, if you try to access a value in an empty array then you will get an error.

    +

    This tells GameMaker that the variable my_array is an array, and you can then add values to it at any time in the future. However, if you try to access a value in an empty array then you will get an error.

    If you already know which items you want to put into the array, you can add comma-separated values between the brackets when declaring the array:

    my_array = ["Steve", 36, "ST-3V3 - Steve Street"];

           Array Bounds

    You should always take care to only access valid array positions, as trying to access a value outside of an array will also give an error. For example, this will cause the project to crash when run:

    my_array = array_create(5, 0);
    var _val = my_array[6];

    -

    The array was only initialised with 5 positions, but we've tried to get position 7 - since arrays are numbered from 0, array[6] is position 7 - therefore the game generates an error and crashes.

    +

    The array was only initialised with 5 positions, but we've tried to get position 7 - since arrays are numbered from 0, my_array[6] is position 7 - therefore the game generates an error and crashes.

           Using Arrays

    Now how do we use an array practically? Exactly the same as we would use a normal variable, as shown in the following examples:

    // Add two array values together
    total = array[0] + array[5];

    // Check an array value
    - if array[9] == 10
    + if (array[9] == 10)
    {
        // Do something
    }
    @@ -73,16 +73,16 @@

           Using Arrays

    // Draw an array value
    draw_text(32, 32, array[3]);

    -

    Since arrays are numbered sequentially, this means you can loop through them to perform extra actions too, just like we did to initialize it:

    -

    var total = 0;
    +

    Since arrays are numbered sequentially, this means you can loop through them to perform extra actions too, just like we did to initialise it:

    +

    var _total = 0;

    for (var i = 0; i < 10; ++i)
    {
    -     total += array[i];
    -     draw_text(32, 32 + (i * 32), array[i]);
    +     _total += array[i];
    +     draw_text(32, 32 + (i * 32), array[i]);
    }

    - draw_text(32, 32 + (i * 32), total); + draw_text(32, 32 + (i * 32), _total);

    The above code will add up all the values in our array, draw each one of them and then draw the total value at the end.

           Deleting Arrays

    @@ -103,7 +103,7 @@

           Deleting Arrays

    We now know what a 1-dimensional array is, but in GameMaker you can have arrays with multiple dimensions, which are essentially structured as an array inside an array inside an array... For example, the following is a 2D (two-dimensional) array:

    array[0][0] = 5;

    -

    This is essentially telling GameMaker that the array is actually comprised of various 1D arrays. Here's an extended example:

    +

    This is essentially telling GameMaker that the array is actually comprised of various 1D arrays. Here's an extended example:

    array[0][0] = 0;
    array[0][1] = 1;
    array[0][2] = 2;
    @@ -112,23 +112,23 @@

           Deleting Arrays

    array[1][1] = 4;
    array[1][2] = 5;

    -

    In the above code, array[0] holds another array, and so does array[1].

    +

    In the above code, array[0] holds another array, and so does array[1].

    Alternatively, to access 2D arrays you can also use the following syntax: 

    array[0, 0] = 5;

     The above syntax only works for 2D arrays.

    -

    A multi-dimension array needs to be initialised before use, the same as a single 1D array, and can hold real numbers, strings, and any other data type, just like any variable, making them ideal candidates for any game that needs to store large amounts of data in an easily accessible way (remember, you can loop through an array easily).

    -

    You can also initialize a multi-dimensional array within one statement by nesting 1-dimensional arrays:

    +

    A multi-dimensional array needs to be initialised before use, the same as a single 1D array, and can hold real numbers, strings, and any other data type, just like any variable, making them ideal candidates for any game that needs to store large amounts of data in an easily accessible way (remember, you can loop through an array easily).

    +

    You can also initialise a multi-dimensional array within one statement by nesting 1-dimensional arrays:

    two_dimensional_array = 
    [
        ["Apple", 10, 2],
        ["Orange", 5, 2],
        ["Mango", 15, 4],
        // ...and so on.
    - ]

    -

    Multi-dimension arrays are also not limited to just two dimensions, and you can have 3, 4 or more dimensions to an array as required in your code, just by adding [n] further arguments, eg:

    + ];

    +

    Multi-dimensional arrays are also not limited to just two dimensions, and you can have 3, 4 or more dimensions to an array as required in your code, just by adding [n] further arguments, e.g.:

    array[0][0][0] = 1;     // A three dimensional array
    array[0][0][0][0] = 1;  // A four dimensional array
    - // etc...

    + // Etc.

    It should be noted too that the length of each dimension in an array can be different, so you can have the initial array dimension with a length of 3, but the second dimension entry can be a different length for each slot in the first dimension; for example:

    array[2][2] = "3";
    array[2][1] = "2";
    @@ -142,10 +142,10 @@

           Deleting Arrays

    array[0][1] = 2;
    array[0][0] = 1;

    -

    In the above code, array[0] has 2 slots, array[1] has 4 slots and array[2] has 3 slots.

    +

    In the above code, array[0] has 2 slots, array[1] has 4 slots and array[2] has 3 slots.

           Extended Example

    Here is one final example of how this may be used in an actual game: Say you want to spawn four different enemies at four different points in your game depending on a random value. Well, we can use an array with 2 dimensions to do this and save writing out a load of code.

    -

    First we should initialize the array we are going to use in the Create event of our "controller" object (note the use of comments to remind you what each array entry does):

    +

    First we should initialise the array we are going to use in the Create event of our "controller" object (note the use of comments to remind you what each array entry does):

    enemy[3][2] = 448;       //y position
    enemy[3][1] = 32;        //x position
    enemy[3][0] = obj_Slime; //Object
    @@ -165,7 +165,7 @@

           Extended Example

    //Use the array to create the object
    instance_create_layer(enemy[i][1], enemy[i][2], "Enemy_Layer", enemy[i][0]);

    -

    That short code will now spawn a random enemy in the game room, and it uses far less code than an "if / then / else" structure or even a "switch", and as the array is initialized all together in the create event it is MUCH easier to edit and change any of those values as they are not hard-coded into the rest of the project code.

    +

    That short code will now spawn a random enemy in the game room, and it uses far less code than an "if / then / else" structure or even a "switch", and as the array is initialised all together in the Create event it is MUCH easier to edit and change any of those values as they are not hard-coded into the rest of the project code.

     

    Also see: Array Functions

    @@ -185,22 +185,22 @@

    Arrays as Function Arguments


    show_debug_message(my_array); // Prints [2, 4, 6];

    -

    In previous GameMaker versions, this was not the case, as modifying an array inside a function would create a copy instead. This deprecated behaviour can still be enabled if desired: read the "Copy on Write" section below for more information.

    -

    Copy on Write

    +

    In previous GameMaker versions, this was not the case, as modifying an array inside a function would create a copy instead. This deprecated behaviour can still be enabled if desired: read the "Copy on Write" section below for more information.

    +

    Copy on Write 

    The Copy on Write behaviour is deprecated, and is only used when "Enable Copy on Write behaviour for Arrays" is enabled in the General Game Options. This section describes the behaviour of arrays when this option is enabled.

    -

    As described in the previous section, arrays can be passed into functions as arguments. To do this, you simply have to specify the array variable (no need for each of the individual positions, nor the [] brackets) and the entire array will be passed by reference into the function:

    +

    As described in the previous section, arrays can be passed into functions as arguments. To do this, you simply have to specify the array variable (no need for each of the individual positions, nor the [ ] brackets) and the entire array will be passed by reference into the function:

    my_array = [1, 2, 4, 8, 16];

    do_something(my_array);

    However, when Copy on Write is enabled, changing any of the array's values inside the function creates a temporary copy with your modifications. The original array is not modified. This behaviour is called Copy on Write.

    -

    To actually modify the original array that was passed into the function, you must either return it back, or use the @ accessor.

    +

    To actually modify the original array that was passed into the function, you must either return it back, or use the @ accessor.

    For example, the function called above, do_something(), may do something simple like this:

    do_something = function(array)
    {
        array[1] = 200;
    }

    -

    Now you would expect my_array to hold the values 1, 200, 4, etc., which would normally be correct -- but when Copy on Write is enabled, the original array remains unaffected.

    +

    Now you would expect my_array to hold the values 1, 200, 4, etc., which would normally be correct - but when Copy on Write is enabled, the original array remains unaffected.

    To work around this, you can make the function return the modified array copy, and then apply it back to the original variable:

    my_array = [1, 2, 4, 8, 16];

    @@ -214,8 +214,8 @@

    Copy on Write

        return array;
    }

    -

    NOTE The above code is not necessary if you are not changing any of the array's values, but rather referencing them. Referencing an array will not copy it and will be faster to parse.

    -

    The second solution is to use the @ accessor to change the array values directly, which saves the CPU overhead of having to make a temporary copy. This means that you do not need to return the array from the function and can edit it directly:

    +

     The above code is not necessary if you are not changing any of the array's values, but rather referencing them. Referencing an array will not copy it and will be faster to parse.

    +

    The second solution is to use the @ accessor to change the array values directly, which saves the CPU overhead of having to make a temporary copy. This means that you do not need to return the array from the function and can edit it directly:

    do_something = function(array)
    {
        array[@ 1] = 200;
    @@ -224,19 +224,18 @@

    Copy on Write

    Again, all of this is not necessary if Copy on Write is disabled (which is the default and recommended option).

    Find out more information on accessors and how they work, along with an example for arrays, from the following page:

     

     

    -

     

    - +
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved

    part_system_create_layer

    -

    This function creates a new particle system on a given layer and returns its handle.

    -

    You give the unique layer ID as returned by the function layer_create or the name of the layer to use as a string - for example "instance_layer" - and then flag the system as being persistent or not.

    +

    This function creates a new particle system on the given layer and returns its handle.

    +

    You give the unique layer ID as returned by the function layer_create or the name of the layer to use as a string - for example "instance_layer" - and then flag the system as being persistent or not.

    Optionally you can provide a Particle System Asset created using The Particle System Editor. Doing so will create the system defined in that asset, with all of its emitters.

    A system not flagged as persistent is automatically destroyed at the end of the room it was created in (this is the same as if you had called the function part_system_destroy and will also destroy any emitters associated with the system). However, when flagged as persistent, the system will be carried to the next room when the room is changed, and if the following room does not have a layer with the same name or depth as the one assigned, then a new layer will be created for the system that is persisting across the rooms, and it will be named the same as the original layer. When changing rooms, if there is another layer in the following rooms with the same name, then the persisted instance will be assigned to the layer with that name regardless of the depth of the layer. Finally, if a persisted system moves to a room with a layer at the same depth as the layer the system was created on, it will not be assigned to this layer, but instead a new layer will be created at the same depth (with the same name as the original layer).

     If you flag the particle system as persistent, it will need to be cleaned up manually using part_system_destroy when not in use, otherwise you risk a memory leak that will negatively impact your final game.

    @@ -39,7 +39,7 @@

    Syntax:

    persistent Boolean - Flag the particle system as persistent (set to true) or not (set to false) + Flag the particle system as persistent (set to true) or not (set to false) partsys @@ -53,8 +53,8 @@

    Returns:

    Particle System Instance

     

    Example:

    -

    global.p_sys = part_system_create_layer("effects_layer", true, ps_Explosion);

    -

    The above code will create a new particle system on the given layer from the ps_Explosion asset, and flag it as persisting over subsequent rooms. The ID for the particle system is stored in a global scope variable p_sys for future reference.

    +

    global.part_sys = part_system_create_layer("effects_layer", true, ps_explosion);

    +

    The above code creates a new particle system on the given layer from the ps_explosion asset, and flags it as persisting over subsequent rooms. The ID of the particle system is stored in a global scope variable part_sys for future reference.

     

     

    diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_destroy.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_destroy.htm index cd59d6975..19ba163f5 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_destroy.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_destroy.htm @@ -1,68 +1,67 @@ - + - - - part_system_destroy - - - - - - - - - -

    part_system_destroy

    -

    With this function you can destroy a given particles system and remove it from memory. This should always be called when the system is no longer needed, like at the end of a room, or in the destroy event of an instance, otherwise you could end up with particles appearing in later rooms and no way to remove them as well as a memory leak which will eventually crash your game.

    -

    This function will also destroy and remove any emitters that may have been created and associated with the system being destroyed.

    -

    -

    Syntax:

    -

    part_system_destroy(ind);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indParticle System IDThe particle system to destroy.
    -

    -

    Returns:

    -

    N/A

    -

    -

    Example:

    -

    if (global.player_hp <= 0) -
    - { -
    - part_system_destroy(p_sys); -
    - room_goto_next(); -
    - }

    -

    The above code checks to see if a global variable value is less than or equal to zero, and if it is then it destroys the particle system referenced in the given variable and then goes to the next room.

    -

    -

    -

    -
    -
    -
    - - -
    + + + part_system_destroy + + + + + + + + + + +

    part_system_destroy

    +

    This function destroys a given particle system instance, including all particles and emitters in it, and removes it from memory.

    +

    The function should always be called when the system is no longer needed, like at the end of a room, or in the Clean Up event of an instance, otherwise you could end up with particles appearing in later rooms and have no way to remove them as well as a memory leak which will eventually crash your game.

    +

     This function does not destroy the particle types used by the particle system. Types created with part_type_create should be destroyed using part_type_destroy, types used by particle system assets always exist.

    +

     

    +

    Syntax:

    +

    part_system_destroy(ind);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indParticle System InstanceThe particle system to destroy.
    +

     

    +

    Returns:

    +

    N/A

    +

     

    +

    Example: 

    +

    Create Event

    +

    part_sys = part_system_create(ps_effects);

    +

    Clean Up Event

    +

    part_system_destroy(part_sys);

    +

    The above code shows how to create a particle system instance from an asset and destroy it.

    +

    In the Create event, a particle system instance is created using part_system_create from an existing asset ps_effects created in The Particle System Editor. The instance is stored in a variable part_sys. In the Clean Up event, the particle system instance, including the emitters and particles in it, is destroyed using part_system_destroy.

    +

     

    +

     

    +
    +
    +
    + +
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    - + +--> + \ No newline at end of file From e6f63e8f768b0feb335833821cdd8aaecedb0a8f Mon Sep 17 00:00:00 2001 From: YYBartT Date: Wed, 16 Oct 2024 18:32:43 +0200 Subject: [PATCH 05/11] docs(general): No explanation of what needs to be cleaned up when creating an instance of a particle system asset YoYoGames/GameMaker-Bugs#7120 * Update of all Particles manual pages --- .../part_emitter_destroy.htm | 28 +-- .../part_emitter_destroy_all.htm | 36 ++-- .../Particle_Systems/Particle_Systems.htm | 2 +- .../Particle_Systems/part_particles_clear.htm | 119 ++++++------ .../Particle_Systems/part_particles_count.htm | 120 ++++++------ .../part_particles_create.htm | 159 ++++++++-------- .../part_particles_create_colour.htm | 173 +++++++++--------- .../Particle_Systems/part_system_angle.htm | 129 ++++++------- .../part_system_automatic_draw.htm | 119 ++++++------ .../part_system_automatic_update.htm | 128 ++++++------- .../Particle_Systems/part_system_clear.htm | 110 +++++------ .../Particle_Systems/part_system_colour.htm | 130 ++++++------- .../Particle_Systems/part_system_depth.htm | 120 ++++++------ .../Particle_Systems/part_system_drawit.htm | 126 +++++++------ .../Particle_Systems/part_system_exists.htm | 118 ++++++------ .../part_system_get_layer.htm | 17 +- .../Particle_Systems/part_system_layer.htm | 12 +- .../Particle_Systems/part_system_position.htm | 138 +++++++------- .../Particle_Systems/part_system_update.htm | 114 ++++++------ .../Particle_Types/part_type_alpha1.htm | 17 +- .../Particle_Types/part_type_alpha2.htm | 19 +- .../Particle_Types/part_type_alpha3.htm | 26 +-- .../Particle_Types/part_type_blend.htm | 26 +-- .../Particle_Types/part_type_clear.htm | 20 +- .../Particle_Types/part_type_create.htm | 6 +- .../Particle_Types/part_type_death.htm | 23 ++- .../Particle_Types/part_type_destroy.htm | 25 +-- .../Particle_Types/part_type_direction.htm | 23 ++- .../Particle_Types/part_type_exists.htm | 24 +-- .../Particle_Types/part_type_gravity.htm | 22 +-- .../Particle_Types/part_type_orientation.htm | 30 +-- .../Particle_Types/part_type_scale.htm | 21 +-- .../Particle_Types/part_type_shape.htm | 14 +- .../Particle_Types/part_type_speed.htm | 23 ++- .../Particle_Types/part_type_step.htm | 23 ++- ...ote_Part_System_Destroy_To_Destroy_All.hts | 14 ++ ...te_Particle_System_IDs_Used_By_Effects.hts | 14 ++ 37 files changed, 1154 insertions(+), 1114 deletions(-) create mode 100644 Manual/contents/assets/snippets/Note_Part_System_Destroy_To_Destroy_All.hts create mode 100644 Manual/contents/assets/snippets/Note_Particle_System_IDs_Used_By_Effects.hts diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Emitters/part_emitter_destroy.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Emitters/part_emitter_destroy.htm index c4c31cf71..2f1c7dd1f 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Emitters/part_emitter_destroy.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Emitters/part_emitter_destroy.htm @@ -4,7 +4,7 @@ part_emitter_destroy - + @@ -14,11 +14,14 @@ -

    part_emitter_destroy

    -

    This function will remove the specified emitter from the given system and clear it from memory (this will also stop any particles from being produced by the given emitter, but it does NOT remove them from the room). This function should always be called when the given emitter is no longer needed for the system to prevent memory leaks and errors.

    +

    part_emitter_destroy

    +

    This function removes the specified emitter from the given particle system and clears it from memory.

    +

    This will also stop any particles from being produced by the given emitter. Existing particles created by this emitter are not removed from the particle system.

    +

    This function should always be called when the given emitter is no longer needed for the system to prevent memory leaks and errors.

    +

     

    Syntax:

    -

    part_emitter_destroy( ps, ind );

    +

    part_emitter_destroy( ps, ind );

    @@ -28,12 +31,12 @@

    Syntax:

    - + - + @@ -43,22 +46,21 @@

    Returns:

    N/A

     

    Example:

    -

    if (part_emitter_exists(global.Sname, p_emit))
    +

    if (part_emitter_exists(global.Sname, p_emit))
    {
    -     part_emitter_destroy(global.Sname, p_emit1);
    +     part_emitter_destroy(global.Sname, p_emit);
    }

    -

    The above code will check to see if the particle emitter indexed in the variable "p_emit" exists in the give particle system and if it does it is destroyed.

    -

     

    +

    The above code will check to see if the particle emitter indexed in the variable p_emit exists in the give particle system and if it does it is destroyed.

     

     

    - - + +
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -

    part_emitter_destroy_all

    -

    This function will remove all defined emitters from the given system and clear them from memory (this will also stop any particles from being produced by the given emitter, but it does NOT remove them from the room). This function should always be called when the emitters are no longer needed for the system to prevent memory leaks and errors.

    +

    part_emitter_destroy_all

    +

    This function removes all defined emitters from the given particle system and clears them from memory.

    +

    This will also stop any particles from being produced by the emitters. Existing particles created by the emitters are not removed from the system.

    +

    This function should always be called when the emitters are no longer needed for the system to prevent memory leaks and errors.

    +

     

    Syntax:

    -

    part_emitter_destroy_all( ps );

    +

    part_emitter_destroy_all( ps );

    psParticle System IDParticle System Instance The particle system to destroy the emitter from.
    indParticle Emitter IDParticle Emitter ID The index of the emitter to destroy.
    - - + + + - + - + + - +
    ArgumentType
    ArgumentType Description
    pspsParticle System Instance The particle system to destroy all emitters from.

     

    Returns:

    -

    +

    N/A

     

    Example:

    -

    if (lives == 0)
    +

    if (lives == 0)
    {
        part_emitter_destroy_all(global.Sname);
        room_goto(rm_Menu);
    }

    -

    The above code checks the built in global variable "lives" and if it is 0, it destroys all particle emitters and then changes room.

    -

     

    +

    The above code checks the built-in global variable lives and if it is 0, it destroys all particle emitters and then changes room.

     

     

    - - + +
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved

    Particle Systems

    -

    Before you can create particles you need to create a particle system. This is a "container" where you place your particles and emitters (if you need them) ready for use, and you can put as many or as few particles into any one system as you think necessary, and you can have as many systems as you think necessary too. However, it is always better to keep this number as small as possible due to the fact that each system, emitter and particle takes up memory and having too many of them may slow your game down or cause problems. For example, if you need some effects to appear above instances, and other effects to appear beneath instances, you would create two systems and set their depths to get the desired effect, with all particles that are added to each system being drawn at the depth you specify.

    +

    Before you can create particles you need to create a particle system. This is a "container" where you place your particles and emitters (if you need them) ready for use, and you can put as many or as few particles into any one system as you think necessary, and you can have as many systems as you think necessary too. However, it is always better to keep this number as small as possible due to the fact that each system, emitter and particle takes up memory and having too many of them may slow your game down or cause problems. For example, if you need some effects to appear above instances, and other effects to appear below instances, you would create two systems and set their depths to get the desired effect, with all particles that are added to each system being drawn at the depth you specify.

    Since a particle system is a dynamically created resource, you must create it and store the returned index in a variable to reference the system in all further function calls, and it is very important that you also destroy the system when it is no longer needed or else you will have a memory leak that will slow down and eventually crash your game. It is also worth noting that particle systems will live on forever after they are created, even if the index is no longer stored. So even if you change room or restart the game, the systems and the particles will remain, and be visible, in all further rooms so you better make sure you destroy them once you no longer need them.

    Copy GML to Clipboard

    diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_particles_clear.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_particles_clear.htm index 988e61d71..31593d9ff 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_particles_clear.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_particles_clear.htm @@ -1,67 +1,66 @@ - + - - - part_particles_clear - - - - - - - - - -

    part_particles_clear

    -

    With this function you can clear all the particles currently created by the system from the room. It does not reset or remove the particle types themselves, just their visual representation, and if you have any object streaming particles from an emitter, these particles disappear but will begin to appear again the next step after calling this code.

    -

    -

    Syntax:

    -

    part_particles_clear(ind);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indParticle System IDThe particle system.
    -

    -

    Returns:

    -

    N/A

    -

    -

    Example:

    -

    if (lives <= 0) -
    - { -
    - part_particles_clear(global.Sname); -
    - room_goto(rm_intro); -
    - }

    -

    The above code will check the value of the variable "lives" and if it is equal to 0, it clears all particles from the system and then changes room.

    -

    -

    -

    -
    -
    -
    - - -
    + + + part_particles_clear + + + + + + + + + + +

    part_particles_clear

    +

    This function clears all particles currently created by the system from the room.

    +

    It does not reset or remove the particle types themselves, just their visual representation, and if you have any object streaming particles from an emitter, these particles disappear but will begin to appear again the next step after calling this code.

    +

     

    +

    Syntax:

    +

    part_particles_clear(ind);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indParticle System InstanceThe particle system.
    +

     

    +

    Returns:

    +

    N/A

    +

     

    +

    Example:

    +

    if (lives <= 0)
    + {
    +     part_particles_clear(global.Sname);
    +     room_goto(rm_intro);
    + }

    +

    The above code will check the value of the variable lives and if it is equal to 0, it clears all particles from the system and then changes room.

    +

     

    +

     

    +
    +
    +
    + +
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    - + +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_particles_count.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_particles_count.htm index 23a55d273..3abf1dfc8 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_particles_count.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_particles_count.htm @@ -1,68 +1,66 @@ - + - - - part_particles_count - - - - - - - - - - -

    part_particles_count

    -

    With this function you can check to see if a particle system currently has any particles created in the room, and it will return the number of them too.

    -

    -

    Syntax:

    -

    part_particles_count(ind);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indParticle System IDThe particle system.
    -

    -

    Returns:

    -

    Real

    -

    -

    Example:

    -

    if (part_particles_count(Sname) == 0) -
    - { -
    - part_system_destroy(Sname); -
    - instance_destroy(); -
    - }

    -

    The above code will check the number of particles in the local particle system indexed in the variable "Sname" and if there are none, it will destroy the system and then the instance.

    -

    -

    -

    -
    -
    -
    - - -
    + + + part_particles_count + + + + + + + + + + + +

    part_particles_count

    +

    This function returns the number of particles that currently exist in the given particle system.

    +

     

    +

    Syntax:

    +

    part_particles_count(ind);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indParticle System InstanceThe particle system.
    +

     

    +

    Returns:

    +

    Real

    +

     

    +

    Example:

    +

    if (part_particles_count(Sname) == 0)
    + {
    +     part_system_destroy(Sname);
    +     instance_destroy();
    + }

    +

    The above code will check the number of particles in the local particle system indexed in the variable Sname and if there are none, it will destroy the system and then the instance.

    +

     

    +

     

    +
    +
    +
    + +
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    - + +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_particles_create.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_particles_create.htm index a1179cea9..9852621af 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_particles_create.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_particles_create.htm @@ -1,86 +1,87 @@ - + - - - part_particles_create - - - - - - - - - - -

    part_particles_create

    -

    This function is ideal for those effects that do not require any of the functionality offered by particle emitters (for example, to create smoke from a missile, or a simple explosion effect) as it permits you to quickly and easily create particles at any position in the game room. Note that you must have created the particle system and the particle type previously for this function to be used.

    -

    -

    Syntax:

    -

    part_particles_create(ind, x, y, parttype, number);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indParticle System IDThe particle system.
    xRealThe x coordinate of where to create the particles.
    yRealThe y coordinate of where to create the particles.
    parttypeParticle Type IDThe index (type) of the particles to be created.
    numberRealThe number of particles to create.
    -

    -

    Returns:

    -

    N/A

    -

    -

    Example:

    -

    if (mouse_check_button(mb_left)) -
    - { -
    - part_particles_create(sname, mouse_x, mouse_y, p_CursorEffect, 5); -
    - }

    -

    The above code checks for the mouse button being pressed and if it returns true it generates 5 particles at the mouse position.

    -

    -

    -

    -
    -
    -
    - - -
    + + + part_particles_create + + + + + + + + + + + +

    part_particles_create

    +

    This function permits you to quickly and easily create particles at any position in a particle system.

    +

    It is ideal for those effects that do not require any of the functionality offered by Particle Emitters (for example, to create smoke from a missile, or a simple explosion effect).

    +

     You must have created the particle system and the particle type previously for this function to be used.

    +

     

    +

    Syntax:

    +

    part_particles_create(ind, x, y, parttype, number);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indParticle System InstanceThe particle system.
    xRealThe x coordinate of where to create the particles.
    yRealThe y coordinate of where to create the particles.
    parttypeParticle Type IDThe index (type) of the particles to be created.
    numberRealThe number of particles to create.
    +

     

    +

    Returns:

    +

    N/A

    +

     

    +

    Example:

    +

    if (mouse_check_button(mb_left))
    + {
    +     part_particles_create(sname, mouse_x, mouse_y, p_CursorEffect, 5);
    + }

    +

    The above code checks for the left mouse button being pressed and if it returns true it generates 5 particles at the mouse position.

    +

     

    +

     

    +
    +
    +
    + +
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    - + +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_particles_create_colour.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_particles_create_colour.htm index eef9cddc0..7b3650e97 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_particles_create_colour.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_particles_create_colour.htm @@ -1,94 +1,95 @@ - + - - - part_particles_create_colour - - - - - - - - - - -

    part_particles_create_colour

    -

    This function is ideal for those effects that do not require any of the functionality offered by particle emitters (for example, to create smoke from a missile, or a simple explosion effect) as it permits you to quickly and easily create particles at any position in the game room. You can also colour the particles "on the fly" as they are created with this function, and this colour will over-ride the predefined colour of the particle, but it does not blend this colour over the particles lifetime. Note that you must have created the particle system and the particle type previously for this function to be used.

    -

    -

    Syntax:

    -

    part_particles_create_colour(ind, x, y, parttype, colour, number);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indParticle System IDThe particle system.
    xRealThe x coordinate of where to create the particles.
    yRealThe y coordinate of where to create the particles.
    parttypeParticle Type IDThe index (type) of the particles to be created.
    colourColourThe colour blending for the particles.
    numberRealThe number of particles to create.
    -

    -

    Returns:

    -

    N/A

    -

    -

    Example:

    -

    if (speed > 1) -
    - { -
    - var _c = choose(c_aqua, c_lime, c_fuchsia, c_orange); -
    - part_particles_create_colour(sname, x, y, p_Smoke, _c, 1); -
    - }

    -

    The above code will generate a single particle every step that the instance with the code has a speed greater than one. These particles will be of a random colour.

    -

    -

    -

    -
    -
    -
    - - -
    + + + part_particles_create_colour + + + + + + + + + + + +

    part_particles_create_colour

    +

    This function permits you to quickly and easily create particles at any position in a particle system.

    +

    It is ideal for those effects that do not require any of the functionality offered by Particle Emitters (for example, to create smoke from a missile, or a simple explosion effect).

    +

    You can also colour the particles "on the fly" as they are created with this function, and this colour will override the predefined colour of the particle, but it does not blend this colour over the particle's lifetime.

    +

     You must have created the particle system and the particle type previously for this function to be used.

    +

     

    +

    Syntax:

    +

    part_particles_create_colour(ind, x, y, parttype, colour, number);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indParticle System InstanceThe particle system.
    xRealThe x coordinate of where to create the particles.
    yRealThe y coordinate of where to create the particles.
    parttypeParticle Type IDThe index (type) of the particles to be created.
    colourColourThe colour blending for the particles.
    numberRealThe number of particles to create.
    +

     

    +

    Returns:

    +

    N/A

    +

     

    +

    Example:

    +

    if (speed > 1)
    + {
    +     var _c = choose(c_aqua, c_lime, c_fuchsia, c_orange);
    +     part_particles_create_colour(sname, x, y, p_Smoke, _c, 1);
    + }

    +

    The above code will generate a single particle every step that the instance with the code has a speed greater than one. These particles will be of a random colour.

    +

     

    +

     

    +
    +
    +
    + +
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    - + +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_angle.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_angle.htm index 5f2e78c19..f29334918 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_angle.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_angle.htm @@ -1,71 +1,72 @@ - + - - - part_system_angle - - - - - - - - - - -

    part_system_angle

    -

    This function changes the angle that the given particle system is rendered with.

    -

    -

    Syntax:

    -

    part_system_angle(ind, angle);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indParticle System IDThe particle system to change.
    angleRealThe new angle of the particle system.
    -

    -

    Returns:

    -

    N/A

    -

    -

    Example:

    -

    var _mouse_dir = point_direction(x, y, mouse_x, mouse_y); -
    - part_system_angle(pt_sys, _mouse_dir);

    -

    This gets the direction from the position of the instance towards the mouse cursor, and applies that as the angle of a particle system.

    -

    -

    -
    -
    -
    - - -
    + + + part_system_angle + + + + + + + + + + +

    part_system_angle

    +

    This function changes the angle that the given particle system is rendered with.

    +

     

    +

    Syntax:

    +

    part_system_angle(ind, angle);

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indParticle System InstanceThe particle system to change.
    angleRealThe new angle of the particle system.
    +

     

    +

    Returns:

    +

    N/A

    +

     

    +

    Example:

    +

    var _mouse_dir = point_direction(x, y, mouse_x, mouse_y);
    + part_system_angle(pt_sys, _mouse_dir);

    +

    This gets the direction from the position of the instance towards the mouse cursor, and applies that as the angle of a particle system.

    +

     

    +

     

    +
    +
    +
    + +
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    - + +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_automatic_draw.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_automatic_draw.htm index 0622dc206..1a792c646 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_automatic_draw.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_automatic_draw.htm @@ -1,65 +1,68 @@ - + - - - part_system_automatic_draw - - - - - - - - - -

    part_system_automatic_draw

    -

    This function can be used to switch off the drawing of a particle system so that any updates done to the system (automatic or otherwise) will not be seen. This is a purely visual option and when set to false you will not be able to see the particles as they are not drawn, but they still exists and are changing position, colour etc... as they would normally. When automatic drawing is off, you can explicitly order GameMaker to draw the current state of the particle system using the function part_system_drawit(), and if you set this function to true again you can switch automatic drawing back on.

    -

    One thing to note is that if you are using the simple effects created by the functions effect_create_above() or effect_create_below() then you can use the values of 0 (for below effects) or 1 (for above effects) as the particle system index and so toggle the automatic draw for these too (this will also work to toggle drawing for the GML Visual particle effects).

    -

    -

    Syntax:

    -

    part_system_automatic_draw(ind, automatic);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indParticle System IDThe particle system to change.
    automaticBooleanWhether automatic drawing is on (true) or not (false).
    -

    -

    Returns:

    -

    N/A

    -

    -

    Example:

    -

    part_system_automatic_draw(global.Sname, false);

    -

    The above code switches off automatic drawing for the particle system indexed in the global variable "Sname".

    -

    -

    -

    -
    -
    -
    - - -
    + + + part_system_automatic_draw + + + + + + + + + + +

    part_system_automatic_draw

    +

    This function can be used to switch off the drawing of a particle system so that any updates done to the system (automatic or otherwise) will not be seen.

    +

    This is a purely visual option and when set to false you will not be able to see the particles as they are not drawn, but they still exist and are changing position, colour, etc. as they would normally. When automatic drawing is off, you can explicitly order GameMaker to draw the current state of the particle system using the function part_system_drawit, and if you set this function to true again you can switch automatic drawing back on.

    +
    +

     

    +

    Syntax:

    +

    part_system_automatic_draw(ind, automatic);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indParticle System InstanceThe particle system to change.
    automaticBooleanWhether automatic drawing is on (true) or not (false).
    +

     

    +

    Returns:

    +

    N/A

    +

     

    +

    Example:

    +

    part_system_automatic_draw(global.Sname, false);

    +

    The above code switches off automatic drawing for the particle system indexed in the global variable Sname.

    +

     

    +

     

    +
    +
    +
    + +
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    - + +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_automatic_update.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_automatic_update.htm index e6d6fd01b..eed60baa8 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_automatic_update.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_automatic_update.htm @@ -1,71 +1,71 @@ - + - - - part_system_automatic_update - - - - - - - - - -

    part_system_automatic_update

    -

    This function controls whether GameMaker should update the particle system automatically or not, and normally you would not need to use this function as the default value of true (automatic update is on) is what you wish to happen. However, for special effects or for pausing the game, you can set this to false and it will prevent any updates being carried out on the given particle system unless explicitly commanded by the use of the function part_system_update() or you use this function again to turn automatic updates on. No updating means that particles created in this system will no longer change position, colour or any other parameter and that emitters will cease to work too, "freezing" the system at the exact point in which the automatic update was set to false.

    -

    One thing to note is that if you are using the simple effects created by the functions effect_create_above() or effect_create_below() then you can use the values of 0 (for below effects) or 1 (for above effects) as the particle system index and so toggle the automatic update for these too (this will also work to toggle updating for the GML Visual particle effects).

    -

    -

    Syntax:

    -

    part_system_automatic_update(ind, automatic);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indParticle System IDThe particle system to change.
    automaticBooleanWhether automatic updating is on (true) or not (false).
    -

    -

    Returns:

    -

    N/A

    -

    -

    Example:

    -

    if (global.Pause) -
    - { -
    - part_system_automatic_update(global.Sname, false); -
    - }

    -

    The above code will switch off the particle updates if the global variable "Paused" is true.

    -

    -

    -

    -
    -
    -
    - - -
    + + + part_system_automatic_update + + + + + + + + + + +

    part_system_automatic_update

    +

    This function controls whether GameMaker should update the particle system automatically or not.

    +

    Normally you would not need to use this function as the default value of true (automatic update is on) is what you wish to happen. However, for special effects or for pausing the game, you can set this to false and it will prevent any updates being carried out on the given particle system unless explicitly commanded by the use of the function part_system_update or you use this function again to turn automatic updates on. No updating means that particles created in this system will no longer change position, colour or any other parameter and that emitters will cease to work too, "freezing" the system at the exact point in which the automatic update was set to false.

    +
    +

     

    +

    Syntax:

    +

    part_system_automatic_update(ind, automatic);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indParticle System InstanceThe particle system to change.
    automaticBooleanWhether automatic updating is on (true) or not (false).
    +

     

    +

    Returns:

    +

    N/A

    +

     

    +

    Example:

    +

    if (global.pause)
    + {
    +     part_system_automatic_update(global.Sname, false);
    + }

    +

    The above code will switch off the particle updates if the global variable pause is true.

    +

     

    +

     

    +
    +
    +
    + +
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    - + +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_clear.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_clear.htm index 82fc1a829..2929a0166 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_clear.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_clear.htm @@ -1,61 +1,63 @@ - + - - - part_system_clear - - - - - - - - - -

    part_system_clear

    -

    With this function you can clear the given particle system to its default state, removing all emitters and resetting the depth and position (if they had been changed). Be careful using this function as if you have any instance setting or bursting or any other action using an emitter associated with this system, you will get an error unless you are using the part_emitter_exists() function to check. There is also no need to call the part_emitter_destroy() function as this is taken care of automatically too.

    -

    NOTE: this function will clear the visible particles in the room, but it does not clear the particle properties, nor does it remove them from memory. For that you should use the functions part_type_clear() and part_type_destroy().

    -

    -

    Syntax:

    -

    part_system_clear(ind);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indParticle System IDThe particle system to clear.
    -

    -

    Returns:

    -

    N/A

    -

    -

    Example:

    -

    part_system_clear(global.Sname);

    -

    The above code will clear the particle system indexed in the global variable "Sname" to its default state.

    -

    -

    -

    -

    -
    -
    -
    - - -
    + + + part_system_clear + + + + + + + + + + +

    part_system_clear

    +

    This function clears the given particle system to its default state, removing all emitters and resetting its depth and position (if they had been changed).

    +

    You should be careful using this function as if you have any instance setting or bursting or any other action using an emitter associated with this system, you will get an error unless you are using the part_emitter_exists function to check. There is also no need to call the part_emitter_exists function as this is taken care of automatically too.

    +

     This function will clear the visible particles in the particle system, but it does not clear the particle properties, nor does it remove them from memory. For that you should use the functions part_type_clear and part_type_destroy.

    +

     

    +

    Syntax:

    +

    part_system_clear(ind);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indParticle System InstanceThe particle system to clear.
    +

     

    +

    Returns:

    +

    N/A

    +

     

    +

    Example:

    +

    part_system_clear(global.Sname);

    +

    The above code will clear the particle system indexed in the global variable Sname to its default state.

    +

     

    +

     

    +
    +
    +
    + +
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    - + +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_colour.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_colour.htm index 5f59c6cef..2ca27e9d5 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_colour.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_colour.htm @@ -1,12 +1,13 @@ - + - - - part_system_colour - - - - - -

    part_system_colour

    -

    This function changes the blend colour and alpha that the given particle system is rendered with. This is similar to image_blend and image_alpha in instances.

    -

    -

    Syntax:

    -

    part_system_color(ind, color, alpha);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indParticle System IDThe particle system to change.
    colorColourThe new colour of the particle system.
    alphaRealThe new alpha of the particle system.
    -

    -

    Returns:

    -

    N/A

    -

    -

    Example:

    -

    part_system_colour(pt_sys, c_red, 0.5);

    -

    This changes the colour of a particle system to red, with an alpha of 0.5.

    -

    -

    -
    -
    -
    - - -
    + //]]> + + + +

    part_system_colour

    +

    This function changes the blend colour and alpha that the given particle system is rendered with. This is similar to image_blend and image_alpha in instances.

    +

     

    +

    Syntax:

    +

    part_system_colour(ind, color, alpha);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indParticle System InstanceThe particle system to change.
    colorColourThe new colour of the particle system.
    alphaRealThe new alpha of the particle system.
    +

     

    +

    Returns:

    +

    N/A

    +

     

    +

    Example:

    +

    part_system_colour(pt_sys, c_red, 0.5);

    +

    This changes the colour of a particle system to red, with an alpha of 0.5.

    +

     

    +

     

    +
    +
    +
    + +
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    - + +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_depth.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_depth.htm index ad2ceab41..617810abc 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_depth.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_depth.htm @@ -1,66 +1,68 @@ - + - - - part_system_depth - - - - - - - - - -

    part_system_depth

    -

    With this function you can set the draw depth for the particle system, much the same as you can set the render depth of different layers within the room, where a low draw depth means that it will appear on top of all things drawn with a higher depth, and a high draw depth placing it below everything with a lower draw depth.

    -
    -

    -

    Syntax:

    -

    part_system_depth(ind, depth);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indParticle System InstanceThe particle system to change.
    depthRealThe depth at which to set the particle system.
    -

    -

    Returns:

    -

    N/A

    -

    -

    Example:

    -

    global.Sname = part_system_create(); -
    - part_system_depth(global.Sname, -1000);

    -

    The above code will create a particle system and store its index in the global variable "Sname". this system is then given a low depth of -1000, meaning that it will appear above everything with a higher draw depth.

    -

    -

    -
    -
    -
    - - -
    + + + part_system_depth + + + + + + + + + + +

    part_system_depth

    +

    With this function you can set the draw depth for the particle system, much the same as you can set the render depth of different layers within the room, where a low draw depth means that it will appear on top of all things drawn with a higher depth, and a high draw depth placing it below everything with a lower draw depth.

    +
    +

     

    +

    Syntax:

    +

    part_system_depth(ind, depth);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indParticle System InstanceThe particle system to change.
    depthRealThe depth at which to set the particle system.
    +

     

    +

    Returns:

    +

    N/A

    +

     

    +

    Example:

    +

    global.Sname = part_system_create();
    + part_system_depth(global.Sname, -1000);

    +

    The above code will create a particle system and store its index in the global variable Sname. this system is then given a low depth of -1000, meaning that it will appear above everything with a higher draw depth.

    +

     

    +

     

    +
    +
    +
    + +
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    - + +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_drawit.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_drawit.htm index cf6ac3590..27656af60 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_drawit.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_drawit.htm @@ -1,71 +1,69 @@ - + - - - part_system_drawit - - - - - - - - - -

    part_system_drawit

    -

    This function draws the given particle system.

    -

    By default, every particle system that you create is drawn automatically by GameMaker. You can also draw it manually using this function.

    -

    If part_system_automatic_draw is switched off then this function will show the particles when used in the draw event of an instance. It can also be used when the drawing target is set to a surface (using surface_set_target) to draw the particles in the system to that surface.

    -

    Call this function in any of the Draw Events to draw the particle system whenever you want. Call it in a Draw End event to draw the particles in front of other graphics or in one of the Draw GUI events to draw them on the GUI layer.

    -

    -

    Syntax:

    -

    part_system_drawit(ind);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indParticle System IDThe particle system to draw.
    -

    -

    Returns:

    -

    N/A

    -

    -

    Example:

    -

    if (surface_exists(surf)) -
    - { -
    - surface_set_target(surf); -
    - part_system_drawit(global.psys); -
    - surface_reset_target(); -
    - }

    -

    The above code checks to see if the surface indexed in the variable surf exists. If it does it then sets the drawing target to the surface, draws the particle system with the ID stored in the global variable, and then resets the drawing target so all normal drawing appears on the screen once more.

    -

    -

    -
    -
    -
    - - -
    + + + part_system_drawit + + + + + + + + + + +

    part_system_drawit

    +

    This function draws the given particle system.

    +

    By default, every particle system that you create is drawn automatically by GameMaker. You can also draw it manually using this function.

    +

    If part_system_automatic_draw is switched off then this function will show the particles when used in the draw event of an instance. It can also be used when the drawing target is set to a surface (using surface_set_target) to draw the particles in the system to that surface.

    +

    Call this function in any of the Draw Events to draw the particle system whenever you want. Call it in a Draw End event to draw the particles in front of other graphics or in one of the Draw GUI events to draw them on the GUI layer.

    +

     

    +

    Syntax:

    +

    part_system_drawit(ind);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indParticle System InstanceThe particle system to draw.
    +

     

    +

    Returns:

    +

    N/A

    +

     

    +

    Example:

    +

    if (surface_exists(surf))
    + {
    +     surface_set_target(surf);
    +     part_system_drawit(global.psys);
    +     surface_reset_target();
    + }

    +

    The above code checks to see if the surface indexed in the variable surf exists. If it does it then sets the drawing target to the surface, draws the particle system with the ID stored in the global variable, and then resets the drawing target so all normal drawing appears on the screen once more.

    +

     

    +

     

    +
    +
    +
    + +
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    - + +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_exists.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_exists.htm index 1909f3700..4d7edb4fe 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_exists.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_exists.htm @@ -1,66 +1,66 @@ - + - - - part_system_exists - - - - - - - - - - -

    part_system_exists

    -

    With this function you can check to see if the given particle system indexed exists in the game or not. Note that if the variable being checked is an uninitialised variable (that a particle system would otherwise have its index assigned to) this will throw an error.

    -

    -

    Syntax:

    -

    part_system_exists(ind);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indParticle System IDThe particle system to check for.
    -

    -

    Returns:

    -

    Boolean

    -

    -

    Example:

    -

    if (!part_system_exists(global.Sname)) -
    - { -
    - global.Sname = part_system_create(); -
    - }

    -

    The above code checks to see if the particle system referenced in the global variable exists and if it does not it is created.

    -

    -

    -

    -
    -
    -
    - - -
    + + + part_system_exists + + + + + + + + + + + +

    part_system_exists

    +

    This function checks to see if the given particle system exists in the game or not.

    +

    Note that if the variable being checked is an uninitialised variable (that a particle system would otherwise have its index assigned to) this will throw an error.

    +

     

    +

    Syntax:

    +

    part_system_exists(ind);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indParticle System InstanceThe particle system to check for.
    +

     

    +

    Returns:

    +

    Boolean

    +

     

    +

    Example:

    +

    if (!part_system_exists(global.Sname))
    + {
    +     global.Sname = part_system_create();
    + }

    +

    The above code checks to see if the particle system referenced in the global variable exists and if it does not it is created.

    +

     

    +

     

    +
    +
    +
    + +
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    - + +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_get_layer.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_get_layer.htm index 567d8b90d..c783cab05 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_get_layer.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_get_layer.htm @@ -15,11 +15,12 @@ -

    part_system_get_layer

    -

    This function can be used to retrieve the layer handle for the given particle system. You supply the particle system handle (as returned by the function part_system_create_layer()) and the function will return the handle of the layer.

    +

    part_system_get_layer

    +

    This function retrieves the layer handle for the given particle system.

    +

    You supply the particle system handle (as returned by the function part_system_create_layer) and the function will return the handle of the layer.

     

    Syntax:

    -

    part_system_get_layer(ind);

    +

    part_system_get_layer(ind);

    @@ -39,19 +40,19 @@

    Returns:

    Layer or 0 (if the layer is an internally managed one)

     

    Example:

    -

    if (part_system_get_layer(global.p_sys) != "effects_layer")
    +

    var _effects_layer = layer_get_id("Particles");
    + if (part_system_get_layer(global.p_sys) != _effects_layer)
    {
    -     part_system_layer(global.p_sys, "effects_layer";
    +     part_system_layer(global.p_sys, _effects_layer);
    }

    The above code will check a particle system to see what layer it is on and if it is not on the given layer it will be changed.

     

     

    -

     

    - - + +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_layer.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_layer.htm index e1ac26072..b0517b929 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_layer.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_layer.htm @@ -14,11 +14,12 @@ -

    part_system_layer

    -

    This function can be used to switch a particle system from its current layer to a new one. You supply the particle system handle (as returned by the function part_system_create_layer()) and then the layer handle (as returned by the function layer_create() or the name of the layer to use as a string - for example "instance_layer" - as defined in the room editor), and the system will be moved to the new layer.

    +

    part_system_layer

    +

    This function moves a particle system from its current layer to a new one.

    +

    You supply the particle system handle (as returned by the function part_system_create_layer) and then the layer handle (as returned by the function layer_create or the name of the layer to use as a string - for example "instance_layer" - as defined in the Room Editor), and the system will be moved to the new layer.

     

    Syntax:

    -

    part_system_layer(ps, layer);

    +

    part_system_layer(ps, layer);

    @@ -50,12 +51,11 @@

    Example:

    The above code will check a particle system to see what layer it is on and if it is not on the given layer it will be changed.

     

     

    -

     

    - - + +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_position.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_position.htm index ea8ac024a..f104cc9f6 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_position.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_position.htm @@ -1,76 +1,76 @@ - + - - - part_system_position - - - - - - - - - -

    part_system_position

    -

    With this function you can set the base position for the particle system relative to the (0,0) position of the room, meaning that all further particle functions relating to this system will now be drawn relative to the new position. By default this position is always (0,0), but in some very special circumstances you may wish to change this to something else.

    -

    NOTE: This function will change everything within the particle system, so if you have an emitter at position (100,100) and then set the particle system position to (0,100), the emitter will now draw at (100,200). The same goes if you shift the system and then create the emitter, as even though you create it at (100,100) it will be drawn at (100,200).

    -

    -

    Syntax:

    -

    part_system_position(ind, x, y);

    -
    - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indParticle System IDThe particle system to change.
    xRealThe new x coordinate of the particle system.
    yRealThe new y coordinate of the particle system.
    -

    -

    Returns:

    -

    N/A

    -

    -

    Example:

    -

    if (mouse_check_button_pressed(mb_left)) -
    - { -
    - part_system_position(global.Sname, mouse_x, mouse_y); -
    - }

    -

    The above code will check for the press of the mouse button and if it detects one, the particle system indexed in the global variable "Sname" is shifted to the mouse x/y position

    -

    -

    -

    -
    -
    -
    - - -
    + + + part_system_position + + + + + + + + + + +

    part_system_position

    +

    This function sets the base position for the particle system relative to the (0, 0) position of the room.

    +

    As a result, all further particle functions relating to this system will now be drawn relative to the new position. By default this position is always (0, 0), but in some very special circumstances you may wish to change this to something else.

    +

     This function will change everything within the particle system, so if you have an emitter at position (100, 100) and then set the particle system position to (0, 100), the emitter will now draw at (100, 200). The same goes if you shift the system and then create the emitter, as even though you create it at (100, 100) it will be drawn at (100, 200).

    +

     

    +

    Syntax:

    +

    part_system_position(ind, x, y);

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indParticle System InstanceThe particle system to change.
    xRealThe new x coordinate of the particle system.
    yRealThe new y coordinate of the particle system.
    +

     

    +

    Returns:

    +

    N/A

    +

     

    +

    Example:

    +

    if (mouse_check_button_pressed(mb_left))
    + {
    + part_system_position(global.Sname, mouse_x, mouse_y);
    + }

    +

    The above code will check for the press of the mouse button and if it detects one, the particle system indexed in the global variable Sname is shifted to the mouse x/y position.

    +

     

    +

     

    +
    +
    +
    + +
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    - + +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_update.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_update.htm index de2be2248..6e025bb5e 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_update.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_update.htm @@ -1,64 +1,64 @@ - + - - - part_system_update - - - - - - - - - -

    part_system_update

    -

    This function will advance the given particle system one step in game time and can be used to simulate the particle system behaviour when automatic updating is off, or it can be used to advance a particle system to a specific point all in one step. For example, if you have a particle system for snow, and you want it to appear that the snow is falling right from the moment the player enters the room then you may wish to advance your snow particles for a few seconds in the create event of an instance so that the first time they are drawn, there are particles all over the screen (the code example below shows this). You can also use this function when automatic updating of the system is switched off by the function part_system_automatic_update to move the system along.

    -

    -

    Syntax:

    -

    part_system_update(ind);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indParticle System IDThe particle system to update.
    -

    -

    Returns:

    -

    N/A

    -

    -

    Example:

    -

    repeat (game_get_speed(gamespeed_fps) * 3) -
    - { -
    - part_system_update(global.RainSys); -
    - }

    -

    The above code will advance the particle system indexed in the global variable RainSys by 3 seconds.

    -

    -

    -
    -
    -
    - - -
    + + + part_system_update + + + + + + + + + + +

    part_system_update

    +

    This function will advance the given particle system one step in game time and can be used to simulate the particle system behaviour when automatic updating is off, or it can be used to advance a particle system to a specific point all in one step. For example, if you have a particle system for snow, and you want it to appear that the snow is falling right from the moment the player enters the room then you may wish to advance your snow particles for a few seconds in the Create event of an instance so that the first time they are drawn, there are particles all over the screen (the code example below shows this). You can also use this function when automatic updating of the system is switched off by the function part_system_automatic_update to move the system along.

    +

     

    +

    Syntax:

    +

    part_system_update(ind);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indParticle System InstanceThe particle system to update.
    +

     

    +

    Returns:

    +

    N/A

    +

     

    +

    Example:

    +

    repeat (game_get_speed(gamespeed_fps) * 3)
    + {
    +     part_system_update(global.RainSys);
    + }

    +

    The above code will advance the particle system indexed in the global variable RainSys by 3 seconds.

    +

     

    +

     

    +
    +
    +
    + +
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    - + +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Types/part_type_alpha1.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Types/part_type_alpha1.htm index dcfbb63ee..2f42ad03b 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Types/part_type_alpha1.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Types/part_type_alpha1.htm @@ -4,7 +4,7 @@ part_type_alpha1 - + @@ -14,11 +14,11 @@ -

    part_type_alpha1

    +

    part_type_alpha1

    This function is used to set a particle type to have a single alpha value (transparency) for the total duration of the lifetime of each individual particle, and this can be from 0 (transparent) to 1 (opaque).

     

    Syntax:

    -

    part_type_alpha1(ind, alpha1);

    +

    part_type_alpha1(ind, alpha1);

    @@ -28,12 +28,12 @@

    Syntax:

    - + - + @@ -47,15 +47,14 @@

    Example:

    The above code will set all particles created of the particle type indexed in the global variable "Snow_Part" to have an alpha value of 0.5 (semi-transparent).

     

     

    -

     

    - - + +
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -

    part_type_alpha2

    +

    part_type_alpha2

    This function can be used to set an alpha value (transparency) gradient for each particle created of the given type. The first alpha is that which all particles will start with, and the second alpha is the one on with which the particle will end with, and a smooth gradient change will occur to the alpha over the particles lifetime from one to the other. This can be from 0 (transparent) to 1 (opaque).

     

    Syntax:

    -

    part_type_alpha2(ind, alpha1, alpha2);

    +

    part_type_alpha2(ind, alpha1, alpha2);

    indParticle Type IDParticle Type ID The index of the particle type to change.
    alpha1RealReal The alpha of the particle.
    @@ -28,17 +28,17 @@

    Syntax:

    - + - + - + @@ -52,15 +52,14 @@

    Example:

    The above code will set all particles created of the particle type indexed in the global variable "Snow_Part" to have an alpha value of 0 (transparent) and then fade in to have an alpha of 1 (opaque) at the end of their lifetime.

     

     

    -

     

    - - + +
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -

    part_type_alpha3

    -

    This function can be used to set a three alpha (transparency) value gradient for each particle created of the given type. The first alpha is that which all particles will start with, and the second alpha is the one that will be blended to half way through its lifetime and the third alpha is the one with which the particle will end with. A smooth gradient change will occur through the alphas over the particles lifetime from one to the other.

    +

    part_type_alpha3

    +

    This function can be used to set a three alpha (transparency) value gradient for each particle created of the given type.

    +

    The first alpha is that which all particles will start with, and the second alpha is the one that will be blended to half way through its lifetime and the third alpha is the one with which the particle will end with. A smooth gradient change will occur through the alphas over the particle's lifetime from one to the other.

     

    Syntax:

    -

    part_type_alpha3(ind, alpha1, alpha2, alpha3);

    +

    part_type_alpha3(ind, alpha1, alpha2, alpha3);

    indParticle Type IDParticle Type ID The index of the particle type to change.
    alpha1RealReal The start alpha of the particle.
    alpha2RealReal The end alpha of the particle.
    @@ -28,22 +29,22 @@

    Syntax:

    - + - + - + - + @@ -54,18 +55,17 @@

    Returns:

     

    Example:

    part_type_alpha3( part_Health, 0.5, 1, 0);

    -

    The above code will make all particles created of the type indexed in the variable "part_Health" have an alpha blend from 0.5 to 1 to 0 over their lifetime.

    -

     

    +

    The above code will make all particles created of the type indexed in the variable part_Health have an alpha blend from 0.5 to 1 to 0 over their lifetime.

     

     

    - - + +
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -

    part_type_blend

    -

    With this function you can make your particles be drawn with an additive blend mode (true) or not (false). Additive blending is a special blend mode that adds the luminosity values of each particle as they overlap, so that light colours will gradually get brighter (until they appear white) as they overlap, and dark colours become more and more transparent with black being almost invisible. This function can give some beautiful particle effects but may not always be necessary. For example, a smoke trail would have additive blending off to keep the effect gray, but a flame effect would probably have it on to make the particles more translucent and brighter.

    +

    part_type_blend

    +

    This function you can make your particles be drawn with an additive blend mode (true) or not (false).

    +

    Additive blending is a special blend mode that adds the luminosity values of each particle as they overlap, so that light colours will gradually get brighter (until they appear white) as they overlap, and dark colours become more and more transparent with black being almost invisible. This function can give some beautiful particle effects but may not always be necessary. For example, a smoke trail would have additive blending off to keep the effect gray, but a flame effect would probably have it on to make the particles more translucent and brighter.

     

    Syntax:

    -

    part_type_blend(ind, additive);

    +

    part_type_blend(ind, additive);

    indParticle Type IDParticle Type ID The index of the particle type to change.
    alpha1RealReal The starting alpha of the particle.
    alpha2RealReal The halfway point alpha of the particle.
    alpha3RealReal The ending alpha of the particle.
    @@ -28,13 +29,13 @@

    Syntax:

    - + - - + +
    indParticle Type IDParticle Type ID The index of the particle type to change.
    additiveBooleanWhether the particles should be blended additively (true) or normally (false).BooleanWhether the particles should be blended additively (true) or normally (false).
    @@ -43,19 +44,18 @@

    Returns:

    N/A

     

    Example:

    -

    part_type_blend(part_Fire, true);

    -

    The above code will set all particles created of the particle type indexed in the variable "part_Fire" to have an additive blend mode.

    -

     

    +

    part_type_blend(part_fire, true);

    +

    The above code will set all particles created of the particle type indexed in the variable part_fire to have an additive blend mode.

     

     

    - - + +
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -

    part_type_clear

    -

    With this function you can "reset" a particle, returning all the values for each of the functions relating to the particle (life, colour, alpha, orientation etc...) to their default values. Note that this function does not remove any particles currently visible in the room from the screen, for that you should be using part_particles_clear().

    +

    part_type_clear

    +

    This function "resets" a particle type, returning all the values for each of the type's properties (life, colour, alpha, orientation, etc.) to their defaults.

    +

     This function does not remove any particles currently visible in the room, for that you should be using part_particles_clear.

     

    Syntax:

    -

    part_type_clear(ind);

    +

    part_type_clear(ind);

    @@ -28,7 +29,7 @@

    Syntax:

    - + @@ -39,18 +40,17 @@

    Returns:

     

    Example:

    part_type_clear(global.explode_part);

    -

    The above code will clear the particle type indexed in the global variable "explode_part" to its default values.

    -

     

    +

    The above code will clear the particle type indexed in the global variable explode_part to its default values.

     

     

    - - + +
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved

    part_type_create

    -

    With this function you can create a new particle type and the return value should be stored in a variable for use in all subsequent particle functions.

    +

    This function creates a new particle type. The return value should be stored in a variable for use in all subsequent particle functions.

     

    Syntax:

    part_type_create()

    @@ -25,8 +25,8 @@

    Returns:

    Particle Type ID

     

    Example:

    -

    mypart = part_type_create();

    -

    This will create a new particle type, storing its index in the variable mypart.

    +

    my_part = part_type_create();

    +

    This will create a new particle type, storing its index in the variable my_part.

     

     

    diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Types/part_type_death.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Types/part_type_death.htm index f78ffd088..c4a389231 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Types/part_type_death.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Types/part_type_death.htm @@ -4,7 +4,7 @@ part_type_death - + @@ -14,12 +14,12 @@ -

    part_type_death

    +

    part_type_death

    This function can be used to make your particle burst another type of particle at the end of its lifetime.

    -

    NOTE: NEVER use the same particle type as this will cause an infinite loop and can crash the game in seconds! Also, be very careful when using this as it can greatly increase the number of particles on-screen at a time and cause your games to slow down noticeably.

    +

     Never use the same particle type as this will cause an infinite loop and can crash the game in seconds! Also, be very careful when using this as it can greatly increase the number of particles on-screen at a time and cause your games to slow down noticeably.

     

    Syntax:

    -

    part_type_death(ind, death_number, death_type);

    +

    part_type_death(ind, death_number, death_type);

    indParticle Type IDParticle Type ID The index of the particle type to clear.
    @@ -29,17 +29,17 @@

    Syntax:

    - + - + - + @@ -74,18 +74,17 @@

    Example:

    part_type_blend(particle2, 0);
    part_type_life(particle2, 60, 60);
    part_type_death(particle1, 1, particle2);

    -

    The above code creates and defines two particles and sets the particle indexed in the variable "particle1" to create 1 particle of "particle2" at the end of its lifetime.

    -

     

    +

    The above code creates and defines two particles and sets the particle indexed in the variable particle1 to create 1 particle of particle2 at the end of its lifetime.

     

     

    - - + +
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -

    part_type_destroy

    -

    With this function you can remove the specified particle type from the game. When you use this function, all particles of the given type will disappear from the room and the particle itself is removed form memory, so this function should be used only when you no longer need the particle.

    +

    part_type_destroy

    +

    This function removes the specified particle type from the game.

    +

    When you use this function, all particles of the given type will disappear from the room and the particle itself is removed form memory, so this function should be used only when you no longer need the particle.

     

    Syntax:

    -

    part_type_destroy(ind);

    +

    part_type_destroy(ind);

    indParticle Type IDParticle Type ID The index of the particle type to change.
    death_numberRealReal The quantity of the new particle to create at the particle death. If a negative value, it will instead create a fraction chance one is created (eg -3 would mean that one is created every 3 or so steps).
    death_typeParticle Type IDParticle Type ID The index of the particle type to create at death.
    @@ -28,7 +29,7 @@

    Syntax:

    - + @@ -38,25 +39,27 @@

    Returns:

    N/A

     

    Example:

    -

    if (part_particles_count(smoke_sys) = 0)
    +

    if (part_particles_count(smoke_sys) == 0)
    {
        part_type_destroy(smoke_part);
        part_system_destroy(smoke_sys);
        instance_destroy();
    }
    - else alarm[0] = 1;

    + else
    + {
    +     alarm[0] = 1;
    + }

    The above code checks a particle system to see if any particles are currently visible in the room and if not, the particles, the system and the instance are destroyed.

     

     

    -

     

    - - + +
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -

    part_type_direction

    +

    part_type_direction

    This function is used to determine the direction of the particle when it is created and can also be used to make the particle increase or decrease its direction over its lifetime. The minimum and maximum direction values default at 0, which means that the particle will move to the right with no variation, but these values can be changed to limit the direction of movement following the standard GameMaker directions of 0 being right, 90 being up, 180 being left and 270 being down. If you set them to the same value the particles will only move in one direction.

    You can also set an increment value which will add (if a positive number) or subtract (if a negative number) an amount of degrees to the direction over its lifetime. This value can be a minimum of (+/-) 0.01.

    Finally, you can set the "wiggle" factor. This is a value that will be added or subtracted randomly to the direction each step of the particles lifetime. Obviously larger values are more pronounced than smaller ones, and this value can even be a negative with the maximum range being between -20 and 20.

     

    Syntax:

    -

    part_type_direction(ind, dir_min, dir_max, dir_incr, dir_wiggle);

    +

    part_type_direction(ind, dir_min, dir_max, dir_incr, dir_wiggle);

    indParticle Type IDParticle Type ID The index of the particle type to destroy.
    @@ -31,27 +31,27 @@

    Syntax:

    - + - + - + - + - + @@ -75,15 +75,14 @@

    Example:

    The above code will set various particle values including the direction which will be random value between 0 and 359 degrees. It will also go up by 1 degree each step and has a random amount added to it of anywhere between 0 and 20 each step too.

     

     

    -

     

    - - + +
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -

    part_type_exists

    -

    With this function you can check to see if the given particle type indexed exists in the game or not. Note that if the variable being checked is an uninitialised variable (that a particle type would otherwise have its index assigned to) this will throw an error.

    +

    part_type_exists

    +

    This function checks if the given particle type exists in the game or not.

    +

    Note that if the variable being checked is an uninitialised variable (that a particle type would otherwise have its index assigned to) this will throw an error.

     

    Syntax:

    -

    part_type_exists(ind);

    +

    part_type_exists(ind);

    indParticle Type IDParticle Type ID The index of the particle type to change.
    dir_minRealReal The minimum direction the particle can start at.
    dir_maxRealReal The maximum direction the particle can start at.
    dir_incrRealReal How much the particle direction should increase or decrease per step.
    dir_wiggleRealReal How much should randomly be added or subtracted from the particle's direction per step.
    @@ -29,32 +30,31 @@

    Syntax:

    - +
    indParticle Type IDParticle Type ID The index of the particle type to check for.

     

    Returns:

    -

    Boolean

    +

    Boolean

     

    Example:

    -

    if (!part_type_exists(global.p1))
    +

    if (!part_type_exists(global.p1))
    {
        global.p1 = part_type_create();
    }

    -

    The above code checks to see if the global variable "p1" stores the index of a particle type and if it does not it creates one.

    -

     

    +

    The above code checks to see if the global variable p1 stores the index of a particle type and if it does not it creates one.

     

     

    - - + +
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -

    part_type_gravity

    -

    This function will set the gravity that is to affect each particle of the given type that is created. The gravity strength value is added to the particle speed every step and is usually a small value like 0.5, while the direction is the direction of the gravity "pull" and follows the standard GameMaker directions of 0° being right, 90° being up, 180° being left and 270° being down.

    +

    part_type_gravity

    +

    This function sets the gravity that is to affect each particle of the given type that is created.

    +

    The gravity strength value is added to the particle speed every step and is usually a small value like 0.5, while the direction is the direction of the gravity "pull" and follows the standard GameMaker directions of 0° being right, 90° being up, 180° being left and 270° being down.

     

    Syntax:

    -

    part_type_gravity(ind, grav_amount, grav_direction);

    +

    part_type_gravity(ind, grav_amount, grav_direction);

    @@ -28,17 +29,17 @@

    Syntax:

    - + - + - + @@ -62,15 +63,14 @@

    Example:

    The above code will set various particle values including the gravity which will add 0.2 to the speed each step with a direction of 270º, so will pull the particle "down" towards the bottom of the screen.

     

     

    -

     

    - - + +
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -

    part_type_orientation

    -

    This function is used to determine the orientation of the particle sprite when it is created and can also be used to make the particle orientation increase or decrease over its lifetime. The minimum and maximum orientation values default at 0 but these values can be changed to randomise the orientation following the standard GameMaker directions of 0 degrees being right, 90 degrees being up, 180 degrees being left and 270 degrees being down. If you set them to the same value the particles will all be created with the same orientation.

    +

    part_type_orientation

    +

    This function determines the orientation of the particle sprite when it is created and can also be used to make the particle orientation increase or decrease over its lifetime.

    +

    The minimum and maximum orientation values default at 0 but these values can be changed to randomise the orientation following the standard GameMaker directions of 0 degrees being right, 90 degrees being up, 180 degrees being left and 270 degrees being down. If you set them to the same value the particles will all be created with the same orientation.

    You can also set an increment value which will add (if a positive number) or subtract (if a negative number) an amount of degrees to the orientation over its lifetime. This value can be a minimum of (+/-) 0.01.

    You can set the "wiggle" factor too, the same as other particle functions. This is a value that will be added or subtracted randomly to the orientation each step of the particles lifetime. Obviously larger values are more pronounced than smaller ones, and this value can even be a negative with the maximum range being between -20 and 20.

    Finally, you can choose to have the orientation relative or not, which means that while the particle has a direction (and speed) the particle sprite will be orientated around that vector. Bear in mind that if you have the particle speed set to reduce and it reaches 0, the lack of speed sets the direction to the default value of 0° and so a relative orientation will cause the particle sprite to "jump" to a different angle.

     

    Syntax:

    -

    part_type_orientation( ind, ang_min, ang_max, ang_incr, ang_wiggle, ang_relative );

    +

    part_type_orientation( ind, ang_min, ang_max, ang_incr, ang_wiggle, ang_relative );

    indParticle Type IDParticle Type ID The index of the particle type to change.
    grav_amountRealReal Strength of the gravity.
    grav_directionRealReal The direction of the gravity.
    @@ -32,33 +33,33 @@

    Syntax:

    - + - + - + - + - + - - + +
    indParticle Type IDParticle Type ID The index of the particle type to change.
    ang_minRealReal The minimum starting angle of the particles.
    ang_maxRealReal The maximum starting angle of the particles.
    ang_incrRealReal The increase (or decrease if set negative) of the angle in degrees per step.
    ang_wiggleRealReal The amount the angle wiggles clockwise/counterclockwise per step.
    ang_relativeRealWhether to set its angle relative to the direction of the particle's motion (true) or not (false).RealWhether to set its angle relative to the direction of the particle's motion (true) or not (false).
    @@ -80,15 +81,14 @@

    Example:

    The above code will set various particle values including the orientation which will be random value between 0º and 359º. It will also have a random amount added to it of anywhere between 0 and 20 each step too, and the orientation is relative to the direction of motion.

     

     

    -

     

    - - + +
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -

    part_type_scale

    -

    This function sets the horizontal and vertical scale of the particle before any other size changes are made. This function works on the ratio of the sprite size, so a value of 1 (the default value) is a 1:1 ratio, meaning that 0.5 would be half and 2 double.

    +

    part_type_scale

    +

    This function sets the horizontal and vertical scale of the particle before any other size changes are made. It works on the ratio of the sprite size, so a value of 1 (the default value) is a 1:1 ratio, meaning that 0.5 would be half and 2 double.

     

    Syntax:

    -

    part_type_scale(ind, xscale, yscale);

    +

    part_type_scale(ind, xscale, yscale);

    @@ -28,17 +28,17 @@

    Syntax:

    - + - + - + @@ -61,15 +61,14 @@

    Example:

    The above code will set various particle values including the scale which sets the xscale to eight times the size and the yscale to half the size.

     

     

    -

     

    - - + +
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -

    part_type_speed

    +

    part_type_speed

    This function is used to set the movement speed of the particle when it is created and can also be used to make the particle increase or decrease its speed over its lifetime. The minimum and maximum speed values default at 1, which means that the particle will move 1 pixel each step, and if they are set to the same value, the initial speed for all particles will be the same, but if set to different values, each particle will start with a random speed from within the given range. For example if you have a minimum of 3 and a maximum of 6, all particles will be created with a speed between three and six pixels per step.

    You can also set an increment value that will make the particle move faster (if a positive number) or slower (if a negative number) over its lifetime, with the given amount being added to the particle speed each and every step. This value can be a minimum of (+/-)0.01.

    Finally, you can set the "wiggle" factor. This is a value that will be added or subtracted randomly to the speed each step of the particles lifetime. Obviously larger values are more pronounced than smaller ones, and this value can even be a negative with the maximum range being between -20 and 20.

     

    Syntax:

    -

    part_type_speed(ind, speed_min, speed_max, speed_incr, speed_wiggle);

    +

    part_type_speed(ind, speed_min, speed_max, speed_incr, speed_wiggle);

    indParticle Type IDParticle Type ID The index of the particle type to change.
    xscaleRealReal The horizontal scaling of the base particle.
    yscaleRealReal The vertical scaling of the base particle.
    @@ -31,27 +31,27 @@

    Syntax:

    - + - + - + - + - + @@ -75,15 +75,14 @@

    Example:

    The above code will set various particle values including the speed which sets a minimum speed of five and a maximum speed of ten, with the speed slowing down by a value of -0.2 each step. The speed will also wiggle by a random value between 0 and 20 each step.

     

     

    -

     

    - - + +
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -

    part_type_step

    +

    part_type_step

    This function can be used to make your particle type stream another type each step until the end of its lifetime. You can set a negative value for the step number and a particle will be emitted at a random interval based on that, so that, for example, a value of -3 will have a 1:3 chance of emitting a particle each step.

    -

    NOTE: NEVER use the same particle type as this will cause an infinite loop and can crash the game in seconds! Also, be very careful when using this as it can greatly increase the number of particles on-screen at a time and cause your games to slow down noticeably.

    +

     Never use the same particle type as this will cause an infinite loop and can crash the game in seconds! Also, be very careful when using this as it can greatly increase the number of particles on-screen at a time and cause your games to slow down noticeably.

     

    Syntax:

    -

    part_type_step(ind, step_number, step_type);

    +

    part_type_step(ind, step_number, step_type);

    indParticle Type IDParticle Type ID The index of the particle type to change.
    speed_minRealReal The minimum speed the particle can start at.
    speed_maxRealReal The maximum speed the particle can start at.
    speed_incrRealReal How much the particle speed should increase or decrease per step.
    speed_wiggleRealReal How much should randomly be added or subtracted from the particle's speed per step.
    @@ -29,17 +29,17 @@

    Syntax:

    - + - + - + @@ -74,18 +74,17 @@

    Example:

    part_type_blend(particle3, 1);
    part_type_life(particle3, 40, 80);
    part_type_step(particle2, 2, particle3);

    -

    The above code creates and defines two particles and sets the particle indexed in the variable "particle2" to create 2 particles of "particle3" every step of its lifetime.

    -

     

    +

    The above code creates and defines two particles and sets the particle indexed in the variable particle2 to create 2 particles of particle3 every step of its lifetime.

     

     

    - - + +
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved

    The Extension Editor

    -

    An extension package can be used to add a number of additional functions and constants to the GameMaker Language (GML) and easily transfer them between projects. Extension functions can also be linked to external SDKs or source code written in other languages (like Java for Android, Objective-C for iOS, etc.), which can be used to expand your game's functionality (usually used for implementing third party APIs, such as for ads, in-app purchases, and more).

    +

    An extension package can be used to add a number of additional functions and constants to the GameMaker Language (GML) and easily transfer them between projects. Extension functions can also be linked to external SDKs or source code written in other languages (like Java for Android, Objective-C for iOS, etc.), which can be used to expand your game's functionality (usually used for implementing third-party APIs, such as for ads, in-app purchases, and more).

    Extensions Properties

    Extensions can be used for creating a library of functions that you use frequently across all your projects, so instead of having to import the same scripts into every project, you can simply add one extension asset that holds a collection of your favourite functions and constants. Such functions can also be specific to a certain platform, and you can easily choose which platforms an extension can be used on.

    For a step-by-step example on creating an extension, see: Creating An Extension

    From 98a95442a1300384586244089e4cdd8b87e6dd79 Mon Sep 17 00:00:00 2001 From: YYBartT Date: Fri, 18 Oct 2024 15:57:38 +0200 Subject: [PATCH 09/11] docs(general): removed space character in heading --- Manual/contents/GameMaker_Language/GML_Overview/Arrays.htm | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Manual/contents/GameMaker_Language/GML_Overview/Arrays.htm b/Manual/contents/GameMaker_Language/GML_Overview/Arrays.htm index 1a3334d91..1125fecbc 100644 --- a/Manual/contents/GameMaker_Language/GML_Overview/Arrays.htm +++ b/Manual/contents/GameMaker_Language/GML_Overview/Arrays.htm @@ -186,7 +186,7 @@

    Arrays as Function Arguments

    show_debug_message(my_array); // Prints [2, 4, 6];

    In previous GameMaker versions, this was not the case, as modifying an array inside a function would create a copy instead. This deprecated behaviour can still be enabled if desired: read the "Copy on Write" section below for more information.

    -

    Copy on Write 

    +

    Copy on Write

    The Copy on Write behaviour is deprecated, and is only used when "Enable Copy on Write behaviour for Arrays" is enabled in the General Game Options. This section describes the behaviour of arrays when this option is enabled.

    As described in the previous section, arrays can be passed into functions as arguments. To do this, you simply have to specify the array variable (no need for each of the individual positions, nor the [ ] brackets) and the entire array will be passed by reference into the function:

    my_array = [1, 2, 4, 8, 16];
    From db0625c824b51eff65157e7fc68d23c2bbab9e16 Mon Sep 17 00:00:00 2001 From: YYBartT Date: Mon, 21 Oct 2024 21:13:11 +0200 Subject: [PATCH 10/11] docs(general): Lighting-related built-in uniforms don't work correctly inside custom shaders YoYoGames/GameMaker-Bugs#6507 YoYoGames/GameMaker-Bugs#6509 * Added that draw_light_define_direction() normalises the vector for directional lights is normalised and that the normalised vector is returned by draw_light_get() * Added that shaders receive the negative of this normalised vector * Added the default value of the ambient colour on the draw_light_get_ambient() page --- .../Asset_Management/Shaders/Shader_Constants.htm | 2 +- .../Drawing/Lighting/draw_light_define_direction.htm | 3 ++- .../GML_Reference/Drawing/Lighting/draw_light_get.htm | 2 +- .../GML_Reference/Drawing/Lighting/draw_light_get_ambient.htm | 3 ++- 4 files changed, 6 insertions(+), 4 deletions(-) diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Asset_Management/Shaders/Shader_Constants.htm b/Manual/contents/GameMaker_Language/GML_Reference/Asset_Management/Shaders/Shader_Constants.htm index a509d2fd8..3d7feb176 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Asset_Management/Shaders/Shader_Constants.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Asset_Management/Shaders/Shader_Constants.htm @@ -106,7 +106,7 @@

    Uniforms

     - + diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Lighting/draw_light_define_direction.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Lighting/draw_light_define_direction.htm index be6a967ae..c2447e4df 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Lighting/draw_light_define_direction.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Lighting/draw_light_define_direction.htm @@ -16,7 +16,8 @@

    draw_light_define_direction

    This function defines a directional light.

    -

    The direction and intensity are set by the values input for the x, y and z unit vector (meaning that they must be between -1 and 1, where 1 or -1 is full intensity, and 0 is no intensity). The lights can also be given a colour, which will also affect the perceived intensity of the light as certain colours appear "darker" than others. You must also give the light an index number which is used in other functions to reference it.

    +

    The direction is set by the values input for x, y and z. The direction vector is stored normalised and is negated before being sent to the shader.

    +

    The lights can also be given a colour, which will also affect the perceived intensity of the light as certain colours appear "darker" than others. You must also give the light an index number which is used in other functions to reference it.

     

    Syntax:

    diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Lighting/draw_light_get.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Lighting/draw_light_get.htm index 9ae54a07a..643281de8 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Lighting/draw_light_get.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Lighting/draw_light_get.htm @@ -50,7 +50,7 @@

    draw_light_get

    indParticle Type IDParticle Type ID The index of the particle type to change.
    step_numberRealReal The quantity of the new particle to create per step.
    step_typeParticle Type IDParticle Type ID The index of the particle type to create per step.
    gm_Lights_Direction[] Vertex ShaderThis is an array uniform of vec4s, where each vec4 contains a light's normalised direction vector (X, Y, Z) and a fourth dimension (W) which is 1 when the light is enabled, and 0 when disabled. Light properties can be set using draw_light_define_direction.This is an array uniform of vec4s, where each vec4 contains a light's normalised direction vector (X, Y, Z) negated and a fourth dimension (W) which is 1 when the light is enabled, and 0 when disabled. Light properties can be set using draw_light_define_direction.
    gm_Lights_PosRange[]
    -

     The x, y and z values store the light's position in case of a point light and the light's direction vector in case of a directional light.

    +

     The x, y and z values store the light's position in case of a point light and the light's normalised direction vector in case of a directional light.

     

    Syntax:

    draw_light_get(ind)

    diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Lighting/draw_light_get_ambient.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Lighting/draw_light_get_ambient.htm index 305d75fba..18b5efc5f 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Lighting/draw_light_get_ambient.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Lighting/draw_light_get_ambient.htm @@ -17,6 +17,7 @@

    draw_light_get_ambient

    This function returns the current colour used for ambient lighting.

    +

    The default ambient colour is set to c_black with an alpha of 1 (i.e. opaque).

     

    Syntax:

    draw_light_get_ambient()

    @@ -25,7 +26,7 @@

    Returns:

    Colour

     

    Example:

    -

    light_col = draw_light_get_ambient();

    +

    light_col = draw_light_get_ambient();

    The above code will get the current ambient light colour and store it in a variable.

     

     

    From 138ee3b523d0d0621e307efffa2889e3b32aa5ff Mon Sep 17 00:00:00 2001 From: gurpreetsinghmatharoo Date: Tue, 22 Oct 2024 16:52:15 +0530 Subject: [PATCH 11/11] docs(feature): GX.games export text fix (Compiling page) --- Manual/contents/Introduction/Compiling.htm | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Manual/contents/Introduction/Compiling.htm b/Manual/contents/Introduction/Compiling.htm index a721e60ea..9eca10511 100644 --- a/Manual/contents/Introduction/Compiling.htm +++ b/Manual/contents/Introduction/Compiling.htm @@ -92,7 +92,7 @@

    How Different Targets Build

    • GX.games - When compiling for the "GX.games" target, you will first be asked the packaging option to use: 

      - Tick the Remember Packaging Option? checkbox here to use the same setting and not show this window again on subsequent builds.
      + Tick the "Remember Packaging Option?" checkbox here to use the same setting and not show this window again on subsequent builds.

      Next you'll see the "GX.games Packaging" window:
      If you chose to Save locally as a ZIP, GameMaker will immediately start compiling your game and show any output here. After the game is compiled you're prompted for a save location.