From 4cd353b05008fee3e1d6082a3cb1a2a1df7183ed Mon Sep 17 00:00:00 2001 From: gurpreetsinghmatharoo Date: Fri, 23 Aug 2024 11:45:13 +0530 Subject: [PATCH 01/13] docs(feature): New buffer error constants https://github.com/YoYoGames/GameMaker-Bugs/issues/7385 --- .../GML_Reference/Buffers/buffer_write.htm | 38 +++++++++++++++++-- Manual/variable/Default.var | 7 ++++ 2 files changed, 42 insertions(+), 3 deletions(-) diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Buffers/buffer_write.htm b/Manual/contents/GameMaker_Language/GML_Reference/Buffers/buffer_write.htm index adc34780c..0214cc295 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Buffers/buffer_write.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Buffers/buffer_write.htm @@ -19,7 +19,39 @@

buffer_write

The function will write your given value at the buffer's current seek position.

The following constants can be used to define the data type:

-

The function will return 0 if it succeeds or -1 if it fails.

+

The function will return 0 if it succeeds or one of the following constants in case of failure:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Buffer Error Constant
ConstantDescriptionValue
buffer_error_generalA general buffer error.-1
buffer_error_out_of_spaceThe buffer doesn't have enough space for the size of the type being written.-2
buffer_error_invalid_typeAttempting to write an invalid type to a buffer. For example, submitting a string value for a buffer_u16 type or a buffer_f16 into a "fast" buffer that only takes buffer_u8 values.-4

 

Syntax:

buffer_write(buffer, type, value);

@@ -49,7 +81,7 @@

Syntax:

 

Returns:

-

Real (0 if success, or -1 if it fails)

+

Real (0 if success) or Buffer Error Constant (if it fails)

 

Example:

buffer_seek(buff, buffer_seek_start, 0);
@@ -67,7 +99,7 @@

Example:

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

The_Game_Window.htm

+

The Game Window

The game you create happens in a window (even when fullscreen), and this window has a number of properties, like position, size, whether it is fullscreen, etc. These details are normally set automatically for you based on the room size and view ports enabled in combination with the settings from Game Options for the target platform, but you can change them during the game using the functions listed on this page.

 These functions are for Windows, Ubuntu, macOS, GX.games and HTML5 targets only and may not work on any other device.

The following image illustrates how some general window functions relate and interact with each other:

@@ -58,8 +58,8 @@

Border & Caption

  • window_get_caption
  • window_set_showborder
  • window_get_showborder
    • -
  • window_enable_borderless_fullscreen
    • -
  • window_get_borderless_fullscreen
    • +
  • window_enable_borderless_fullscreen
    • +
  • window_get_borderless_fullscreen

    • Dimensions & Position

    -

    When using this function you give the view port index (from 0 to 7) and a surface index (either the application_surface or the unique index value returned by the function surface_create()) or, if a surface has previously been assigned and you want to remove it, a value of -1. For more examples on setting the view port to a surface see the variable view_surface_id.

    +

    When using this function you give the view port index (from 0 to 7) and a surface index (either the application_surface or the handle returned by the function surface_create()) or, if a surface has previously been assigned and you want to remove it, a value of -1. For more examples on setting the view port to a surface see the variable view_surface_id.

     

    Syntax:

    @@ -34,22 +34,22 @@

    Syntax:

    view_port - Real + Real The view port to target (0 - 7) surf - Surface ID + Surface The surface to apply to the view

     

    Returns:

    -

    Real

    +

    Real

     

    Example:

    -

    if (view_get_surface_id(0) == -1)
    +

    if (view_get_surface_id(0) == -1)
    {
        view_set_surface_id(0, global.vSurf);
    }

    @@ -62,7 +62,7 @@

    Example:

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

    ds_grid_add

    -

    This function can be used to add a given value (real or string) to the value of the given cell within the grid. The value to be added must be the same type as that held within the grid cell, ie: you cannot add a string to a real or vice-versa, and for - strings this corresponds to concatenation.

    -

     

    -

    Syntax:

    -

    ds_grid_add(index, x, y, val);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid.
    xThe x position of the cell in the grid.
    yThe y position of the cell in the grid.
    valThe value to add to the cell.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    ds_grid_add(grid, 5, 5, 6)

    -

    This would add 6 to the given cell within the DS grid referenced by the variable "grid".

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    -
    Next: ds_grid_add_region
    + + + + ds_grid_add + + + + + + + + + +

    ds_grid_add

    +

    This function can be used to add a given value (real or string) to the value of the given cell within the grid. The value to be added must be the same type as that held within the grid cell, ie: you cannot add a string to a real or vice-versa, and for strings this corresponds to concatenation.

    +

    +

    Syntax:

    +

    ds_grid_add(index, x, y, val);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid.
    xThe x position of the cell in the grid.
    yThe y position of the cell in the grid.
    valThe value to add to the cell.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    ds_grid_add(grid, 5, 5, 6)

    +

    This would add 6 to the given cell within the DS grid referenced by the variable "grid".

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - - \ No newline at end of file +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_add_disk.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_add_disk.htm index 79340ad9c..2fea8765a 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_add_disk.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_add_disk.htm @@ -1,78 +1,79 @@ - - + - - - ds_grid_add_disk - - - - - - - - - - - -

    ds_grid_add_disk

    -

    This function can be used to add a given value (real or string) to all the values of the cells found within the defined disk area of a grid. The value to be added must be of the same type as that held within the grid cells, ie: you cannot add a string - to a real or vice-versa, and for strings this corresponds to concatenation.

    -

     

    -

    Syntax:

    -

    ds_grid_add_disk(index, xm, ym, r, val);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid.
    xmThe x position of the disk on the grid.
    ymThe y position of the disk on the grid.
    rThe radius of the disk on the grid.
    valThe value to add to the cells within the disk.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    ds_grid_add_disk(grid, 7, 6, 5, 2)

    -

    This would add 2 to all the values held in the cells within the defined disk area of the DS grid referenced by the variable "grid".

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + + ds_grid_add_disk + + + + + + + + + +

    ds_grid_add_disk

    +

    This function can be used to add a given value (real or string) to all the values of the cells found within the defined disk area of a grid. The value to be added must be of the same type as that held within the grid cells, ie: you cannot add a string to a real or vice-versa, and for strings this corresponds to concatenation.

    +

    +

    Syntax:

    +

    ds_grid_add_disk(index, xm, ym, r, val);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid.
    xmThe x position of the disk on the grid.
    ymThe y position of the disk on the grid.
    rThe radius of the disk on the grid.
    valThe value to add to the cells within the disk.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    ds_grid_add_disk(grid, 7, 6, 5, 2)

    +

    This would add 2 to all the values held in the cells within the defined disk area of the DS grid referenced by the variable "grid".

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - - \ No newline at end of file +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_add_grid_region.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_add_grid_region.htm index 27775fd3e..5c0dc8141 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_add_grid_region.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_add_grid_region.htm @@ -1,91 +1,96 @@ - - + - - - ds_grid_add_grid_region - - - - - - - - - - - -

    ds_grid_add_grid_region

    -

    This function can be used to add all the values of all the cells found within the source area of a grid to the values within the destination grid, as illustrated below:

    -

    DS grid add grid region

    -

    NOTE You can also use this function on the same grid to add values from one region of the grid to those stored in another (see code example below).

    -

     

    -

    Syntax:

    -

    ds_grid_add_grid_region(index, source, x1, y1, x2, y2, xpos, ypos);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the destination grid.
    sourceThe index of the source grid.
    x1The left position of the region of cells to copy from the source grid.
    y1The top position of the region of cells to copy from the source grid.
    x2The right position of the region of cells to copy from the source grid.
    y2The bottom position of the region of cells to copy from the source grid.
    xposThe x position on the destination grid to add the source region to.
    yposThe y position on the destination grid to add the source region to.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    ds_grid_add_grid_region(grid, grid, 0, 0, 1, 5, 2, 0)

    -

    The above code would copy the region of cells from (0,0) to (1,5) of the DS grid indexed in the variable "grid" and add them to the cells from position (2,0) of the same DS grid .

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + + ds_grid_add_grid_region + + + + + + + + + +

    ds_grid_add_grid_region

    +

    This function can be used to add all the values of all the cells found within the source area of a grid to the values within the destination grid, as illustrated below:

    +

    DS grid add grid region

    +

    NOTE You can also use this function on the same grid to add values from one region of the grid to those stored in another (see code example below).

    +

    +

    Syntax:

    +

    ds_grid_add_grid_region(index, source, x1, y1, x2, y2, xpos, ypos);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the destination grid.
    sourceThe handle of the source grid.
    x1The left position of the region of cells to copy from the source grid.
    y1The top position of the region of cells to copy from the source grid.
    x2The right position of the region of cells to copy from the source grid.
    y2The bottom position of the region of cells to copy from the source grid.
    xposThe x position on the destination grid to add the source region to.
    yposThe y position on the destination grid to add the source region to.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    ds_grid_add_grid_region(grid, grid, 0, 0, 1, 5, 2, 0)

    +

    The above code would copy the region of cells from (0,0) to (1,5) of the DS grid indexed in the variable "grid" and add them to the cells from position (2,0) of the same DS grid .

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - - \ No newline at end of file +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_add_region.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_add_region.htm index 1a69b76c3..b894bdd7f 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_add_region.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_add_region.htm @@ -1,82 +1,84 @@ - - + - - - ds_grid_add_region - - - - - - - - - - - -

    ds_grid_add_region

    -

    This function can be used to add a given value (real or string) to all the values of the cells found within the defined area of a grid. The value to be added must be of the same type as that held within the grid cells, ie: you cannot add a string to - a real or vice-versa, and for strings this corresponds to concatenation.

    -

     

    -

    Syntax:

    -

    ds_grid_add_region(index, x1, y1, x2, y2, val);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid.
    x1The x position of the left of the region in the grid.
    y1The y position of the top of the region in the grid.
    x2The x position of the right of the region in the grid.
    y2The y position of the bottom of the region in the grid.
    valThe value to add to the region cells.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    ds_grid_add_region(grid, 2, 4, 5, 5, ".")

    -

    This would add "." to all the strings held in the cells within the defined region of the DS grid referenced by the variable "grid".

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + + ds_grid_add_region + + + + + + + + + +

    ds_grid_add_region

    +

    This function can be used to add a given value (real or string) to all the values of the cells found within the defined area of a grid. The value to be added must be of the same type as that held within the grid cells, ie: you cannot add a string to a real or vice-versa, and for strings this corresponds to concatenation.

    +

    +

    Syntax:

    +

    ds_grid_add_region(index, x1, y1, x2, y2, val);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid.
    x1The x position of the left of the region in the grid.
    y1The y position of the top of the region in the grid.
    x2The x position of the right of the region in the grid.
    y2The y position of the bottom of the region in the grid.
    valThe value to add to the region cells.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    ds_grid_add_region(grid, 2, 4, 5, 5, ".")

    +

    This would add "." to all the strings held in the cells within the defined region of the DS grid referenced by the variable "grid".

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - - \ No newline at end of file +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_clear.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_clear.htm index c9dcfda19..50000a904 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_clear.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_clear.htm @@ -1,66 +1,67 @@ - - + - - - ds_grid_clear - - - - - - - - - - - -

    ds_grid_clear

    -

    This function can be used to clear a given DS grid to a specific value. All cells within the grid will then contain this value, which can be a real number or a string. The image below illustrates how this works:

    -

    DS grid clear

    -

     

    -

    Syntax:

    -

    ds_grid_clear(index, val);

    - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThis index of the grid to clear.
    valThe new value for all grid cells.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    ds_grid_resize(global.Grid, room_width / 32, room_height / 32);
    ds_grid_clear(global.Grid, -1)

    -

    The above code will resize the DS grid indexed in the global variable "Grid" and then clear it so that each cell holds the value -1.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + + ds_grid_clear + + + + + + + + + +

    ds_grid_clear

    +

    This function can be used to clear a given DS grid to a specific value. All cells within the grid will then contain this value, which can be a real number or a string. The image below illustrates how this works:

    +

    DS grid clear

    +

    +

    Syntax:

    +

    ds_grid_clear(index, val);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThis handle of the grid to clear.
    valThe new value for all grid cells.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    ds_grid_resize(global.Grid, room_width / 32, room_height / 32); +
    + ds_grid_clear(global.Grid, -1)

    +

    The above code will resize the DS grid indexed in the global variable "Grid" and then clear it so that each cell holds the value -1.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - - \ No newline at end of file +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_copy.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_copy.htm index f28007913..c7c173f11 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_copy.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_copy.htm @@ -1,71 +1,70 @@ - + - - - ds_grid_copy - - - - - - - - - - -

    ds_grid_copy

    -

    With this function you can copy the contents of one grid into another one. Both grids must have been created previously using the ds_grid_create() function.

    -

    This will resize the destination grid to be the same size as the source grid.

    -

     

    -

    Syntax:

    -

    ds_grid_copy(destination, source);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    destinationDS GridThis index of the grid to copy to.
    sourceDS GridThis index of the grid to copy from.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    n_grid = ds_grid_create(1, 1);
    - ds_grid_copy(n_grid, a_grid);
    - ds_grid_clear(a_grid, -1)

    -

    The above code creates a new DS grid, then copies information from the previous grid to the new one. The starting size of the destination DS grid does not matter as the size of the source grid will be applied to it before any data is copied.

    -

    Finally it clears the old grid so that all cells have a value of -1.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_copy + + + + + + + + + +

    ds_grid_copy

    +

    With this function you can copy the contents of one grid into another one. Both grids must have been created previously using the ds_grid_create() function.

    +

    This will resize the destination grid to be the same size as the source grid.

    +

    +

    Syntax:

    +

    ds_grid_copy(destination, source);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    destinationDS GridThis handle of the grid to copy to.
    sourceDS GridThis handle of the grid to copy from.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    n_grid = ds_grid_create(1, 1); +
    + ds_grid_copy(n_grid, a_grid); +
    + ds_grid_clear(a_grid, -1)

    +

    The above code creates a new DS grid, then copies information from the previous grid to the new one. The starting size of the destination DS grid does not matter as the size of the source grid will be applied to it before any data is copied.

    +

    Finally it clears the old grid so that all cells have a value of -1.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_destroy.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_destroy.htm index 4f0723953..8ea536e58 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_destroy.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_destroy.htm @@ -1,67 +1,69 @@ - + - - - ds_grid_destroy - - - - - - - - - - -

    ds_grid_destroy

    -

    This function will remove the given grid data structure from memory, freeing up the resources it was using and removing all values that it contained. This function should always be used when you are finished using the DS grid to prevent memory leaks that can slow down and crash your game.

    -
    -

     

    -

    Syntax:

    -

    ds_grid_destroy(index);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexDS GridThis index of the grid to destroy.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    if (lives == 0)
    - {
    -     ds_grid_destroy(Wall_Grid);
    -     Wall_Grid = -1;
    -     room_goto(rm_Menu);
    - }

    -

    The above code will check the value of the built in global variable lives and if it is 0, it destroys the DS grid referenced in the variable Wall_Grid and then changes rooms.

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_destroy + + + + + + + + + +

    ds_grid_destroy

    +

    This function will remove the given grid data structure from memory, freeing up the resources it was using and removing all values that it contained. This function should always be used when you are finished using the DS grid to prevent memory leaks that can slow down and crash your game.

    +
    +

    +

    Syntax:

    +

    ds_grid_destroy(index);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexDS GridThis handle of the grid to destroy.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    if (lives == 0) +
    + { +
    + ds_grid_destroy(Wall_Grid); +
    + Wall_Grid = -1; +
    + room_goto(rm_Menu); +
    + }

    +

    The above code will check the value of the built in global variable lives and if it is 0, it destroys the DS grid referenced in the variable Wall_Grid and then changes rooms.

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get.htm index 7bfb9829d..aaf1c99c7 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get.htm @@ -1,71 +1,74 @@ - + - - - ds_grid_get - - - - - - - - - - - -

    ds_grid_get

    -

    This function can be used to get the value from any cell within the given DS grid. If you pass invalid grid coordinates to the function, then the value returned will be undefined and an error will be shown in the output window.

    -

     

    -

    Syntax:

    -

    ds_grid_get(index, x, y);

    - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid.
    xThe x position of the cell you want to find the value of.
    yThe y position of the cell you want to find the value of.
    -

     

    -

    Returns:

    -

    Variable

    -

     

    -

    Example:

    -

    var xx = irandom(ds_grid_width(grid) - 1);
    - var yy = irandom(ds_grid_height(grid) - 1);
    - val = ds_grid_get(grid, xx, yy)

    -

    The above code selects a random cell from the DS grid indexed in the variable "grid" and stores its value in the variable "val".

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_get + + + + + + + + + + +

    ds_grid_get

    +

    This function can be used to get the value from any cell within the given DS grid. If you pass invalid grid coordinates to the function, then the value returned will be undefined and an error will be shown in the output window.

    +

    +

    Syntax:

    +

    ds_grid_get(index, x, y);

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid.
    xThe x position of the cell you want to find the value of.
    yThe y position of the cell you want to find the value of.
    +

    +

    Returns:

    +

    Variable

    +

    +

    Example:

    +

    var xx = irandom(ds_grid_width(grid) - 1); +
    + var yy = irandom(ds_grid_height(grid) - 1); +
    + val = ds_grid_get(grid, xx, yy)

    +

    The above code selects a random cell from the DS grid indexed in the variable "grid" and stores its value in the variable "val".

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_disk_max.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_disk_max.htm index f31c54d96..b7db49596 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_disk_max.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_disk_max.htm @@ -1,73 +1,75 @@ - + - - - ds_grid_get_disk_max - - - - - - - - - - - -

    ds_grid_get_disk_max

    -

    This function can be used to find the maximum value for all the cells found within the defined disk area of a grid, as shown in the image below:

    -

    DS grid get disk max

    -

    Syntax:

    -

    ds_grid_get_disk_max(index, xm, ym, r);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid.
    xmThe x position of the disk center in the grid.
    ymThe y position of the disk center in the grid.
    rThe radius of the disk in the grid.
    -

     

    -

    Returns:

    -

    Real or String

    -

     

    -

    Example:

    -

    val = ds_grid_get_disk_max(grid, 5, 5, 2)

    -

    The above code will set the variable "val" to the maximum value contained within the given disk of the DS grid indexed in the variable "grid".

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_get_disk_max + + + + + + + + + + +

    ds_grid_get_disk_max

    +

    This function can be used to find the maximum value for all the cells found within the defined disk area of a grid, as shown in the image below:

    +

    DS grid get disk max

    +

    Syntax:

    +

    ds_grid_get_disk_max(index, xm, ym, r);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid.
    xmThe x position of the disk center in the grid.
    ymThe y position of the disk center in the grid.
    rThe radius of the disk in the grid.
    +

    +

    Returns:

    +

    Real or String

    +

    +

    Example:

    +

    val = ds_grid_get_disk_max(grid, 5, 5, 2)

    +

    The above code will set the variable "val" to the maximum value contained within the given disk of the DS grid indexed in the variable "grid".

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_disk_mean.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_disk_mean.htm index 5ff5156b4..0ed48804f 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_disk_mean.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_disk_mean.htm @@ -1,74 +1,76 @@ - + - - - ds_grid_get_disk_mean - - - - - - - - - - - -

    ds_grid_get_disk_mean

    -

    This function can be used to find the mean value for all the cells found within the defined disk area of a grid (all cell values are added together and then divided by the total number of cells that make up the disk), as shown in the image below:

    -

    DS grid get disk mean

    -

     

    -

    Syntax:

    -

    ds_grid_get_disk_mean(index, xm, ym, r);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid.
    xmThe x position of the disk on the grid.
    ymThe y position of the disk on the grid.
    rThe radius of the disk on the grid.
    -

     

    -

    Returns:

    -

    Real or String

    -

     

    -

    Example:

    -

    val = ds_grid_get_disk_mean(grid, 5, 5, 2)

    -

    The above code will set the variable "val" to the mean value contained within the given disk of the DS grid indexed in the variable "grid".

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_get_disk_mean + + + + + + + + + + +

    ds_grid_get_disk_mean

    +

    This function can be used to find the mean value for all the cells found within the defined disk area of a grid (all cell values are added together and then divided by the total number of cells that make up the disk), as shown in the image below:

    +

    DS grid get disk mean

    +

    +

    Syntax:

    +

    ds_grid_get_disk_mean(index, xm, ym, r);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid.
    xmThe x position of the disk on the grid.
    ymThe y position of the disk on the grid.
    rThe radius of the disk on the grid.
    +

    +

    Returns:

    +

    Real or String

    +

    +

    Example:

    +

    val = ds_grid_get_disk_mean(grid, 5, 5, 2)

    +

    The above code will set the variable "val" to the mean value contained within the given disk of the DS grid indexed in the variable "grid".

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_disk_min.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_disk_min.htm index 956b97e15..19ad4ea3e 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_disk_min.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_disk_min.htm @@ -1,73 +1,75 @@ - + - - - ds_grid_get_disk_min - - - - - - - - - - - -

    ds_grid_get_disk_min

    -

    This function can be used to find the minimum value for all the cells found within the defined disk area of a grid, as shown in the image below:

    -

    Ds grid get disk min

    -

    Syntax:

    -

    ds_grid_get_disk_min(index, xm, ym, r);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid.
    xmThe x position of the disk on the grid.
    ymThe y position of the disk on the grid.
    rThe radius of the disk on the grid.
    -

     

    -

    Returns:

    -

    Real or String

    -

     

    -

    Example:

    -

    val = ds_grid_get_disk_min(grid, 5, 5, 2)

    -

    The above code will set the variable "val" to the minimum value contained within the given disk of the DS grid indexed in the variable "grid".

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_get_disk_min + + + + + + + + + + +

    ds_grid_get_disk_min

    +

    This function can be used to find the minimum value for all the cells found within the defined disk area of a grid, as shown in the image below:

    +

    Ds grid get disk min

    +

    Syntax:

    +

    ds_grid_get_disk_min(index, xm, ym, r);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid.
    xmThe x position of the disk on the grid.
    ymThe y position of the disk on the grid.
    rThe radius of the disk on the grid.
    +

    +

    Returns:

    +

    Real or String

    +

    +

    Example:

    +

    val = ds_grid_get_disk_min(grid, 5, 5, 2)

    +

    The above code will set the variable "val" to the minimum value contained within the given disk of the DS grid indexed in the variable "grid".

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_disk_sum.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_disk_sum.htm index efcd89687..be6748d84 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_disk_sum.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_disk_sum.htm @@ -1,74 +1,76 @@ - + - - - ds_grid_get_disk_sum - - - - - - - - - - - -

    ds_grid_get_disk_sum

    -

    This function can be used to add all the values all the cells found within the defined disk area of a grid together, as shown in the image below:

    -

    DS grid get disk sum

    -

     

    -

    Syntax:

    -

    ds_grid_get_disk_sum(index, xm, ym, r);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid.
    xmThe x position of the disk on the grid.
    ymThe y position of the disk on the grid.
    rThe radius of the disk on the grid.
    -

     

    -

    Returns:

    -

    Real or String

    -

     

    -

    Example:

    -

    val = ds_grid_get_disk_sum(grid, 5, 5, 2)

    -

    The above code will set the variable "val" to the sum of all values contained within the given disk of the DS grid indexed in the variable "grid".

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_get_disk_sum + + + + + + + + + + +

    ds_grid_get_disk_sum

    +

    This function can be used to add all the values all the cells found within the defined disk area of a grid together, as shown in the image below:

    +

    DS grid get disk sum

    +

    +

    Syntax:

    +

    ds_grid_get_disk_sum(index, xm, ym, r);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid.
    xmThe x position of the disk on the grid.
    ymThe y position of the disk on the grid.
    rThe radius of the disk on the grid.
    +

    +

    Returns:

    +

    Real or String

    +

    +

    Example:

    +

    val = ds_grid_get_disk_sum(grid, 5, 5, 2)

    +

    The above code will set the variable "val" to the sum of all values contained within the given disk of the DS grid indexed in the variable "grid".

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_max.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_max.htm index 7ccaaafec..cdc7e594d 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_max.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_max.htm @@ -1,77 +1,80 @@ - + - - - ds_grid_get_max - - - - - - - - - - - -

    ds_grid_get_max

    -

    This function can be used to find the maximum value for all the cells found within the defined region of a grid, as shown in the image below:

    -

    DS grid get max

    -

    Syntax:

    -

    ds_grid_get_max(index, x1, y1, x2, y2);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid.
    x1The left cell column of the region.
    y1The top cell row of the region.
    x2The right cell column of the region.
    y2The bottom cell row of the region.
    -

     

    -

    Returns:

    -

    Real or String

    -

     

    -

    Example:

    -

    val = ds_grid_get_max(grid, 0, 0, 5, 5)

    -

    The above code will set the variable "val" to the maximum value contained within the given region of the DS grid indexed in the variable "grid".

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_get_max + + + + + + + + + + +

    ds_grid_get_max

    +

    This function can be used to find the maximum value for all the cells found within the defined region of a grid, as shown in the image below:

    +

    DS grid get max

    +

    Syntax:

    +

    ds_grid_get_max(index, x1, y1, x2, y2);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid.
    x1The left cell column of the region.
    y1The top cell row of the region.
    x2The right cell column of the region.
    y2The bottom cell row of the region.
    +

    +

    Returns:

    +

    Real or String

    +

    +

    Example:

    +

    val = ds_grid_get_max(grid, 0, 0, 5, 5)

    +

    The above code will set the variable "val" to the maximum value contained within the given region of the DS grid indexed in the variable "grid".

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_mean.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_mean.htm index 7452c1c90..61d6eff61 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_mean.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_mean.htm @@ -1,78 +1,81 @@ - + - - - ds_grid_get_mean - - - - - - - - - - - -

    ds_grid_get_mean

    -

    This function can be used to find the mean value for all the cells found within the defined region of a grid (all cell values are added together and then divided by the total number of cells that make the region), as shown in the image below:

    -

    DS grid get mean

    -

     

    -

    Syntax:

    -

    ds_grid_get_mean(index, x1, y1, x2, y2);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid.
    x1The left cell column of the region.
    y1The top cell row of the region.
    x2The right cell column of the region.
    y2The bottom cell row of the region.
    -

     

    -

    Returns:

    -

    Real or String

    -

     

    -

    Example:

    -

    val = ds_grid_get_mean(grid, 0, 0, 5, 5)

    -

    The above code will set the variable "val" to the mean value contained within the given region of the DS grid indexed in the variable "grid".

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_get_mean + + + + + + + + + + +

    ds_grid_get_mean

    +

    This function can be used to find the mean value for all the cells found within the defined region of a grid (all cell values are added together and then divided by the total number of cells that make the region), as shown in the image below:

    +

    DS grid get mean

    +

    +

    Syntax:

    +

    ds_grid_get_mean(index, x1, y1, x2, y2);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid.
    x1The left cell column of the region.
    y1The top cell row of the region.
    x2The right cell column of the region.
    y2The bottom cell row of the region.
    +

    +

    Returns:

    +

    Real or String

    +

    +

    Example:

    +

    val = ds_grid_get_mean(grid, 0, 0, 5, 5)

    +

    The above code will set the variable "val" to the mean value contained within the given region of the DS grid indexed in the variable "grid".

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_min.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_min.htm index 3c10a20c5..ddb069d94 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_min.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_min.htm @@ -1,78 +1,81 @@ - + - - - ds_grid_get_min - - - - - - - - - - - -

    ds_grid_get_min

    -

    This function can be used to find the minimum value for all the cells found within the defined region of a grid, as shown in the image below:

    -

    Ds grid get min

    -

     

    -

    Syntax:

    -

    ds_grid_get_min(index, x1, y1, x2, y2);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid.
    x1The left cell column of the region.
    y1The top cell row of the region.
    x2The right cell column of the region.
    y2The bottom cell row of the region.
    -

     

    -

    Returns:

    -

    Real or String

    -

     

    -

    Example:

    -

    val = ds_grid_get_min(grid, 0, 0, 5, 5)

    -

    The above code will set the variable "val" to the minimum value contained within the given region of the DS grid indexed in the variable "grid".

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_get_min + + + + + + + + + + +

    ds_grid_get_min

    +

    This function can be used to find the minimum value for all the cells found within the defined region of a grid, as shown in the image below:

    +

    Ds grid get min

    +

    +

    Syntax:

    +

    ds_grid_get_min(index, x1, y1, x2, y2);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid.
    x1The left cell column of the region.
    y1The top cell row of the region.
    x2The right cell column of the region.
    y2The bottom cell row of the region.
    +

    +

    Returns:

    +

    Real or String

    +

    +

    Example:

    +

    val = ds_grid_get_min(grid, 0, 0, 5, 5)

    +

    The above code will set the variable "val" to the minimum value contained within the given region of the DS grid indexed in the variable "grid".

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_sum.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_sum.htm index 808bd556b..6a11817fc 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_sum.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_get_sum.htm @@ -1,78 +1,81 @@ - + - - - ds_grid_get_sum - - - - - - - - - - - -

    ds_grid_get_sum

    -

    This function can be used to add all the values all the cells found within the defined region of a grid together, as shown in the image below:

    -

    DS grid get sum

    -

     

    -

    Syntax:

    -

    ds_grid_get_sum(index, x1, y1, x2, y2);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid.
    x1The left cell column of the region.
    y1The top cell row of the region.
    x2The right cell column of the region.
    y2The bottom cell row of the region.
    -

     

    -

    Returns:

    -

    Real or String

    -

     

    -

    Example:

    -

    val = ds_grid_get_sum(grid, 0, 0, 5, 5)

    -

    The above code will set the variable "val" to the sum of all values contained within the given region of the DS grid indexed in the variable "grid".

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_get_sum + + + + + + + + + + +

    ds_grid_get_sum

    +

    This function can be used to add all the values all the cells found within the defined region of a grid together, as shown in the image below:

    +

    DS grid get sum

    +

    +

    Syntax:

    +

    ds_grid_get_sum(index, x1, y1, x2, y2);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid.
    x1The left cell column of the region.
    y1The top cell row of the region.
    x2The right cell column of the region.
    y2The bottom cell row of the region.
    +

    +

    Returns:

    +

    Real or String

    +

    +

    Example:

    +

    val = ds_grid_get_sum(grid, 0, 0, 5, 5)

    +

    The above code will set the variable "val" to the sum of all values contained within the given region of the DS grid indexed in the variable "grid".

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_height.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_height.htm index be9895d34..37feb0265 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_height.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_height.htm @@ -1,71 +1,79 @@ - + - - - ds_grid_height - - - - - - - - - - - -

    ds_grid_height

    -

    This function will return the height of the given grid. This value is the number of cells the grid has along the y-axis and is always an integer, as shown in the image below:

    -

    DS grid height

    -

     

    -

    Syntax:

    -

    ds_grid_height(index);

    - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThis index of the grid to find the height of.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    for (var i = 0; i < ds_grid_width(grid); ++i)
    - {
    -     for (var j = 0; j < ds_grid_height(grid); ++j)
    -     {
    -         if (ds_grid_get(grid, i, j) == 1)
    -         {
    -             instance_create_Layer(i * 32, j * 32, "Walls", obj_Wall);
    -         }
    -     }
    - }

    -

    The above code will loop through the DS grid indexed in the variable "grid" and if the value found in any specific cell is equal to 1, it will then create an instance of "obj_Wall" at the appropriate position within the room.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_height + + + + + + + + + + +

    ds_grid_height

    +

    This function will return the height of the given grid. This value is the number of cells the grid has along the y-axis and is always an integer, as shown in the image below:

    +

    DS grid height

    +

    +

    Syntax:

    +

    ds_grid_height(index);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThis handle of the grid to find the height of.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    for (var i = 0; i < ds_grid_width(grid); ++i) +
    + { +
    + for (var j = 0; j < ds_grid_height(grid); ++j) +
    + { +
    + if (ds_grid_get(grid, i, j) == 1) +
    + { +
    + instance_create_Layer(i * 32, j * 32, "Walls", obj_Wall); +
    + } +
    + } +
    + }

    +

    The above code will loop through the DS grid indexed in the variable "grid" and if the value found in any specific cell is equal to 1, it will then create an instance of "obj_Wall" at the appropriate position within the room.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_multiply.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_multiply.htm index 7e5ed896f..fa9b17f13 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_multiply.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_multiply.htm @@ -1,78 +1,75 @@ - + - - - ds_grid_multiply - - - - - - - - - - -

    ds_grid_multiply

    -

    This function will multiply the value of the given grid cell by the specified amount.

    -

    NOTE This function will only work with real numbers, not strings.

    -

     

    -

    Syntax:

    -

    ds_grid_multiply(index, x, y, val);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexDS Grid IDThe index of the grid.
    xRealThe x position of the cell in the grid.
    yRealThe y position of the cell in the grid.
    valRealThe value to multiply with the cell.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    ds_grid_multiply(mygrid, 5, 5, 2)

    -

    The above code will multiply the value stored in the given DS grid cell by 2.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_multiply + + + + + + + + + +

    ds_grid_multiply

    +

    This function will multiply the value of the given grid cell by the specified amount.

    +

    NOTE This function will only work with real numbers, not strings.

    +

    +

    Syntax:

    +

    ds_grid_multiply(index, x, y, val);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexDS Grid IDThe handle of the grid.
    xRealThe x position of the cell in the grid.
    yRealThe y position of the cell in the grid.
    valRealThe value to multiply with the cell.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    ds_grid_multiply(mygrid, 5, 5, 2)

    +

    The above code will multiply the value stored in the given DS grid cell by 2.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_multiply_disk.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_multiply_disk.htm index b85fb938a..2400868c4 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_multiply_disk.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_multiply_disk.htm @@ -1,83 +1,80 @@ - + - - - ds_grid_multiply_disk - - - - - - - - - - -

    ds_grid_multiply_disk

    -

    This function will take all the values in a given disc-shaped region of the DS grid, and multiply each one by the given amount.

    -

    NOTE This function will only work with real numbers, not strings.

    -

     

    -

    Syntax:

    -

    ds_grid_multiply_disk(index, xm, ym, r, val);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexDS Grid IDThe index of the grid.
    xmRealThe x position of the disk on the grid.
    ymRealThe y position of the disk on the grid.
    rRealThe radius of the disk on the grid.
    valRealThe value to multiply the cells within the disk with.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    ds_grid_multiply_disk(mygrid, 5, 5, 5, 2)

    -

    The above code will take all the values found within the circular grid area and multiply each one by 2.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_multiply_disk + + + + + + + + + +

    ds_grid_multiply_disk

    +

    This function will take all the values in a given disc-shaped region of the DS grid, and multiply each one by the given amount.

    +

    NOTE This function will only work with real numbers, not strings.

    +

    +

    Syntax:

    +

    ds_grid_multiply_disk(index, xm, ym, r, val);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexDS Grid IDThe handle of the grid.
    xmRealThe x position of the disk on the grid.
    ymRealThe y position of the disk on the grid.
    rRealThe radius of the disk on the grid.
    valRealThe value to multiply the cells within the disk with.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    ds_grid_multiply_disk(mygrid, 5, 5, 5, 2)

    +

    The above code will take all the values found within the circular grid area and multiply each one by 2.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_multiply_grid_region.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_multiply_grid_region.htm index 01ee4adad..39775c633 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_multiply_grid_region.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_multiply_grid_region.htm @@ -1,90 +1,94 @@ - - + - - - ds_grid_multiply_grid_region - - - - - - - - - - - -

    ds_grid_multiply_grid_region

    -

    With this function you can define an area within a given DS grid, then take those values and multiply them with those found in a separate region of either the same DS grid, or another one (which has been previously created). The original region will - remain unchanged, while the region that they have been multiplied with will now store the new values for each cell.

    -

     

    -

    Syntax:

    -

    ds_grid_multiply_grid_region(index, source, x1, y1, x2, y2, xpos, ypos);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the destination grid.
    sourceThe index of the source grid.
    x1The left position of the region of cells to copy from the source grid.
    y1The top position of the region of cells to copy from the source grid.
    x2The right position of the region of cells to copy from the source grid.
    y2The bottom position of the region of cells to copy from the source grid.
    xposThe x position on the destination grid to multiply the source region with.
    yposThe y position on the destination grid to multiply the source region with.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    ds_grid_multiply_grid_region(mygrid, mygrid, 0, 0, 5, 5, 0, 0)

    -

    This would take the region of cells from (0,0) to (5,5) of the DS grid "mygrid" and multiply them with the cells from position (0,0) of the same DS grid.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + + ds_grid_multiply_grid_region + + + + + + + + + +

    ds_grid_multiply_grid_region

    +

    With this function you can define an area within a given DS grid, then take those values and multiply them with those found in a separate region of either the same DS grid, or another one (which has been previously created). The original region will remain unchanged, while the region that they have been multiplied with will now store the new values for each cell.

    +

    +

    Syntax:

    +

    ds_grid_multiply_grid_region(index, source, x1, y1, x2, y2, xpos, ypos);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the destination grid.
    sourceThe handle of the source grid.
    x1The left position of the region of cells to copy from the source grid.
    y1The top position of the region of cells to copy from the source grid.
    x2The right position of the region of cells to copy from the source grid.
    y2The bottom position of the region of cells to copy from the source grid.
    xposThe x position on the destination grid to multiply the source region with.
    yposThe y position on the destination grid to multiply the source region with.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    ds_grid_multiply_grid_region(mygrid, mygrid, 0, 0, 5, 5, 0, 0)

    +

    This would take the region of cells from (0,0) to (5,5) of the DS grid "mygrid" and multiply them with the cells from position (0,0) of the same DS grid.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - - \ No newline at end of file +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_multiply_region.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_multiply_region.htm index e504f58bf..c2a056503 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_multiply_region.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_multiply_region.htm @@ -1,88 +1,85 @@ - + - - - ds_grid_multiply_region - - - - - - - - - - -

    ds_grid_multiply_region

    -

    With this function you can specify a region of the grid in which to multiply each cell value by a given amount.

    -

    NOTE This function will only work with real numbers, not strings.

    -

     

    -

    Syntax:

    -

    ds_grid_multiply_region(index, x1, y1, x2, y2, val);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexDS Grid IDThe index of the grid.
    x1RealThe x position of the left of the region in the grid.
    y1RealThe y position of the top of the region in the grid.
    x2RealThe x position of the right of the region in the grid.
    y2RealThe y position of the bottom of the region in the grid.
    valRealThe value to multiply with the region cells.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    ds_grid_multiply_region(mygrid, 5, 5, 10, 10, 2);

    -

    The above code will take all the values found within the defined rectangular grid area and multiply each one by 2.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_multiply_region + + + + + + + + + +

    ds_grid_multiply_region

    +

    With this function you can specify a region of the grid in which to multiply each cell value by a given amount.

    +

    NOTE This function will only work with real numbers, not strings.

    +

    +

    Syntax:

    +

    ds_grid_multiply_region(index, x1, y1, x2, y2, val);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexDS Grid IDThe handle of the grid.
    x1RealThe x position of the left of the region in the grid.
    y1RealThe y position of the top of the region in the grid.
    x2RealThe x position of the right of the region in the grid.
    y2RealThe y position of the bottom of the region in the grid.
    valRealThe value to multiply with the region cells.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    ds_grid_multiply_region(mygrid, 5, 5, 10, 10, 2);

    +

    The above code will take all the values found within the defined rectangular grid area and multiply each one by 2.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_read.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_read.htm index 51d458ac3..3e4d89fad 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_read.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_read.htm @@ -1,76 +1,76 @@ - + - - - ds_grid_read - - - - - - - - - - -

    ds_grid_read

    -

    This function can be used to convert a string which has been created previously by the function ds_grid_write() back into a DS grid. The DS grid must have been created previously (see the example below).

    -

    Note that if the specified DS string was written by the GameMaker: Studio 1.2.x runtime (or older), you should specify the optional argument "legacy", setting it to true as the string format changed after that.

    -

     

    -

    Syntax:

    -

    ds_grid_read(index, string [, legacy]);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexDS Grid IDThe index of the grid to read.
    stringStringThe string to read into the DS grid.
    legacyBooleanOPTIONAL Can be either true or false or omitted completely.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    grid = ds_grid_create(room_width div 32, room_height div 32);
    - ini_open("Save.ini");
    - ds_grid_read(grid, ini_read_string("Save", "0", ""));
    - ini_close();

    -

    The above code creates a DS grid based on the size of the room (each 32x32 square of pixels represents one grid cell) and then reads a previously saved set of grid data from an ini file into the new DS grid.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_read + + + + + + + + + +

    ds_grid_read

    +

    This function can be used to convert a string which has been created previously by the function ds_grid_write() back into a DS grid. The DS grid must have been created previously (see the example below).

    +

    Note that if the specified DS string was written by the GameMaker: Studio 1.2.x runtime (or older), you should specify the optional argument "legacy", setting it to true as the string format changed after that.

    +

    +

    Syntax:

    +

    ds_grid_read(index, string [, legacy]);

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexDS Grid IDThe handle of the grid to read.
    stringStringThe string to read into the DS grid.
    legacyBooleanOPTIONAL Can be either true or false or omitted completely.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    grid = ds_grid_create(room_width div 32, room_height div 32); +
    + ini_open("Save.ini"); +
    + ds_grid_read(grid, ini_read_string("Save", "0", "")); +
    + ini_close();

    +

    The above code creates a DS grid based on the size of the room (each 32x32 square of pixels represents one grid cell) and then reads a previously saved set of grid data from an ini file into the new DS grid.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_resize.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_resize.htm index f557df5f8..3b0015972 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_resize.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_resize.htm @@ -1,70 +1,71 @@ - - + - - - ds_grid_resize - - - - - - - - - - - -

    ds_grid_resize

    -

    With this function you can resize the given DS grid to have a different width and/or height. If the grid size is larger than the current grid, the new cells will have a base value of 0, and if the size is smaller then the values held in the cells that - are no longer within the new size will be lost. All other cells will be left untouched.

    -

     

    -

    Syntax:

    -

    ds_grid_resize(index, w, h);

    - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThis index of the grid to resize.
    wThe new width of the grid.
    hThe new height of the grid.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    ds_grid_resize(global.Grid, room_width / 32, room_height / 32);
    ds_grid_clear(global.Grid, -1)

    -

    The above code will resize the DS grid indexed in the global variable "Grid" and then clear it so that each cell holds the value -1.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + + ds_grid_resize + + + + + + + + + +

    ds_grid_resize

    +

    With this function you can resize the given DS grid to have a different width and/or height. If the grid size is larger than the current grid, the new cells will have a base value of 0, and if the size is smaller then the values held in the cells that are no longer within the new size will be lost. All other cells will be left untouched.

    +

    +

    Syntax:

    +

    ds_grid_resize(index, w, h);

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThis handle of the grid to resize.
    wThe new width of the grid.
    hThe new height of the grid.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    ds_grid_resize(global.Grid, room_width / 32, room_height / 32); +
    + ds_grid_clear(global.Grid, -1)

    +

    The above code will resize the DS grid indexed in the global variable "Grid" and then clear it so that each cell holds the value -1.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - - \ No newline at end of file +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_set.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_set.htm index fc6ef98a3..1990611a1 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_set.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_set.htm @@ -1,87 +1,100 @@ - + - - - ds_grid_set - - - - - - - - - - -

    ds_grid_set

    -

    This function can be used to set a given cell within the given DS grid to any value, which can be a real number or a string. The image below illustrates this:

    -

    DS grid set

    -

    Syntax:

    -

    ds_grid_set(index, x, y, value);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThis index of the grid.
    xThe x position of the cell to set.
    yThe y position of the cell to set.
    valueThe value with which to set the cell.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    grid = ds_grid_create(5, 5);
    - var i = 0;
    - var j = 0;
    -
    - repeat (ds_grid_width(grid))
    - {
    -     repeat (ds_grid_height(grid))
    -     {
    -         ds_grid_set(grid, i, j, irandom(9));
    -         j += 1;
    -     }
    -
    -     j = 0;
    -     i += 1;
    - } -

    -

    The above code creates a grid and stores its index in the variable "grid". It then populates this grid with random integers from 0 to 9.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_set + + + + + + + + + +

    ds_grid_set

    +

    This function can be used to set a given cell within the given DS grid to any value, which can be a real number or a string. The image below illustrates this:

    +

    DS grid set

    +

    Syntax:

    +

    ds_grid_set(index, x, y, value);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThis handle of the grid.
    xThe x position of the cell to set.
    yThe y position of the cell to set.
    valueThe value with which to set the cell.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    grid = ds_grid_create(5, 5); +
    + var i = 0; +
    + var j = 0; +
    +
    + repeat (ds_grid_width(grid)) +
    + { +
    + repeat (ds_grid_height(grid)) +
    + { +
    + ds_grid_set(grid, i, j, irandom(9)); +
    + j += 1; +
    + } +
    +
    + j = 0; +
    + i += 1; +
    + }

    +

    The above code creates a grid and stores its index in the variable "grid". It then populates this grid with random integers from 0 to 9.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_set_disk.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_set_disk.htm index 64d123dc1..58eb40886 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_set_disk.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_set_disk.htm @@ -1,79 +1,80 @@ - - + - - - ds_grid_set_disk - - - - - - - - - - - -

    ds_grid_set_disk

    -

    With this function you can set a circular region of a grid to a certain value. You need to supply a starting grid cell (as an x and y axis coordinate) as well as the radius of the disk to set and the value that you wish to set the disk too, as shown - by the illustration below:

    -

    DS grid set disk

    -

     

    -

    Syntax:

    -

    ds_grid_set_disk(index, xm, ym, r, val);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid.
    xmThe x position of the disk on the grid.
    ymThe y position of the disk on the grid.
    rThe radius of the disk on the grid.
    valThe value to set with the cells within the disk.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    ds_grid_set_disk(grid, ds_grid_width(grid) div 2, ds_grid_height(grid) div 2, 5, -4)

    -

    The above code will set a circular region with a radius of 5 cells in the DS grid indexed in the variable "grid" to a value of -4.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + + ds_grid_set_disk + + + + + + + + + +

    ds_grid_set_disk

    +

    With this function you can set a circular region of a grid to a certain value. You need to supply a starting grid cell (as an x and y axis coordinate) as well as the radius of the disk to set and the value that you wish to set the disk too, as shown by the illustration below:

    +

    DS grid set disk

    +

    +

    Syntax:

    +

    ds_grid_set_disk(index, xm, ym, r, val);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid.
    xmThe x position of the disk on the grid.
    ymThe y position of the disk on the grid.
    rThe radius of the disk on the grid.
    valThe value to set with the cells within the disk.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    ds_grid_set_disk(grid, ds_grid_width(grid) div 2, ds_grid_height(grid) div 2, 5, -4)

    +

    The above code will set a circular region with a radius of 5 cells in the DS grid indexed in the variable "grid" to a value of -4.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - - \ No newline at end of file +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_set_grid_region.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_set_grid_region.htm index 7d18ef344..27522a971 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_set_grid_region.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_set_grid_region.htm @@ -1,91 +1,95 @@ - - + - - - ds_grid_set_grid_region - - - - - - - - - - - -

    ds_grid_set_grid_region

    -

    This function can be used to copy the contents of a rectangular area of grid cells from one (previously defined) DS grid to another, or it can be used to copy a region from within the same grid. The following images illustrate both ways that - this function can be used:

    -

    DS grid set grid region

    -

     

    -

    Syntax:

    -

    ds_grid_set_grid_region(index, source, x1, y1, x2, y2, xpos, ypos);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the destination grid.
    sourceThe index of the source grid.
    x1The left position of the region of cells to copy from the source grid.
    y1The top position of the region of cells to copy from the source grid.
    x2The right position of the region of cells to copy from the source grid.
    y2The bottom position of the region of cells to copy from the source grid.
    xposThe x position on the destination grid to copy the source region to.
    yposThe y position on the destination grid to copy the source region to.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    ds_grid_set_grid_region(grid, t_grid, 0, 0, 5, 5, 10, 10)

    -

    This would copy the region of cells from (0,0) to (5,5) of the grid indexed in the variable "t_grid" and copy them to position (10,10) in the grid indexed in the variable "grid".

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + + ds_grid_set_grid_region + + + + + + + + + +

    ds_grid_set_grid_region

    +

    This function can be used to copy the contents of a rectangular area of grid cells from one (previously defined) DS grid to another, or it can be used to copy a region from within the same grid. The following images illustrate both ways that this function can be used:

    +

    DS grid set grid region

    +

    +

    Syntax:

    +

    ds_grid_set_grid_region(index, source, x1, y1, x2, y2, xpos, ypos);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the destination grid.
    sourceThe handle of the source grid.
    x1The left position of the region of cells to copy from the source grid.
    y1The top position of the region of cells to copy from the source grid.
    x2The right position of the region of cells to copy from the source grid.
    y2The bottom position of the region of cells to copy from the source grid.
    xposThe x position on the destination grid to copy the source region to.
    yposThe y position on the destination grid to copy the source region to.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    ds_grid_set_grid_region(grid, t_grid, 0, 0, 5, 5, 10, 10)

    +

    This would copy the region of cells from (0,0) to (5,5) of the grid indexed in the variable "t_grid" and copy them to position (10,10) in the grid indexed in the variable "grid".

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - - \ No newline at end of file +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_set_region.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_set_region.htm index a761500df..6dde1cde1 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_set_region.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_set_region.htm @@ -1,82 +1,85 @@ - - + - - - ds_grid_set_region - - - - - - - - - - - -

    ds_grid_set_region

    -

    This function can be used to set a rectangular region of a given grid to a specified value (which can be either a real or a string) as illustrated by the image shown below:

    -

    DS grid set region

    -

     

    -

    Syntax:

    -

    ds_grid_set_region(index, x1, y1, x2, y2, val);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid.
    x1The x position of the left of the region in the grid.
    y1The y position of the top of the region in the grid.
    x2The x position of the right of the region in the grid.
    y2The y position of the bottom of the region in the grid.
    valThe value to set the region cells to.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    ds_grid_set_region(grid, 5, 5, 10, 10, 99)

    -

    This would set all cells within the region of the grid indexed in the variable "grid" from (5,5) to (10,10) to 99.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + + ds_grid_set_region + + + + + + + + + +

    ds_grid_set_region

    +

    This function can be used to set a rectangular region of a given grid to a specified value (which can be either a real or a string) as illustrated by the image shown below:

    +

    DS grid set region

    +

    +

    Syntax:

    +

    ds_grid_set_region(index, x1, y1, x2, y2, val);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid.
    x1The x position of the left of the region in the grid.
    y1The y position of the top of the region in the grid.
    x2The x position of the right of the region in the grid.
    y2The y position of the bottom of the region in the grid.
    valThe value to set the region cells to.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    ds_grid_set_region(grid, 5, 5, 10, 10, 99)

    +

    This would set all cells within the region of the grid indexed in the variable "grid" from (5,5) to (10,10) to 99.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - - \ No newline at end of file +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_shuffle.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_shuffle.htm index 97947303f..46190cfea 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_shuffle.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_shuffle.htm @@ -4,7 +4,7 @@ ds_grid_shuffle - + @@ -16,27 +16,27 @@

    ds_grid_shuffle

    This function can be used to randomise the positions of all values in all cells within a grid.

    -

    NOTE This function will shuffle the grid cells to the same positions every time the game is run afresh due to the fact that GameMaker generates the same initial random seed every time to make debugging code a far easier task. To avoid - this behaviour use randomise() at the start of your game. This is only true when testing and debugging the game, as the final executable - package will not show this behaviour and will be random every play.

    +

    NOTE This function will shuffle the grid cells to the same positions every time the game is run afresh due to the fact that GameMaker generates the same initial random seed every time to make debugging code a far easier task. To avoid this behaviour use randomise() at the start of your game. This is only true when testing and debugging the game, as the final executable package will not show this behaviour and will be random every play.

     

    Syntax:

    ds_grid_shuffle(index);

    - + + - + - - - + + + +
    ArgumentTypeArgumentType Description
    indexThe index of the grid to shuffle.
    indexDS GridThe handle of the grid to shuffle.

     

    Returns:

    -

    +

    N/A

     

    Example:

    ds_grid_shuffle(grid)

    @@ -48,10 +48,10 @@

    Example:

    Back: DS Grids
    - +
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -

    ds_grid_sort

    -

    This function can be used to sort a DS grid based on the values from a given column (much as you would sort files by date, size etc... in the OS file explorer). The following image shows an example:

    -

    DS grid sort

    -

     

    -

    Syntax:

    -

    ds_grid_sort(index, column, ascending);

    - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid to sort.
    columnThe column to use for sorting the rows
    ascendingWhether to sort lowest to highest (true), or highest to lowest (false).
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    ds_grid_sort(grid, 3, false)

    -

    This would take all the values in the DS grid indexed in the variable "grid" and sort them according to the values found in the 3rd column of the grid (as shown in the above image).

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + + ds_grid_sort + + + + + + + + + + +

    ds_grid_sort

    +

    This function can be used to sort a DS grid based on the values from a given column (much as you would sort files by date, size etc... in the OS file explorer). The following image shows an example:

    +

    DS grid sort

    +

    +

    Syntax:

    +

    ds_grid_sort(index, column, ascending);

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid to sort.
    columnThe column to use for sorting the rows
    ascendingWhether to sort lowest to highest (true), or highest to lowest (false).
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    ds_grid_sort(grid, 3, false)

    +

    This would take all the values in the DS grid indexed in the variable "grid" and sort them according to the values found in the 3rd column of the grid (as shown in the above image).

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - - \ No newline at end of file +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_disk_exists.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_disk_exists.htm index b990d4fe7..6815ff0d4 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_disk_exists.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_disk_exists.htm @@ -1,81 +1,88 @@ - + - - - ds_grid_value_disk_exists - - - - - - - - - - - -

    ds_grid_value_disk_exists

    -

    With this function you can check to see if a specific value (real or string) is present within a circular area of a given DS grid. If it is present the function will return true otherwise it will return false.

    -

     

    -

    Syntax:

    -

    ds_grid_value_disk_exists(index, xm, ym, r, val);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid.
    xmThe x position of the disk on the grid.
    ymThe y position of the disk on the grid.
    rThe radius of the disk on the grid.
    valThe value to find.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    if (ds_grid_value_disk_exists(grid, 5, 5, 5, val))
    - {
    -     xpos = ds_grid_value_disk_x(grid, 5, 5, 5, val);
    -     ypos = ds_grid_value_disk_y(grid, 5, 5, 5, val);
    - }

    -

    The above code checks a DS grid for a specific value within a disk region. if it is found, it then stores the x and y position of the value in two variables for later use.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_value_disk_exists + + + + + + + + + + +

    ds_grid_value_disk_exists

    +

    With this function you can check to see if a specific value (real or string) is present within a circular area of a given DS grid. If it is present the function will return true otherwise it will return false.

    +

    +

    Syntax:

    +

    ds_grid_value_disk_exists(index, xm, ym, r, val);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid.
    xmThe x position of the disk on the grid.
    ymThe y position of the disk on the grid.
    rThe radius of the disk on the grid.
    valThe value to find.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    if (ds_grid_value_disk_exists(grid, 5, 5, 5, val)) +
    + { +
    + xpos = ds_grid_value_disk_x(grid, 5, 5, 5, val); +
    + ypos = ds_grid_value_disk_y(grid, 5, 5, 5, val); +
    + }

    +

    The above code checks a DS grid for a specific value within a disk region. if it is found, it then stores the x and y position of the value in two variables for later use.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_disk_x.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_disk_x.htm index 65af3bc11..5d058ab34 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_disk_x.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_disk_x.htm @@ -1,81 +1,88 @@ - + - - - ds_grid_value_disk_x - - - - - - - - - - - -

    ds_grid_value_disk_x

    -

    With this function you can get the x coordinate (within the given grid disc-shaped region) of the value being searched for. You give the DS grid index (as returned by ds_grid_create()) along with the x/y positions for the center cell of the disk. Then you give the radius (as an integer value) around the center cell to search, before supplying the value to search for. If the value being searched for does not exist, then the function will return -1.

    -

     

    -

    Syntax:

    -

    ds_grid_value_disk_x(index, xm, ym, r, val);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid.
    xmThe x position of the disk on the grid.
    ymThe y position of the disk on the grid.
    rThe radius of the disk on the grid.
    valThe value to find.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    if (ds_grid_value_disk_exists(grid, 5, 5, 5, val))
    - {
    -     xpos = ds_grid_value_disk_x(grid, 5, 5, 5, val);
    -     ypos = ds_grid_value_disk_y(grid, 5, 5, 5, val);
    - }

    -

    The above code checks a ds_grid for a specific value within a disk region. if it is found, it then stores the x and y position of the value in two variables for later use.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_value_disk_x + + + + + + + + + + +

    ds_grid_value_disk_x

    +

    With this function you can get the x coordinate (within the given grid disc-shaped region) of the value being searched for. You give the DS grid index (as returned by ds_grid_create()) along with the x/y positions for the center cell of the disk. Then you give the radius (as an integer value) around the center cell to search, before supplying the value to search for. If the value being searched for does not exist, then the function will return -1.

    +

    +

    Syntax:

    +

    ds_grid_value_disk_x(index, xm, ym, r, val);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid.
    xmThe x position of the disk on the grid.
    ymThe y position of the disk on the grid.
    rThe radius of the disk on the grid.
    valThe value to find.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    if (ds_grid_value_disk_exists(grid, 5, 5, 5, val)) +
    + { +
    + xpos = ds_grid_value_disk_x(grid, 5, 5, 5, val); +
    + ypos = ds_grid_value_disk_y(grid, 5, 5, 5, val); +
    + }

    +

    The above code checks a ds_grid for a specific value within a disk region. if it is found, it then stores the x and y position of the value in two variables for later use.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_disk_y.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_disk_y.htm index ae52306b1..3d8d7a10f 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_disk_y.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_disk_y.htm @@ -1,81 +1,88 @@ - + - - - ds_grid_value_disk_y - - - - - - - - - - - -

    ds_grid_value_disk_y

    -

    With this function you can get the y coordinate (within the given grid disc-shaped region) of the value being searched for. You give the DS grid index (as returned by ds_grid_create()) along with the x/y positions for the center cell of the disk. Then you give the radius (as an integer value) around the center cell to search, before supplying the value to search for. If the value being searched for does not exist, then the function will return -1.

    -

     

    -

    Syntax:

    -

    ds_grid_value_disk_y(index, xm, ym, r, val);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid.
    xmThe x position of the disk on the grid.
    ymThe y position of the disk on the grid.
    rThe radius of the disk on the grid.
    valThe value to find.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    if (ds_grid_value_disk_exists(grid, 5, 5, 5, val))
    - {
    -     xpos = ds_grid_value_disk_x(grid, 5, 5, 5, val);
    -     ypos = ds_grid_value_disk_y(grid, 5, 5, 5, val);
    - }

    -

    The above code checks a DS grid for a specific value within a disk region. if it is found, it then stores the x and y position of the value in two variables for later use.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_value_disk_y + + + + + + + + + + +

    ds_grid_value_disk_y

    +

    With this function you can get the y coordinate (within the given grid disc-shaped region) of the value being searched for. You give the DS grid index (as returned by ds_grid_create()) along with the x/y positions for the center cell of the disk. Then you give the radius (as an integer value) around the center cell to search, before supplying the value to search for. If the value being searched for does not exist, then the function will return -1.

    +

    +

    Syntax:

    +

    ds_grid_value_disk_y(index, xm, ym, r, val);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid.
    xmThe x position of the disk on the grid.
    ymThe y position of the disk on the grid.
    rThe radius of the disk on the grid.
    valThe value to find.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    if (ds_grid_value_disk_exists(grid, 5, 5, 5, val)) +
    + { +
    + xpos = ds_grid_value_disk_x(grid, 5, 5, 5, val); +
    + ypos = ds_grid_value_disk_y(grid, 5, 5, 5, val); +
    + }

    +

    The above code checks a DS grid for a specific value within a disk region. if it is found, it then stores the x and y position of the value in two variables for later use.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_exists.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_exists.htm index 3dbd1dcea..aaf644b6c 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_exists.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_exists.htm @@ -1,85 +1,93 @@ - + - - - ds_grid_value_exists - - - - - - - - - - - -

    ds_grid_value_exists

    -

    With this function you can check to see if a specific value (real or string) is present within a rectangular area of a given DS grid. If it is present the function will return true otherwise it will return false.

    -

     

    -

    Syntax:

    -

    ds_grid_value_exists(index, x1, y1, x2, y2, val);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid.
    x1The x position of the left of the region in the grid.
    y1The y position of the top of the region in the grid.
    x2The x position of the right of the region in the grid.
    y2The y position of the bottom of the region in the grid.
    valThe value to find.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    if (ds_grid_value_exists(grid, 0, 1, 5, 6, val))
    - {
    -     xpos = ds_grid_value_x(grid, 0, 1, 5, 6, val);
    -     ypos = ds_grid_value_y(grid, 0, 1, 5, 6, val);
    - }

    -

    The above code checks a DS grid for a specific value within a rectangular region. if it is found, it then stores the x and y position of the value in two variables for later use.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_value_exists + + + + + + + + + + +

    ds_grid_value_exists

    +

    With this function you can check to see if a specific value (real or string) is present within a rectangular area of a given DS grid. If it is present the function will return true otherwise it will return false.

    +

    +

    Syntax:

    +

    ds_grid_value_exists(index, x1, y1, x2, y2, val);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid.
    x1The x position of the left of the region in the grid.
    y1The y position of the top of the region in the grid.
    x2The x position of the right of the region in the grid.
    y2The y position of the bottom of the region in the grid.
    valThe value to find.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    if (ds_grid_value_exists(grid, 0, 1, 5, 6, val)) +
    + { +
    + xpos = ds_grid_value_x(grid, 0, 1, 5, 6, val); +
    + ypos = ds_grid_value_y(grid, 0, 1, 5, 6, val); +
    + }

    +

    The above code checks a DS grid for a specific value within a rectangular region. if it is found, it then stores the x and y position of the value in two variables for later use.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_x.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_x.htm index f7e8b6700..565ad788c 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_x.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_x.htm @@ -1,85 +1,93 @@ - + - - - ds_grid_value_x - - - - - - - - - - - -

    ds_grid_value_x

    -

    With this function you can get the x coordinate (within the given rectangular grid region) of the value being searched for. You give the DS grid index (as returned by ds_grid_create()) along with the x/y positions for the top left and bottom right corners of the grid region to search, before supplying the value to search for. If the value being searched for does not exist, then the function will return -1.

    -

     

    -

    Syntax:

    -

    ds_grid_value_x(index, x1, y1, x2, y2, val);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid.
    x1The x position of the left of the region in the grid, from 0 to (grid width - 1).
    y1The y position of the top of the region in the grid, from 0 to (grid height - 1).
    x2The x position of the right of the region in the grid, from 0 to (grid width - 1).
    y2The y position of the bottom of the region in the grid, from 0 to (grid height - 1).
    valThe value to find.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    if (ds_grid_value_exists(grid, 0, 1, 5, 6, val))
    - {
    -     xpos = ds_grid_value_x(grid, 0, 1, 5, 6, val);
    -     ypos = ds_grid_value_y(grid, 0, 1, 5, 6, val);
    - }

    -

    The above code checks a ds_grid for a specific value within a rectangular region. if it is found, it then stores the x and y position of the value in two variables for later use.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_value_x + + + + + + + + + + +

    ds_grid_value_x

    +

    With this function you can get the x coordinate (within the given rectangular grid region) of the value being searched for. You give the DS grid index (as returned by ds_grid_create()) along with the x/y positions for the top left and bottom right corners of the grid region to search, before supplying the value to search for. If the value being searched for does not exist, then the function will return -1.

    +

    +

    Syntax:

    +

    ds_grid_value_x(index, x1, y1, x2, y2, val);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid.
    x1The x position of the left of the region in the grid, from 0 to (grid width - 1).
    y1The y position of the top of the region in the grid, from 0 to (grid height - 1).
    x2The x position of the right of the region in the grid, from 0 to (grid width - 1).
    y2The y position of the bottom of the region in the grid, from 0 to (grid height - 1).
    valThe value to find.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    if (ds_grid_value_exists(grid, 0, 1, 5, 6, val)) +
    + { +
    + xpos = ds_grid_value_x(grid, 0, 1, 5, 6, val); +
    + ypos = ds_grid_value_y(grid, 0, 1, 5, 6, val); +
    + }

    +

    The above code checks a ds_grid for a specific value within a rectangular region. if it is found, it then stores the x and y position of the value in two variables for later use.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_y.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_y.htm index 986e8eddf..83e9f3ab7 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_y.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_value_y.htm @@ -1,85 +1,93 @@ - + - - - ds_grid_value_y - - - - - - - - - - - -

    ds_grid_value_y

    -

    With this function you can get the y coordinate (within the given rectangular grid region) of the value being searched for. You give the DS grid index (as returned by ds_grid_create()) along with the x/y positions for the top left and bottom right corners of the grid region to search, before supplying the value to search for. If the value being searched for does not exist, then the function will return -1.

    -

     

    -

    Syntax:

    -

    ds_grid_value_y(index, x1, y1, x2, y2, val);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid.
    x1The x position of the left of the region in the grid, from 0 to (grid width - 1).
    y1The y position of the top of the region in the grid, from 0 to (grid height - 1).
    x2The x position of the right of the region in the grid, from 0 to (grid width - 1).
    y2The y position of the bottom of the region in the grid, from 0 to (grid height - 1)
    valThe value to find.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    if (ds_grid_value_exists(grid, 0, 1, 5, 6, val))
    - {
    -     xpos = ds_grid_value_x(grid, 0, 1, 5, 6, val);
    -     ypos = ds_grid_value_y(grid, 0, 1, 5, 6, val);
    - }

    -

    The above code checks a ds_grid for a specific value within a rectangular region. if it is found, it then stores the x and y position of the value in two variables for later use.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_value_y + + + + + + + + + + +

    ds_grid_value_y

    +

    With this function you can get the y coordinate (within the given rectangular grid region) of the value being searched for. You give the DS grid index (as returned by ds_grid_create()) along with the x/y positions for the top left and bottom right corners of the grid region to search, before supplying the value to search for. If the value being searched for does not exist, then the function will return -1.

    +

    +

    Syntax:

    +

    ds_grid_value_y(index, x1, y1, x2, y2, val);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid.
    x1The x position of the left of the region in the grid, from 0 to (grid width - 1).
    y1The y position of the top of the region in the grid, from 0 to (grid height - 1).
    x2The x position of the right of the region in the grid, from 0 to (grid width - 1).
    y2The y position of the bottom of the region in the grid, from 0 to (grid height - 1)
    valThe value to find.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    if (ds_grid_value_exists(grid, 0, 1, 5, 6, val)) +
    + { +
    + xpos = ds_grid_value_x(grid, 0, 1, 5, 6, val); +
    + ypos = ds_grid_value_y(grid, 0, 1, 5, 6, val); +
    + }

    +

    The above code checks a ds_grid for a specific value within a rectangular region. if it is found, it then stores the x and y position of the value in two variables for later use.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_width.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_width.htm index f667614a0..f522ce46c 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_width.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_width.htm @@ -1,70 +1,78 @@ - + - - - ds_grid_width - - - - - - - - - - - -

    ds_grid_width

    -

    This function will return the width of the given grid. This value is the number of cells the grid has along the x-axis and is always an integer, as shown in the image below:

    -

    DS grid width

    -

    Syntax:

    -

    ds_grid_width(index);

    - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThis index of the grid to find the width of.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    for (var i = 0; i < ds_grid_width(grid); ++i)
    - {
    -     for (var j = 0; j < ds_grid_height(grid); ++j)
    -     {
    -         if (ds_grid_get(grid, i, j) == 1)
    -         {
    -             instance_create_layer(i * 32, j * 32, "Walls", obj_Wall);
    -         }
    -     }
    - }

    -

    The above code will loop through the DS grid indexed in the variable "grid" and if the value found in any specific cell is equal to 1, it will then create an instance of "obj_Wall" at the appropriate position within the room.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + ds_grid_width + + + + + + + + + + +

    ds_grid_width

    +

    This function will return the width of the given grid. This value is the number of cells the grid has along the x-axis and is always an integer, as shown in the image below:

    +

    DS grid width

    +

    Syntax:

    +

    ds_grid_width(index);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThis handle of the grid to find the width of.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    for (var i = 0; i < ds_grid_width(grid); ++i) +
    + { +
    + for (var j = 0; j < ds_grid_height(grid); ++j) +
    + { +
    + if (ds_grid_get(grid, i, j) == 1) +
    + { +
    + instance_create_layer(i * 32, j * 32, "Walls", obj_Wall); +
    + } +
    + } +
    + }

    +

    The above code will loop through the DS grid indexed in the variable "grid" and if the value found in any specific cell is equal to 1, it will then create an instance of "obj_Wall" at the appropriate position within the room.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_write.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_write.htm index 5930c738e..c7c716af7 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_write.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Grids/ds_grid_write.htm @@ -1,64 +1,65 @@ - - + - - - ds_grid_write - - - - - - - - - - - - -

    ds_grid_write

    -

    This function can be used to convert the given ds_grid into a string, which can then be stored in an external file (for example). You can read the returned string from this function back into a ds_grid using the function ds_grid_read().

    -

    NOTE The returned string is not a human readable string, but rather a dump of the contents of the data-structure.

    -

     

    -

    Syntax:

    -

    ds_grid_write(index);

    - - - - - - - - - - - -
    ArgumentTypeDescription
    indexThe index of the grid to write.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    ini_open("Save.ini");
    ini_write_string("Save", "0", ds_grid_write(mygrid));
    ini_close() -

    -

    The above code will open an ini file (creating it if it doesn't already exist) and then write the given ds_grid as a string to that file.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Grids
    - + + + + ds_grid_write + + + + + + + + + + +

    ds_grid_write

    +

    This function can be used to convert the given ds_grid into a string, which can then be stored in an external file (for example). You can read the returned string from this function back into a ds_grid using the function ds_grid_read().

    +

    NOTE The returned string is not a human readable string, but rather a dump of the contents of the data-structure.

    +

    +

    Syntax:

    +

    ds_grid_write(index);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indexThe handle of the grid to write.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    ini_open("Save.ini"); +
    + ini_write_string("Save", "0", ds_grid_write(mygrid)); +
    + ini_close()

    +

    The above code will open an ini file (creating it if it doesn't already exist) and then write the given ds_grid as a string to that file.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Grids
    + +
    +
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - - \ No newline at end of file +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_add.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_add.htm index a1c9706b9..0f5e3a6d1 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_add.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_add.htm @@ -1,72 +1,69 @@ - + - - - ds_list_add - - - - - - - - - - -

    ds_list_add

    -

    This function can be used to add a new value (real or string) to the list, which will be added on at the end. The function can take further optional arguments (as many as you require), permitting you to add multiple values consecutively to the list in a single call.

    -

     

    -

    Syntax:

    -

    ds_list_add(id, val1 [, val2, ... max_val]);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS List IDThe id of the list to add to.
    valVariableThe value to add to the list.
    [val2, ... max_val]VariableOptional values to be added to the list.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    ds_list_add(sc_list, score);

    -

    The above code will add the value stored in the "score" variable into the list indexed in the variable "sc_list".

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Lists
    - + + + ds_list_add + + + + + + + + + +

    ds_list_add

    +

    This function can be used to add a new value (real or string) to the list, which will be added on at the end. The function can take further optional arguments (as many as you require), permitting you to add multiple values consecutively to the list in a single call.

    +

    +

    Syntax:

    +

    ds_list_add(id, val1 [, val2, ... max_val]);

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS List IDThe handle of the list to add to.
    valVariableThe value to add to the list.
    [val2, ... max_val]VariableOptional values to be added to the list.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    ds_list_add(sc_list, score);

    +

    The above code will add the value stored in the "score" variable into the list indexed in the variable "sc_list".

    +

    +

    +

    +
    +
    +
    +
    Back: DS Lists
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_clear.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_clear.htm index c36b275a9..48200ad4c 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_clear.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_clear.htm @@ -1,66 +1,68 @@ - + - - - ds_list_clear - - - - - - - - - - -

    ds_list_clear

    -

    With this function you can clear all data from the given list data-structure. This does NOT destroy the data-structure (for that you should use ds_list_destroy()) it only wipes all data from it and makes the list empty (zero in size). Note that clearing a list will de-reference any data structures stored in it giving a memory leak, so you would need to go through the list and destroy all data structure items manually before clearing it to prevent this. The only time this is not required is when you have flagged any items in the list as another DS list or as a DS map, in which case these items will be destroyed (not cleared!) and their memory cleaned up automatically when the parent is cleared.

    -

     

    -

    Syntax:

    -

    ds_list_clear(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS List IDThe id of the data structure to clear.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    if (count == 15) && (!ds_list_empty(command_list))
    - {
    -     ds_list_clear(command_list);
    -     alarm[0] = game_get_speed(gamespeed_fps);
    -     ai_count = 0;
    - }

    -

    The above code checks a variable to see if it has reached a specific value and if it has it clears the DS list indexed in the variable "command_list", sets an alarm, and resets the variable to 0.

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Lists
    - + + + ds_list_clear + + + + + + + + + +

    ds_list_clear

    +

    With this function you can clear all data from the given list data-structure. This does NOT destroy the data-structure (for that you should use ds_list_destroy()) it only wipes all data from it and makes the list empty (zero in size). Note that clearing a list will de-reference any data structures stored in it giving a memory leak, so you would need to go through the list and destroy all data structure items manually before clearing it to prevent this. The only time this is not required is when you have flagged any items in the list as another DS list or as a DS map, in which case these items will be destroyed (not cleared!) and their memory cleaned up automatically when the parent is cleared.

    +

    +

    Syntax:

    +

    ds_list_clear(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS List IDThe handle of the data structure to clear.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    if (count == 15) && (!ds_list_empty(command_list)) +
    + { +
    + ds_list_clear(command_list); +
    + alarm[0] = game_get_speed(gamespeed_fps); +
    + ai_count = 0; +
    + }

    +

    The above code checks a variable to see if it has reached a specific value and if it has it clears the DS list indexed in the variable "command_list", sets an alarm, and resets the variable to 0.

    +

    +

    +
    +
    +
    +
    Back: DS Lists
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_copy.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_copy.htm index abc303453..b4c1062c1 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_copy.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_copy.htm @@ -1,69 +1,74 @@ - + - - - ds_list_copy - - - - - - - - - - -

    ds_list_copy

    -

    With this function you can copy the contents of one list into another. Both lists must have been created previously and if the list being copied to already has information within it, this list will be cleared first. The end result is two independent lists which contain the same information.

    -

     

    -

    Syntax:

    -

    ds_list_copy( id, source );

    - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idThe id of the list being copied to.
    sourceThe id of the list to be copied from.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    if (!ds_list_empty(main_list))
    - {
    -     old_list = ds_list_create();
    -     ds_list_copy(old_list, main_list);
    -     ds_list_clear(main_list);
    - }

    -

    The above code will check a DS list to see if it is empty. If it is not empty it is copied into another DS list (which has been created previously) and then the original list is cleared.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Lists
    - + + + ds_list_copy + + + + + + + + + +

    ds_list_copy

    +

    With this function you can copy the contents of one list into another. Both lists must have been created previously and if the list being copied to already has information within it, this list will be cleared first. The end result is two independent lists which contain the same information.

    +

    +

    Syntax:

    +

    ds_list_copy( id, source );

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idThe handle of the list being copied to.
    sourceThe handle of the list to be copied from.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    if (!ds_list_empty(main_list)) +
    + { +
    + old_list = ds_list_create(); +
    + ds_list_copy(old_list, main_list); +
    + ds_list_clear(main_list); +
    + }

    +

    The above code will check a DS list to see if it is empty. If it is not empty it is copied into another DS list (which has been created previously) and then the original list is cleared.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Lists
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_delete.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_delete.htm index 42f68902c..8177bc34f 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_delete.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_delete.htm @@ -1,70 +1,76 @@ - + - - - ds_list_delete - - - - - - - - - - -

    ds_list_delete

    -

    With this function you can remove the value stored at a specific position within the list.

    -

     

    -

    Syntax:

    -

    ds_list_delete(id, pos);

    - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idThe id of the list to change.
    posWhere in the list to delete the value.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    if (ds_list_size(sc_list) > 10)
    - {
    -     while (ds_list_size(sc_list) > 10)
    -     {
    -         ds_list_delete(sc_list, 0);
    -     }
    - }

    -

    The above code checks the size of a DS list and if it is larger than ten, it loops through the list removing the top value (position 0) until the list has only 10 entries.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Lists
    - + + + ds_list_delete + + + + + + + + + +

    ds_list_delete

    +

    With this function you can remove the value stored at a specific position within the list.

    +

    +

    Syntax:

    +

    ds_list_delete(id, pos);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idThe handle of the list to change.
    posWhere in the list to delete the value.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    if (ds_list_size(sc_list) > 10) +
    + { +
    + while (ds_list_size(sc_list) > 10) +
    + { +
    + ds_list_delete(sc_list, 0); +
    + } +
    + }

    +

    The above code checks the size of a DS list and if it is larger than ten, it loops through the list removing the top value (position 0) until the list has only 10 entries.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Lists
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_destroy.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_destroy.htm index dde88d2b4..54967aaff 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_destroy.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_destroy.htm @@ -1,68 +1,70 @@ - + - - - ds_list_destroy - - - - - - - - - - -

    ds_list_destroy

    -

    This function will remove the given list data structure from memory, freeing up the resources it was using and removing all values that it contained. This function should always be used when you are finished using the DS list to prevent memory leaks that can slow down and crash your game.

    -

     Destroying a list will de-reference any data structures stored in it giving a memory leak, so you would need to go through the list and destroy all data structure items manually before destroying it to prevent this. The only time this is not required is when you have flagged any items in the list as another DS list or as a DS map, in which case these items will be destroyed and their memory cleaned up automatically as well.

    -
    -

     

    -

    Syntax:

    -

    ds_list_destroy(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS ListThe id of the data structure to remove.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    if (lives == 0)
    - {
    -     ds_list_destroy(AI_list);
    -     AI_list = -1;
    -     room_goto(rm_Menu);
    - }

    -

    The above code will check the value of the built-in global variable lives and if it is 0, it destroys the DS list indexed in the variable AI_list and then changes rooms.

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Lists
    - + + + ds_list_destroy + + + + + + + + + +

    ds_list_destroy

    +

    This function will remove the given list data structure from memory, freeing up the resources it was using and removing all values that it contained. This function should always be used when you are finished using the DS list to prevent memory leaks that can slow down and crash your game.

    +

    Destroying a list will de-reference any data structures stored in it giving a memory leak, so you would need to go through the list and destroy all data structure items manually before destroying it to prevent this. The only time this is not required is when you have flagged any items in the list as another DS list or as a DS map, in which case these items will be destroyed and their memory cleaned up automatically as well.

    +
    +

    +

    Syntax:

    +

    ds_list_destroy(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS ListThe handle of the data structure to remove.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    if (lives == 0) +
    + { +
    + ds_list_destroy(AI_list); +
    + AI_list = -1; +
    + room_goto(rm_Menu); +
    + }

    +

    The above code will check the value of the built-in global variable lives and if it is 0, it destroys the DS list indexed in the variable AI_list and then changes rooms.

    +

    +

    +
    +
    +
    +
    Back: DS Lists
    + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_empty.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_empty.htm index 38469fa9c..a57ad418a 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_empty.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_empty.htm @@ -1,67 +1,69 @@ - + - - - ds_list_empty - - - - - - - - - - - -

    ds_list_empty

    -

    With this function you can check the given DS list to see if it is empty (returns true) or not (returns false).

    -

     

    -

    Syntax:

    -

    ds_list_empty(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS List idThe id of the data structure to check.
    -

     

    -

    Returns:

    -

    Boolean

    -

     

    -

    Example:

    -

    if (count == 15( && (!ds_list_empty(command_list))
    - {
    -     ds_list_clear(command_list);
    -     alarm[0] = game_get_speed(gamespeed_fps);
    -     count = 0;
    - }

    -

    The above code checks a variable to see if it has reached a specific value and if it has it clears the DS list indexed in the variable "command_list", sets an alarm, and resets the variable to 0.

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Lists
    - + + + ds_list_empty + + + + + + + + + + +

    ds_list_empty

    +

    With this function you can check the given DS list to see if it is empty (returns true) or not (returns false).

    +

    +

    Syntax:

    +

    ds_list_empty(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS List idThe handle of the data structure to check.
    +

    +

    Returns:

    +

    Boolean

    +

    +

    Example:

    +

    if (count == 15( && (!ds_list_empty(command_list)) +
    + { +
    + ds_list_clear(command_list); +
    + alarm[0] = game_get_speed(gamespeed_fps); +
    + count = 0; +
    + }

    +

    The above code checks a variable to see if it has reached a specific value and if it has it clears the DS list indexed in the variable "command_list", sets an alarm, and resets the variable to 0.

    +

    +

    +
    +
    +
    +
    Back: DS Lists
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_find_index.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_find_index.htm index 0fad68de1..468fff9ae 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_find_index.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_find_index.htm @@ -1,68 +1,65 @@ - + - - - ds_list_find_index - - - - - - - - - - - -

    ds_list_find_index

    -

    With this function you can check the given list for a value and the position within the list for that value will be returned. Note that if there are more than one entries in the list with the same value, the position of any one of them may be returned, and that if the value does not exist, then -1 will be returned.

    -

     

    -

    Syntax:

    -

    ds_list_find_index(id, val);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS List IDThe id of the list to use.
    valVariableThe value to find.
    -

     

    -

    Returns:

    -

    Real

    -

     

    -

    Example:

    -

    pos = ds_list_find_index(list, "Player1");

    -

    The above code checks the list indexed in the variable "list" for the value "Player1" and stores the returned position in the variable "pos".

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Lists
    - + + + ds_list_find_index + + + + + + + + + + +

    ds_list_find_index

    +

    With this function you can check the given list for a value and the position within the list for that value will be returned. Note that if there are more than one entries in the list with the same value, the position of any one of them may be returned, and that if the value does not exist, then -1 will be returned.

    +

    +

    Syntax:

    +

    ds_list_find_index(id, val);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS List IDThe handle of the list to use.
    valVariableThe value to find.
    +

    +

    Returns:

    +

    Real

    +

    +

    Example:

    +

    pos = ds_list_find_index(list, "Player1");

    +

    The above code checks the list indexed in the variable "list" for the value "Player1" and stores the returned position in the variable "pos".

    +

    +

    +

    +
    +
    +
    +
    Back: DS Lists
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_find_value.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_find_value.htm index e266e4c11..a9fd3d864 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_find_value.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_find_value.htm @@ -1,68 +1,65 @@ - + - - - ds_list_find_value - - - - - - - - - - - -

    ds_list_find_value

    -

    With this function you can check the given list position and the value held within the list for that position will be returned. Note that if you give a position that is outside of the given list size (i.e.: position 11 in a 10 value list) then the function may return undefined or 0. This is because when you create the list, internally the first few entries in the list are set to 0 to minimize performance issues when initially adding items to the list (although the ds_list_size() function will still return 0 on a newly created list). If you wish to ensure that the list is "truly" empty on create, then you should call ds_list_clear() after creating the list, which will then mean that any values returned for unpopulated list slots will be undefined, which you can then check consistently using the is_undefined() function.

    -

     

    -

    Syntax:

    -

    ds_list_find_value(id, pos);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS List IDThe id of the list to use.
    posRealThe position to look at, where 0 corresponds to the very beginning of the list and the final position is ds_list_size(id)-1.
    -

     

    -

    Returns:

    -

    Variable or undefined

    -

     

    -

    Example:

    -

    val = ds_list_find_value(list, ds_list_size(list) - 1);

    -

    The above code checks the list indexed in the variable "list" at the last position in the list and stores the returned value in the variable "val".

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Lists
    - + + + ds_list_find_value + + + + + + + + + + +

    ds_list_find_value

    +

    With this function you can check the given list position and the value held within the list for that position will be returned. Note that if you give a position that is outside of the given list size (i.e.: position 11 in a 10 value list) then the function may return undefined or 0. This is because when you create the list, internally the first few entries in the list are set to 0 to minimize performance issues when initially adding items to the list (although the ds_list_size() function will still return 0 on a newly created list). If you wish to ensure that the list is "truly" empty on create, then you should call ds_list_clear() after creating the list, which will then mean that any values returned for unpopulated list slots will be undefined, which you can then check consistently using the is_undefined() function.

    +

    +

    Syntax:

    +

    ds_list_find_value(id, pos);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS List IDThe handle of the list to use.
    posRealThe position to look at, where 0 corresponds to the very beginning of the list and the final position is ds_list_size(id)-1.
    +

    +

    Returns:

    +

    Variable or undefined

    +

    +

    Example:

    +

    val = ds_list_find_value(list, ds_list_size(list) - 1);

    +

    The above code checks the list indexed in the variable "list" at the last position in the list and stores the returned value in the variable "val".

    +

    +

    +

    +
    +
    +
    +
    Back: DS Lists
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_insert.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_insert.htm index e0eebd2e0..7fa1c6954 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_insert.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_insert.htm @@ -1,72 +1,69 @@ - + - - - ds_list_insert - - - - - - - - - - -

    ds_list_insert

    -

    This function will add the given value into the list at the given position. if the list contains more values after the given position, their position will be shifted up one to make room making the list larger by one.

    -

     

    -

    Syntax:

    -

    ds_list_insert(id, pos, val);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS List IDThe id of the list to add to.
    posRealThe position to add the value, where 0 corresponds to the very beginning of the list and the final position is ds_list_size(id)-1.
    valVariableThe value to add to the list.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    ds_list_insert(list, 9, score);

    -

    The above code will add the value stored in the variable "score" into the 10th position of the list indexed by the variable "list" (lists are counted from 0, so a ten value list is numbered from 0 - 9).

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Lists
    - + + + ds_list_insert + + + + + + + + + +

    ds_list_insert

    +

    This function will add the given value into the list at the given position. if the list contains more values after the given position, their position will be shifted up one to make room making the list larger by one.

    +

    +

    Syntax:

    +

    ds_list_insert(id, pos, val);

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS List IDThe handle of the list to add to.
    posRealThe position to add the value, where 0 corresponds to the very beginning of the list and the final position is ds_list_size(id)-1.
    valVariableThe value to add to the list.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    ds_list_insert(list, 9, score);

    +

    The above code will add the value stored in the variable "score" into the 10th position of the list indexed by the variable "list" (lists are counted from 0, so a ten value list is numbered from 0 - 9).

    +

    +

    +

    +
    +
    +
    +
    Back: DS Lists
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_is_list.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_is_list.htm index fc28ed138..d1f10a47a 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_is_list.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_is_list.htm @@ -1,76 +1,81 @@ - + - - - ds_list_is_list - - - - - - - - - - - -

    ds_list_is_list

    -

    With this function you can check to see if another DS list is stored at the given position within a DS list. If the given position contains a DS list ID, then the function will return true otherwise it will return false.

    -

     This will only detect lists that were manually marked using the ds_list_mark_as_list function.

    -

     

    -

    Syntax:

    -

    ds_list_is_list(id, pos);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS ListThe ID of the list to check.
    posRealThe position within the list to check.
    -

     

    -

    Returns:

    -

    Boolean

    -

     

    -

    Example:

    -

    var size = ds_list_size(ships);
    - for (var i = 0; i < size; i++)
    - {
    -     if (ds_list_is_list(ships, i))
    -     {
    -         ds_list_destroy(ships[| i]);
    -     }
    - }
    - ds_list_destroy(ships);

    -

    The above code loops through a DS list and checks to see if any of the entries contain other list IDs. If they do, then these lists are destroyed, and then the main list is destroyed after the loop is finished.

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Lists
    - + + + ds_list_is_list + + + + + + + + + + +

    ds_list_is_list

    +

    With this function you can check to see if another DS list is stored at the given position within a DS list. If the given position contains a DS list ID, then the function will return true otherwise it will return false.

    +

    This will only detect lists that were manually marked using the ds_list_mark_as_list function.

    +

    +

    Syntax:

    +

    ds_list_is_list(id, pos);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS ListThe handle of the list to check.
    posRealThe position within the list to check.
    +

    +

    Returns:

    +

    Boolean

    +

    +

    Example:

    +

    var size = ds_list_size(ships); +
    + for (var i = 0; i < size; i++) +
    + { +
    + if (ds_list_is_list(ships, i)) +
    + { +
    + ds_list_destroy(ships[| i]); +
    + } +
    + } +
    + ds_list_destroy(ships);

    +

    The above code loops through a DS list and checks to see if any of the entries contain other list IDs. If they do, then these lists are destroyed, and then the main list is destroyed after the loop is finished.

    +

    +

    +
    +
    +
    +
    Back: DS Lists
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_is_map.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_is_map.htm index 87e2b08d0..94fe04058 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_is_map.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_is_map.htm @@ -1,76 +1,81 @@ - + - - - ds_list_is_map - - - - - - - - - - - -

    ds_list_is_map

    -

    With this function you can check to see if a DS map is stored at the given position within a DS list. If the given position contains a DS map ID, then the function will return true otherwise it will return false.

    -

     This will only detect maps that were manually marked using the ds_list_mark_as_map function.

    -

     

    -

    Syntax:

    -

    ds_list_is_map(id, pos);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS ListThe ID of the list to check.
    posRealThe position within the list to check.
    -

     

    -

    Returns:

    -

    Boolean

    -

     

    -

    Example:

    -

    var size = ds_list_size(ships);
    - for (var i = 0; i < size; i++)
    - {
    -     if (ds_list_is_map(ships, i))
    -     {
    -         ds_map_destroy(ships[| i]);
    -     }
    - }
    - ds_list_destroy(ships);

    -

    The above code loops through a DS list and checks to see if any of the entries contain map IDs. If they do, then these maps are destroyed, and then the main list is destroyed after the loop is finished.

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Lists
    - + + + ds_list_is_map + + + + + + + + + + +

    ds_list_is_map

    +

    With this function you can check to see if a DS map is stored at the given position within a DS list. If the given position contains a DS map ID, then the function will return true otherwise it will return false.

    +

    This will only detect maps that were manually marked using the ds_list_mark_as_map function.

    +

    +

    Syntax:

    +

    ds_list_is_map(id, pos);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS ListThe handle of the list to check.
    posRealThe position within the list to check.
    +

    +

    Returns:

    +

    Boolean

    +

    +

    Example:

    +

    var size = ds_list_size(ships); +
    + for (var i = 0; i < size; i++) +
    + { +
    + if (ds_list_is_map(ships, i)) +
    + { +
    + ds_map_destroy(ships[| i]); +
    + } +
    + } +
    + ds_list_destroy(ships);

    +

    The above code loops through a DS list and checks to see if any of the entries contain map IDs. If they do, then these maps are destroyed, and then the main list is destroyed after the loop is finished.

    +

    +

    +
    +
    +
    +
    Back: DS Lists
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_mark_as_list.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_mark_as_list.htm index 3b1e88f08..b04fc2438 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_mark_as_list.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_mark_as_list.htm @@ -1,74 +1,77 @@ - + - - - ds_list_mark_as_list - - - - - - - - - - -

    ds_list_mark_as_list

    -

    This function will "mark" (or "flag") a given position within a previously created DS list as holding another DS list.

    -

    This functionality is required when encoding JSON strings (which you can create using json_encode), but can also be useful when nesting data structures, as items marked in this way will automatically be garbage collected (destroyed) when the parent DS list is destroyed. This means that you do not have to manually go through the list contents and destroy the marked data structures individually before destroying the "parent" list. However, if you delete the list position individually, the DS list it contained will not be garbage collected and you should call the appropriate DS list destroy function before deleting the item from the parent list position. Also note that if you call the function ds_list_clear on a list, any items flagged as lists will be destroyed as well when the list is cleared.

    -
    -

     

    -

    Syntax:

    -

    ds_list_mark_as_list(id, pos);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS ListThe ID of the list to mark.
    posRealThe position within the list to mark.
    -

     

    -

    Returns:

    -

    DS List or -1 (if it fails)

    -

     

    -

    Example:

    -

    var j_list = ds_list_create();
    - var sub_list = ds_list_create();
    - ds_list_add(sub_list, health);
    - ds_list_add(sub_list, lives);
    - ds_list_add(sub_list, score);
    - ds_list_add(j_list, sub_list);
    - ds_list_mark_as_list(j_list, 0);

    -

    The above code creates two DS lists, then populates one with various values from global variables. This list is then added into the second list, and the position "marked" as such so that it can be correctly encoded later.

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Lists
    - + + + ds_list_mark_as_list + + + + + + + + + +

    ds_list_mark_as_list

    +

    This function will "mark" (or "flag") a given position within a previously created DS list as holding another DS list.

    +

    This functionality is required when encoding JSON strings (which you can create using json_encode), but can also be useful when nesting data structures, as items marked in this way will automatically be garbage collected (destroyed) when the parent DS list is destroyed. This means that you do not have to manually go through the list contents and destroy the marked data structures individually before destroying the "parent" list. However, if you delete the list position individually, the DS list it contained will not be garbage collected and you should call the appropriate DS list destroy function before deleting the item from the parent list position. Also note that if you call the function ds_list_clear on a list, any items flagged as lists will be destroyed as well when the list is cleared.

    +
    +

    +

    Syntax:

    +

    ds_list_mark_as_list(id, pos);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS ListThe handle of the list to mark.
    posRealThe position within the list to mark.
    +

    +

    Returns:

    +

    DS List or -1 (if it fails)

    +

    +

    Example:

    +

    var j_list = ds_list_create(); +
    + var sub_list = ds_list_create(); +
    + ds_list_add(sub_list, health); +
    + ds_list_add(sub_list, lives); +
    + ds_list_add(sub_list, score); +
    + ds_list_add(j_list, sub_list); +
    + ds_list_mark_as_list(j_list, 0);

    +

    The above code creates two DS lists, then populates one with various values from global variables. This list is then added into the second list, and the position "marked" as such so that it can be correctly encoded later.

    +

    +

    +
    +
    +
    +
    Back: DS Lists
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_mark_as_map.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_mark_as_map.htm index 72aa5c2f4..c55496796 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_mark_as_map.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_mark_as_map.htm @@ -1,72 +1,73 @@ - + - - - ds_list_mark_as_map - - - - - - - - - - -

    ds_list_mark_as_map

    -

    This function will "mark" (or "flag") a given position within a previously created DS list as holding a DS map.

    -

    This functionality is required when encoding JSON strings (which you can create using json_encode), but can also be useful when nesting data structures, as items marked in this way will automatically be garbage collected (destroyed) when the parent DS list is destroyed. This means that you do not have to manually go through the list contents and destroy the marked data structures individually before destroying the "parent" list. However, if you delete the list position individually, the data structure it contained will not be garbage collected and you should call the appropriate DS map destroy function before deleting the parent list position. Also note that if you call the function ds_list_clear on a list, any items flagged as maps will be destroyed as well when the list is cleared.

    -
    -

     

    -

    Syntax:

    -

    ds_list_mark_as_map(id, pos);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS ListThe ID of the list to mark.
    posRealThe position within the list to mark.
    -

     

    -

    Returns:

    -

    DS Map or -1 (if it fails)

    -

     

    -

    Example:

    -

    var sub_map = ds_map_create();
    - ds_map_add(sub_map, "player", player_array);
    - ds_map_add(sub_map, "enemy", enemy_array);
    - ds_list_add(j_list, sub_map);
    - ds_list_mark_as_map(j_list, 0);

    -

    The above code creates a DS map and then populates it with two keys, each containing an array of values. This map is then added to the given DS list , and the position "marked" as such so that it can be correctly encoded later.

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Lists
    - + + + ds_list_mark_as_map + + + + + + + + + +

    ds_list_mark_as_map

    +

    This function will "mark" (or "flag") a given position within a previously created DS list as holding a DS map.

    +

    This functionality is required when encoding JSON strings (which you can create using json_encode), but can also be useful when nesting data structures, as items marked in this way will automatically be garbage collected (destroyed) when the parent DS list is destroyed. This means that you do not have to manually go through the list contents and destroy the marked data structures individually before destroying the "parent" list. However, if you delete the list position individually, the data structure it contained will not be garbage collected and you should call the appropriate DS map destroy function before deleting the parent list position. Also note that if you call the function ds_list_clear on a list, any items flagged as maps will be destroyed as well when the list is cleared.

    +
    +

    +

    Syntax:

    +

    ds_list_mark_as_map(id, pos);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS ListThe handle of the list to mark.
    posRealThe position within the list to mark.
    +

    +

    Returns:

    +

    DS Map or -1 (if it fails)

    +

    +

    Example:

    +

    var sub_map = ds_map_create(); +
    + ds_map_add(sub_map, "player", player_array); +
    + ds_map_add(sub_map, "enemy", enemy_array); +
    + ds_list_add(j_list, sub_map); +
    + ds_list_mark_as_map(j_list, 0);

    +

    The above code creates a DS map and then populates it with two keys, each containing an array of values. This map is then added to the given DS list , and the position "marked" as such so that it can be correctly encoded later.

    +

    +

    +
    +
    +
    +
    Back: DS Lists
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_read.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_read.htm index a4490a0fe..ad3e7dec8 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_read.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_read.htm @@ -1,80 +1,84 @@ - + - - - ds_list_read - - - - - - - - - - -

    ds_list_read

    -

    With this function you can recreate a saved DS list (one that has previously been written as a string using ds_list_write()). You must first create a new DS list to read the string into, and if the DS list already exists and has information stored in it, then this will be cleared before reading. This function is of vital importance when creating save/load mechanisms for your game.

    -

    Note that if the specified DS string was written by the GameMaker: Studio 1.2.x runtime (or older), you should specify the optional argument "legacy", setting it to true as the string format changed after that.

    -

     

    -

    Syntax:

    -

    ds_list_read(id, str [, legacy]);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS List IDThe id of the data structure to read into.
    strStringThe string to read from.
    legacyBooleanOPTIONAL Can be either true or false or omitted completely.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    list = ds_list_create();
    - ini_open("save.ini");
    - var str = ini_read_string("Lists", "0", "");
    - if (str != "")
    - {
    -     ds_list_read(list, str);
    - }
    - ini_close();

    -

    The above code creates a list and stores the index in the variable "list". It then opens an ini file and reads a string from that, checking to make sure that the string is not returned as empty first. This string is then read into the newly created ds_list.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Lists
    - + + + ds_list_read + + + + + + + + + +

    ds_list_read

    +

    With this function you can recreate a saved DS list (one that has previously been written as a string using ds_list_write()). You must first create a new DS list to read the string into, and if the DS list already exists and has information stored in it, then this will be cleared before reading. This function is of vital importance when creating save/load mechanisms for your game.

    +

    Note that if the specified DS string was written by the GameMaker: Studio 1.2.x runtime (or older), you should specify the optional argument "legacy", setting it to true as the string format changed after that.

    +

    +

    Syntax:

    +

    ds_list_read(id, str [, legacy]);

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS List IDThe handle of the data structure to read into.
    strStringThe string to read from.
    legacyBooleanOPTIONAL Can be either true or false or omitted completely.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    list = ds_list_create(); +
    + ini_open("save.ini"); +
    + var str = ini_read_string("Lists", "0", ""); +
    + if (str != "") +
    + { +
    + ds_list_read(list, str); +
    + } +
    + ini_close();

    +

    The above code creates a list and stores the index in the variable "list". It then opens an ini file and reads a string from that, checking to make sure that the string is not returned as empty first. This string is then read into the newly created ds_list.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Lists
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_replace.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_replace.htm index 2934a1636..8a7b9247b 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_replace.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_replace.htm @@ -1,72 +1,69 @@ - + - - - ds_list_replace - - - - - - - - - - -

    ds_list_replace

    -

    This function will replace the value at the given position for another one.

    -

    Attempting to replace an item at a position out of bounds results in an error, e.g. ds_list_replace :: Trying to access an out-of-bounds index [| 4].

    -

     

    -

    Syntax:

    -

    ds_list_replace(id, pos, val);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS List IDThe id of the list to change.
    posRealThe position to replace the value, where 0 corresponds to the very beginning of the list and the final position is ds_list_size(id)-1.
    valAnyThe new value to replace the given value with.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    ds_list_replace(n_list, 3, name);

    -

    The above code will replace the value stored at position 3 in the list for that stored in the variable "name".

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Lists
    - + + + ds_list_replace + + + + + + + + + +

    ds_list_replace

    +

    This function will replace the value at the given position for another one.

    +

    Attempting to replace an item at a position out of bounds results in an error, e.g. ds_list_replace :: Trying to access an out-of-bounds index [| 4].

    +

    +

    Syntax:

    +

    ds_list_replace(id, pos, val);

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS List IDThe handle of the list to change.
    posRealThe position to replace the value, where 0 corresponds to the very beginning of the list and the final position is ds_list_size(id)-1.
    valAnyThe new value to replace the given value with.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    ds_list_replace(n_list, 3, name);

    +

    The above code will replace the value stored at position 3 in the list for that stored in the variable "name".

    +

    +

    +
    +
    +
    +
    Back: DS Lists
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_set.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_set.htm index d4e86967b..717e354ca 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_set.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_set.htm @@ -1,75 +1,74 @@ - + - - - ds_list_set - - - - - - - - - - -

    ds_list_set

    -

    This function can be used to set a previously added list entry. It does the same as the DS list accessor.

    -

    You give the list ID (as returned when you created the list) and the position within the list to set as well as the value to set it to.

    -

     If the entry being set is outside the bounds of the list (i.e., you set list entry 20 but the current list only contains 10 entries) then the list will be filled to the given position and each entry will be set to 0.

    -

     

    -

    Syntax:

    -

    ds_list_set(id, pos, val);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS ListThe ID of the list to add to.
    posAnyThe position within the list to set.
    [val2, ... max_val]AnyThe value to set in the list.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    list = ds_list_create();
    - ds_list_add(list, 71, 77, 46);
    - ds_list_set(list, 2, 33);

    -

    The above code first creates a new DS list and stores it in an instance variable list. It then adds a few values to the list add finally sets the last value (the third value at index 2) with a call to ds_list_set.

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Lists
    - + + + ds_list_set + + + + + + + + + +

    ds_list_set

    +

    This function can be used to set a previously added list entry. It does the same as the DS list accessor.

    +

    You give the list ID (as returned when you created the list) and the position within the list to set as well as the value to set it to.

    +

    If the entry being set is outside the bounds of the list (i.e., you set list entry 20 but the current list only contains 10 entries) then the list will be filled to the given position and each entry will be set to 0.

    +

    +

    Syntax:

    +

    ds_list_set(id, pos, val);

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS ListThe handle of the list to add to.
    posAnyThe position within the list to set.
    [val2, ... max_val]AnyThe value to set in the list.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    list = ds_list_create(); +
    + ds_list_add(list, 71, 77, 46); +
    + ds_list_set(list, 2, 33);

    +

    The above code first creates a new DS list and stores it in an instance variable list. It then adds a few values to the list add finally sets the last value (the third value at index 2) with a call to ds_list_set.

    +

    +

    +
    +
    +
    +
    Back: DS Lists
    + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_shuffle.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_shuffle.htm index a5e6f6059..c2f4128c5 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_shuffle.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_shuffle.htm @@ -1,66 +1,66 @@ - + - - - ds_list_shuffle - - - - - - - - - - -

    ds_list_shuffle

    -

    With this function you can shuffle a list, which will re-order all the component values into random positions from those in which they were originally added to the list.

    -
    -

     

    -

    Syntax:

    -

    ds_list_shuffle(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS List IDThe id of the list to shuffle.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    if (restart)
    - {
    -     ds_list_shuffle(card_list);
    - }

    -

    The above code will shuffle the list indexed in the variable "card_list" if the variable "restart" is flagged as true.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Lists
    - + + + ds_list_shuffle + + + + + + + + + +

    ds_list_shuffle

    +

    With this function you can shuffle a list, which will re-order all the component values into random positions from those in which they were originally added to the list.

    +
    +

    +

    Syntax:

    +

    ds_list_shuffle(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS List IDThe handle of the list to shuffle.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    if (restart) +
    + { +
    + ds_list_shuffle(card_list); +
    + }

    +

    The above code will shuffle the list indexed in the variable "card_list" if the variable "restart" is flagged as true.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Lists
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_size.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_size.htm index a6eebb2cd..da08eaf51 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_size.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_size.htm @@ -1,64 +1,66 @@ - + - - - ds_list_size - - - - - - - - - - - -

    ds_list_size

    -

    This function will return the "size" of the list, ie: the number of items that have been added into it.

    -

     

    -

    Syntax:

    -

    ds_list_size(id);

    - - - - - - - - - - - -
    ArgumentTypeDescription
    idThe id of the data structure to check.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    if (!ds_list_empty(control_list))
    - {
    -     num = ds_list_size(control_list);
    - }

    -

    The above code checks a DS list to see if it is empty or not, and if it is not, it gets the number of items that it contains and stores the value in a variable.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Lists
    - + + + ds_list_size + + + + + + + + + + +

    ds_list_size

    +

    This function will return the "size" of the list, ie: the number of items that have been added into it.

    +

    +

    Syntax:

    +

    ds_list_size(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idThe handle of the data structure to check.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    if (!ds_list_empty(control_list)) +
    + { +
    + num = ds_list_size(control_list); +
    + }

    +

    The above code checks a DS list to see if it is empty or not, and if it is not, it gets the number of items that it contains and stores the value in a variable.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Lists
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_sort.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_sort.htm index cb9e6a66a..fdb9ca3fe 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_sort.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_sort.htm @@ -1,67 +1,70 @@ - + - - - ds_list_sort - - - - - - - - - - -

    ds_list_sort

    -

    With this function you can sort all the values within a list, either in ascending or descending order. If the list contains strings, these will be sorted alphabetically, based on the English 26 letter alphabet.

    -

     

    -

    Syntax:

    -

    ds_list_sort(id, ascend);

    - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idThe id of the list to sort.
    ascendWhether the values should be ascending (true) or descending (false) order.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    if (newgame)
    - {
    -     ds_list_sort(name_list, true);
    - }

    -

    The above code will sort the list indexed in the variable "name_list" if the variable "newgame" is flagged as true.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Lists
    - + + + ds_list_sort + + + + + + + + + +

    ds_list_sort

    +

    With this function you can sort all the values within a list, either in ascending or descending order. If the list contains strings, these will be sorted alphabetically, based on the English 26 letter alphabet.

    +

    +

    Syntax:

    +

    ds_list_sort(id, ascend);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idThe handle of the list to sort.
    ascendWhether the values should be ascending (true) or descending (false) order.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    if (newgame) +
    + { +
    + ds_list_sort(name_list, true); +
    + }

    +

    The above code will sort the list indexed in the variable "name_list" if the variable "newgame" is flagged as true.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Lists
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_write.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_write.htm index 2d5d0ca73..af5b1c72d 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_write.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Lists/ds_list_write.htm @@ -1,68 +1,69 @@ - + - - - ds_list_write - - - - - - - - - - - -

    ds_list_write

    -

    This function returns a string which can then be stored or transferred to another data structure using the ds_list_read() function.

    -

     The returned string is not a human readable string, but rather a dump of the contents of the data-structure.

    -

     

    -

    Syntax:

    -

    ds_list_write(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS List IDThe id of the data structure to write.
    -

     

    -

    Returns:

    -

    String

    -

     

    -

    Example:

    -

    ini_open("save.ini");
    - var str = ds_list_write(list);
    - ini_write_string("Lists", "0", str);
    - ds_list_clear(list);
    - ini_close();

    -

    The above code opens an ini file and then writes a string containing the information stored in the DS list indexed in the variable "list". The list is then cleared and the ini file closed.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Lists
    - + + + ds_list_write + + + + + + + + + + +

    ds_list_write

    +

    This function returns a string which can then be stored or transferred to another data structure using the ds_list_read() function.

    +

    The returned string is not a human readable string, but rather a dump of the contents of the data-structure.

    +

    +

    Syntax:

    +

    ds_list_write(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS List IDThe handle of the data structure to write.
    +

    +

    Returns:

    +

    String

    +

    +

    Example:

    +

    ini_open("save.ini"); +
    + var str = ds_list_write(list); +
    + ini_write_string("Lists", "0", str); +
    + ds_list_clear(list); +
    + ini_close();

    +

    The above code opens an ini file and then writes a string containing the information stored in the DS list indexed in the variable "list". The list is then cleared and the ini file closed.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Lists
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_add.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_add.htm index ed558f9a6..784a6b874 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_add.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_add.htm @@ -1,86 +1,91 @@ - + - - - ds_map_add - - - - - - - - - - -

    ds_map_add

    -

    This function should be used to add sets of key/value pairs into the specified DS map.

    -

    You can check this function to see if it was successful or not (it will return true on success or false otherwise), as it may fail if there already exists the same key in the DS map or you specify a non-existent DS map as the ID of the map to add to.

    -

    The keys and and values you supply can be made up of any combination of data types, so all of the following - and more - are acceptable (although, in practice, you would most commonly use a string for the key):

    -

    ds_map_add(map, 5, undefined);
    - ds_map_add(map, "level", 1);
    - ds_map_add(map, 89.6, "hello world");
    - ds_map_add(map, 5, buffer_get_address(buff)); // This will return false and fail, as the key 5 already exists in the map

    -

    You can also add to a map using the accessor "?", as shown below, however this is a ds_map_set operation and will successfully update existing keys as well, unlike the add function.

    -

    map[? 5] = undefined;
    - map[? "level"] = 1;
    - map[? 89.6] = "hello world";
    - map[? 5] = buffer_get_address(buff); // This will succeed as it is a "set" and not an "add"

    -

    Unlike other data structures in GameMaker this key will not go to the start (nor the end) of the DS map, but rather it will just go into the DS map somewhere.

    -

     

    -

    Syntax:

    -

    ds_map_add(id, key, val);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS MapThe id of the map to add to.
    keyStringThe key of the value to add.
    valAnyThe value to add to the map.
    -

     

    -

    Returns:

    -

    Boolean

    -

     

    -

    Example:

    -

    inventory = ds_map_create();
    - ds_map_add(inventory, "hp potion", 1);
    - ds_map_add(inventory, "gold", 100);

    -

    This will create a new map, assigning its id to the variable "inventory". It then adds two new keys to the map, "hp potion" and "gold", and sets their initial values as 1 and 100.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_add + + + + + + + + + +

    ds_map_add

    +

    This function should be used to add sets of key/value pairs into the specified DS map.

    +

    You can check this function to see if it was successful or not (it will return true on success or false otherwise), as it may fail if there already exists the same key in the DS map or you specify a non-existent DS map as the ID of the map to add to.

    +

    The keys and and values you supply can be made up of any combination of data types, so all of the following - and more - are acceptable (although, in practice, you would most commonly use a string for the key):

    +

    ds_map_add(map, 5, undefined); +
    + ds_map_add(map, "level", 1); +
    + ds_map_add(map, 89.6, "hello world"); +
    + ds_map_add(map, 5, buffer_get_address(buff)); // This will return false and fail, as the key 5 already exists in the map

    +

    You can also add to a map using the accessor "?", as shown below, however this is a ds_map_set operation and will successfully update existing keys as well, unlike the add function.

    +

    map[? 5] = undefined; +
    + map[? "level"] = 1; +
    + map[? 89.6] = "hello world"; +
    + map[? 5] = buffer_get_address(buff); // This will succeed as it is a "set" and not an "add"

    +

    Unlike other data structures in GameMaker this key will not go to the start (nor the end) of the DS map, but rather it will just go into the DS map somewhere.

    +

    +

    Syntax:

    +

    ds_map_add(id, key, val);

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS MapThe handle of the map to add to.
    keyStringThe key of the value to add.
    valAnyThe value to add to the map.
    +

    +

    Returns:

    +

    Boolean

    +

    +

    Example:

    +

    inventory = ds_map_create(); +
    + ds_map_add(inventory, "hp potion", 1); +
    + ds_map_add(inventory, "gold", 100);

    +

    This will create a new map, assigning its id to the variable "inventory". It then adds two new keys to the map, "hp potion" and "gold", and sets their initial values as 1 and 100.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_add_list.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_add_list.htm index 2ac68d633..6c108852e 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_add_list.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_add_list.htm @@ -1,79 +1,83 @@ - + - - - ds_map_add_list - - - - - - - - - - -

    ds_map_add_list

    -

    With this function you can assign a (previously created) DS list to a key within the given DS map.

    -

    This function is designed for creating JSON compatible maps which you would then encode using json_encode and should only be used in conjunction with that functionality. If a DS map has a list added in this way, destroying the parent map will also destroy the contained lists and free their memory, and calling ds_map_clear on the parent map will also destroy and clean up any flagged lists.

    -

     

    -

    Syntax:

    -

    ds_map_add_list(id, key, value)

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS MapThe ID of the map to use.
    keyStringThe key for the added list.
    valueDS ListThe ID of the list to add.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    var j_list = ds_list_create();
    - ds_list_add(j_list, health);
    - ds_list_add(j_list, lives);
    - ds_list_add(j_list, score);
    - var j_map = ds_map_create();
    - ds_map_add_list(j_map, "list", j_list);
    - var j = json_encode(j_map);
    - ds_map_destroy(j_map);

    -

    The above code will create a list and populate it with the various values of global variables. This list is then "nested" within a DS map, and the map is then encoded into a JSON string, before the map is destroyed, removing it, and any lists it contains, from memory.

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_add_list + + + + + + + + + +

    ds_map_add_list

    +

    With this function you can assign a (previously created) DS list to a key within the given DS map.

    +

    This function is designed for creating JSON compatible maps which you would then encode using json_encode and should only be used in conjunction with that functionality. If a DS map has a list added in this way, destroying the parent map will also destroy the contained lists and free their memory, and calling ds_map_clear on the parent map will also destroy and clean up any flagged lists.

    +

    +

    Syntax:

    +

    ds_map_add_list(id, key, value)

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS MapThe handle of the map to use.
    keyStringThe key for the added list.
    valueDS ListThe handle of the list to add.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    var j_list = ds_list_create(); +
    + ds_list_add(j_list, health); +
    + ds_list_add(j_list, lives); +
    + ds_list_add(j_list, score); +
    + var j_map = ds_map_create(); +
    + ds_map_add_list(j_map, "list", j_list); +
    + var j = json_encode(j_map); +
    + ds_map_destroy(j_map);

    +

    The above code will create a list and populate it with the various values of global variables. This list is then "nested" within a DS map, and the map is then encoded into a JSON string, before the map is destroyed, removing it, and any lists it contains, from memory.

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_add_map.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_add_map.htm index 742f959d3..2cefa5add 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_add_map.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_add_map.htm @@ -1,79 +1,83 @@ - + - - - ds_map_add_map - - - - - - - - - - -

    ds_map_add_map

    -

    With this function you can assign a (previously created) DS map to a key within the given DS map.

    -

    This function is designed for creating JSON compatible maps which you would then encode using json_encode and should only be used in conjunction with that functionality. If a DS map has another map added in this way, then destroying the parent map will also destroy the contained maps and free their memory, and calling ds_map_clear on the parent map will also destroy and clean up any flagged maps.

    -

     

    -

    Syntax:

    -

    ds_map_add_map(id, key, value)

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS MapThe ID of the map to use.
    keyStringThe key for the added map.
    valueDS MapThe ID of the map to add.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    var j_map = ds_map_create();
    - var j_list = ds_list_create();
    - var sub_map = ds_map_create();
    - ds_map_add_list(sub_map, "list", j_list);
    - ds_map_add(sub_map, "array", j_array);
    - ds_map_add_map(j_map, "map", sub_map);
    - var j = json_encode(j_map);
    - ds_map_destroy(j_map);

    -

    The above code will create two DS maps, and then populate one with a list and an array before adding it into the second, which is then encoded into a JSON string. The map is then destroyed to remove it, and any other maps or lists that it contains, from memory.

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_add_map + + + + + + + + + +

    ds_map_add_map

    +

    With this function you can assign a (previously created) DS map to a key within the given DS map.

    +

    This function is designed for creating JSON compatible maps which you would then encode using json_encode and should only be used in conjunction with that functionality. If a DS map has another map added in this way, then destroying the parent map will also destroy the contained maps and free their memory, and calling ds_map_clear on the parent map will also destroy and clean up any flagged maps.

    +

    +

    Syntax:

    +

    ds_map_add_map(id, key, value)

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS MapThe handle of the map to use.
    keyStringThe key for the added map.
    valueDS MapThe handle of the map to add.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    var j_map = ds_map_create(); +
    + var j_list = ds_list_create(); +
    + var sub_map = ds_map_create(); +
    + ds_map_add_list(sub_map, "list", j_list); +
    + ds_map_add(sub_map, "array", j_array); +
    + ds_map_add_map(j_map, "map", sub_map); +
    + var j = json_encode(j_map); +
    + ds_map_destroy(j_map);

    +

    The above code will create two DS maps, and then populate one with a list and an array before adding it into the second, which is then encoded into a JSON string. The map is then destroyed to remove it, and any other maps or lists that it contains, from memory.

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_clear.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_clear.htm index 460221d95..1e25c3754 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_clear.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_clear.htm @@ -1,63 +1,65 @@ - + - - - ds_map_clear - - - - - - - - - - -

    ds_map_clear

    -

    This function will clear the (previously created) DS map of all key/value pairs, but it will not delete the DS map itself from memory. For that you should use the function ds_map_destroy(). Note that clearing a map will de-reference any data structures stored in the map giving a memory leak, so you would need to go through it and destroy all data structure items manually before clearing the map to prevent this. The only time this is not required is when you have flagged any items in the map as a DS list or as another DS map, in which case these items will be destroyed (not cleared!) and their memory cleaned up automatically when the parent map is cleared.

    -

     

    -

    Syntax:

    -

    ds_map_clear(id);

    - - - - - - - - - - - -
    ArgumentTypeDescription
    idThe id of the data structure to clear.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    if (global.new_game)
    - {
    -     ds_map_clear(inventory);
    - }

    -

    The above function will check a global variable to see if it is true and, if it is, then the DS map indexed in the instance variable "inventory" will be cleared of all key/value pairs (but it is not destroyed).

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_clear + + + + + + + + + +

    ds_map_clear

    +

    This function will clear the (previously created) DS map of all key/value pairs, but it will not delete the DS map itself from memory. For that you should use the function ds_map_destroy(). Note that clearing a map will de-reference any data structures stored in the map giving a memory leak, so you would need to go through it and destroy all data structure items manually before clearing the map to prevent this. The only time this is not required is when you have flagged any items in the map as a DS list or as another DS map, in which case these items will be destroyed (not cleared!) and their memory cleaned up automatically when the parent map is cleared.

    +

    +

    Syntax:

    +

    ds_map_clear(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idThe handle of the data structure to clear.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    if (global.new_game) +
    + { +
    + ds_map_clear(inventory); +
    + }

    +

    The above function will check a global variable to see if it is true and, if it is, then the DS map indexed in the instance variable "inventory" will be cleared of all key/value pairs (but it is not destroyed).

    +

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_copy.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_copy.htm index a3985269a..09890d60f 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_copy.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_copy.htm @@ -1,66 +1,66 @@ - - + - - - ds_map_copy - - - - - - - - - - - -

    ds_map_copy

    -

    You can use this function to copy the contents of one map into another one that you have previously created using ds_map_create(). If the DS map that is being copied to is not empty, - then this function will clear it first before copying. The original DS map remains unchanged by this process.

    -

     

    -

    Syntax:

    -

    ds_map_copy(id, source);

    - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idThe id of the map you are copying to
    sourceThe id of the map you are copying from
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    inventory_2 = ds_map_create();
    ds_map_copy(inventory_2, inventory_1);

    -

    The above code will create a new map and assign it to the variable "inventory_2". It will then copy the contents of the DS map indexed in the variable "inventory_1" to this new map.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + + ds_map_copy + + + + + + + + + +

    ds_map_copy

    +

    You can use this function to copy the contents of one map into another one that you have previously created using ds_map_create(). If the DS map that is being copied to is not empty, then this function will clear it first before copying. The original DS map remains unchanged by this process.

    +

    +

    Syntax:

    +

    ds_map_copy(id, source);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idThe handle of the map you are copying to
    sourceThe handle of the map you are copying from
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    inventory_2 = ds_map_create(); +
    + ds_map_copy(inventory_2, inventory_1);

    +

    The above code will create a new map and assign it to the variable "inventory_2". It will then copy the contents of the DS map indexed in the variable "inventory_1" to this new map.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - - \ No newline at end of file +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_delete.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_delete.htm index 50f094e10..f1799047c 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_delete.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_delete.htm @@ -1,67 +1,64 @@ - + - - - ds_map_delete - - - - - - - - - - -

    ds_map_delete

    -

    With this function you can remove any given key (and its corresponding value) from the given, previously created, DS map .

    -

     

    -

    Syntax:

    -

    ds_map_delete(id, key);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Map IDThe id of the map to change.
    keyStringThe key to delete (along with its associated value).
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    ds_map_delete(inventory, "shield");

    -

    The above code will delete the key "shield" (and the value it is paired with) from the DS map (inventory).

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_delete + + + + + + + + + +

    ds_map_delete

    +

    With this function you can remove any given key (and its corresponding value) from the given, previously created, DS map .

    +

    +

    Syntax:

    +

    ds_map_delete(id, key);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Map IDThe handle of the map to change.
    keyStringThe key to delete (along with its associated value).
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    ds_map_delete(inventory, "shield");

    +

    The above code will delete the key "shield" (and the value it is paired with) from the DS map (inventory).

    +

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_destroy.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_destroy.htm index 4ad41e3b7..36bf396df 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_destroy.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_destroy.htm @@ -1,64 +1,62 @@ - + - - - ds_map_destroy - - - - - - - - - - -

    ds_map_destroy

    -

    DS maps take up space in memory, which is allocated to them when they are created. This means that you also need to free this memory when the DS map is not needed to prevent errors, memory leaks and loss of performance when running your game. This function does just that.

    -

     Destroying a map will de-reference any data structures stored in the map giving a memory leak, so you would need to go through the map and destroy all data structure items manually before destroying it to prevent this. The only time this is not required is when you have flagged any items in the map as a DS list or as another DS map, in which case these items will be destroyed and their memory cleaned up automatically as well.

    -
    -

     

    -

    Syntax:

    -

    ds_map_destroy(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS MapThe id of the map to destroy.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    ds_map_destroy(inventory);
    - inventory = -1;

    -

    The above code will destroy the DS map referenced in the variable inventory.

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_destroy + + + + + + + + + +

    ds_map_destroy

    +

    DS maps take up space in memory, which is allocated to them when they are created. This means that you also need to free this memory when the DS map is not needed to prevent errors, memory leaks and loss of performance when running your game. This function does just that.

    +

    Destroying a map will de-reference any data structures stored in the map giving a memory leak, so you would need to go through the map and destroy all data structure items manually before destroying it to prevent this. The only time this is not required is when you have flagged any items in the map as a DS list or as another DS map, in which case these items will be destroyed and their memory cleaned up automatically as well.

    +
    +

    +

    Syntax:

    +

    ds_map_destroy(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS MapThe handle of the map to destroy.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    ds_map_destroy(inventory); +
    + inventory = -1;

    +

    The above code will destroy the DS map referenced in the variable inventory.

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_empty.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_empty.htm index 8c95de0aa..ec6a902c8 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_empty.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_empty.htm @@ -1,64 +1,66 @@ - + - - - ds_map_empty - - - - - - - - - - - -

    ds_map_empty

    -

    This function will simply return false if the specified (previously created) DS map contains any key/value pairs, or true if it does not.

    -

     

    -

    Syntax:

    -

    ds_map_empty(id);

    - - - - - - - - - - - -
    ArgumentTypeDescription
    idThe id of the data structure to check.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    if (ds_map_empty(inventory))
    - {
    -     weight = 0;
    - }

    -

    The above code checks to see if the DS map indexed in the variable "inventory" has any key/value pairs and if it does not it sets the variable "weight" to 0.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_empty + + + + + + + + + + +

    ds_map_empty

    +

    This function will simply return false if the specified (previously created) DS map contains any key/value pairs, or true if it does not.

    +

    +

    Syntax:

    +

    ds_map_empty(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idThe handle of the data structure to check.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    if (ds_map_empty(inventory)) +
    + { +
    + weight = 0; +
    + }

    +

    The above code checks to see if the DS map indexed in the variable "inventory" has any key/value pairs and if it does not it sets the variable "weight" to 0.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_exists.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_exists.htm index f6da3258f..5526cab5e 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_exists.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_exists.htm @@ -1,71 +1,71 @@ - + - - - ds_map_exists - - - - - - - - - - - -

    ds_map_exists

    -

    This function will return true if the specified key exists in the (previously created) DS map , and false if it does not.

    -

     

    -

    Syntax:

    -

    ds_map_exists(id, key);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Map IDThe id of the data structure to check
    keyStringThe key to check for
    -

     

    -

    Returns:

    -

    Boolean

    -

     

    -

    Example:

    -

    if (!ds_map_exists(inventory, "potions"))
    - {
    -     ds_map_add(inventory, "potions", 1);
    - }

    -

    The above code will check the DS map indexed in the variable "inventory" for the key "potions" and if it doesn't exist it will add it to the map.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_exists + + + + + + + + + + +

    ds_map_exists

    +

    This function will return true if the specified key exists in the (previously created) DS map , and false if it does not.

    +

    +

    Syntax:

    +

    ds_map_exists(id, key);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Map IDThe handle of the data structure to check
    keyStringThe key to check for
    +

    +

    Returns:

    +

    Boolean

    +

    +

    Example:

    +

    if (!ds_map_exists(inventory, "potions")) +
    + { +
    + ds_map_add(inventory, "potions", 1); +
    + }

    +

    The above code will check the DS map indexed in the variable "inventory" for the key "potions" and if it doesn't exist it will add it to the map.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_find_first.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_find_first.htm index 6e3691aab..60b542a0c 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_find_first.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_find_first.htm @@ -1,71 +1,79 @@ - + - - - ds_map_find_first - - - - - - - - - - - -

    ds_map_find_first

    -

    This function returns the first key stored in the DS map. This is not the first key in the order you added them! DS maps are not stored in a linear form, for that use DS list, so all this does is find the first key as stored by the computer. This can be useful if your have to iterate through the DS map looking for something, but should be avoided if possible as it can be slow.

    -

    Note that this function will return undefined if the given DS map is empty.

    -

     

    -

    Syntax:

    -

    ds_map_find_first(id);

    - - - - - - - - - - - -
    ArgumentTypeDescription
    idThe id of the map to use.
    -

     

    -

    Returns:

    -

    Variable or undefined

    -

     

    -

    Example:

    -

    var size = ds_map_size(inventory) ;
    - var key = ds_map_find_first(inventory);
    - for (var i = 0; i < size; i++;)
    - {
    -     if (key != "gold")
    -     {
    -         key = ds_map_find_next(inventory, key);
    -     }
    -     else break;
    - }

    -

    The above code creates some temporary variables and then gets the DS map size and finds the first key as stored by the computer in the map. It then uses a for loop to iterate through the DS map looking for the key value "gold". If it finds it, it breaks out the loop.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_find_first + + + + + + + + + + +

    ds_map_find_first

    +

    This function returns the first key stored in the DS map. This is not the first key in the order you added them! DS maps are not stored in a linear form, for that use DS list, so all this does is find the first key as stored by the computer. This can be useful if your have to iterate through the DS map looking for something, but should be avoided if possible as it can be slow.

    +

    Note that this function will return undefined if the given DS map is empty.

    +

    +

    Syntax:

    +

    ds_map_find_first(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idThe handle of the map to use.
    +

    +

    Returns:

    +

    Variable or undefined

    +

    +

    Example:

    +

    var size = ds_map_size(inventory) ; +
    + var key = ds_map_find_first(inventory); +
    + for (var i = 0; i < size; i++;) +
    + { +
    + if (key != "gold") +
    + { +
    + key = ds_map_find_next(inventory, key); +
    + } +
    + else break; +
    + }

    +

    The above code creates some temporary variables and then gets the DS map size and finds the first key as stored by the computer in the map. It then uses a for loop to iterate through the DS map looking for the key value "gold". If it finds it, it breaks out the loop.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_find_last.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_find_last.htm index d1f649be9..0208a6ab3 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_find_last.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_find_last.htm @@ -1,71 +1,79 @@ - + - - - ds_map_find_last - - - - - - - - - - - -

    ds_map_find_last

    -

    This function returns the last key stored in the DS map. This is not the last key in the order that you have added them! DS maps are not stored in a linear form, for that use DS lists, so all this does is find the last key as stored by the computer. This can be useful if your have to iterate through the DS map looking for something, but should be avoided if possible as it can be slow.

    -

    Note that this function will return undefined if the given DS map is empty.

    -

     

    -

    Syntax:

    -

    ds_map_find_last(id);

    - - - - - - - - - - - -
    ArgumentTypeDescription
    idThe id of the map to use.
    -

     

    -

    Returns:

    -

    Variable or undefined

    -

     

    -

    Example:

    -

    var size = ds_map_size(inventory);
    - var key = ds_map_find_last(inventory);
    - for (var i = size; i > 0; i--;)
    - {
    -     if (key != "gold")
    -     {
    -         key = ds_map_find_previous(inventory, key);
    -     }
    -     else break;
    - }

    -

    The above code creates some temporary variables and then gets the DS map size and finds the last key as stored by the computer in the map. It then uses a for loop to iterate back through the DS map looking for the key value "gold". If it finds it, it breaks out the loop.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_find_last + + + + + + + + + + +

    ds_map_find_last

    +

    This function returns the last key stored in the DS map. This is not the last key in the order that you have added them! DS maps are not stored in a linear form, for that use DS lists, so all this does is find the last key as stored by the computer. This can be useful if your have to iterate through the DS map looking for something, but should be avoided if possible as it can be slow.

    +

    Note that this function will return undefined if the given DS map is empty.

    +

    +

    Syntax:

    +

    ds_map_find_last(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idThe handle of the map to use.
    +

    +

    Returns:

    +

    Variable or undefined

    +

    +

    Example:

    +

    var size = ds_map_size(inventory); +
    + var key = ds_map_find_last(inventory); +
    + for (var i = size; i > 0; i--;) +
    + { +
    + if (key != "gold") +
    + { +
    + key = ds_map_find_previous(inventory, key); +
    + } +
    + else break; +
    + }

    +

    The above code creates some temporary variables and then gets the DS map size and finds the last key as stored by the computer in the map. It then uses a for loop to iterate back through the DS map looking for the key value "gold". If it finds it, it breaks out the loop.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_find_next.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_find_next.htm index 376c9040d..cb8caf113 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_find_next.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_find_next.htm @@ -1,74 +1,83 @@ - + - - - ds_map_find_next - - - - - - - - - - - -

    ds_map_find_next

    -

    This function returns the next key stored in the DS map after the one specified in the function. This can be useful if your have to iterate through the DS map looking for something, but should be avoided if possible as it can be slow. If no such key exists then the function will return undefined. You should always check this using the is_undefined() function.

    -

     

    -

    Syntax:

    -

    ds_map_find_next(id, key);

    - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idThe id of the map to use.
    keyThe key to find the next one to.
    -

     

    -

    Returns:

    -

    Variable or undefined

    -

     

    -

    Example:

    -

    var size = ds_map_size(inventory);
    - var key = ds_map_find_first(inventory);
    - for (var i = 0; i < size; i++;)
    - {
    -     if (key != "gold")
    -     {
    -         key = ds_map_find_next(inventory, key);
    -     }
    -     else break;
    - }

    -

    The above code creates some temporary variables and then gets the DS map size and finds the first key as stored by the computer in the map. It then uses a for loop to iterate through the DS map looking for the key value "gold". If it finds it, it breaks out the loop.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_find_next + + + + + + + + + + +

    ds_map_find_next

    +

    This function returns the next key stored in the DS map after the one specified in the function. This can be useful if your have to iterate through the DS map looking for something, but should be avoided if possible as it can be slow. If no such key exists then the function will return undefined. You should always check this using the is_undefined() function.

    +

    +

    Syntax:

    +

    ds_map_find_next(id, key);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idThe handle of the map to use.
    keyThe key to find the next one to.
    +

    +

    Returns:

    +

    Variable or undefined

    +

    +

    Example:

    +

    var size = ds_map_size(inventory); +
    + var key = ds_map_find_first(inventory); +
    + for (var i = 0; i < size; i++;) +
    + { +
    + if (key != "gold") +
    + { +
    + key = ds_map_find_next(inventory, key); +
    + } +
    + else break; +
    + }

    +

    The above code creates some temporary variables and then gets the DS map size and finds the first key as stored by the computer in the map. It then uses a for loop to iterate through the DS map looking for the key value "gold". If it finds it, it breaks out the loop.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_find_previous.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_find_previous.htm index c648fcca5..3a48823fa 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_find_previous.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_find_previous.htm @@ -1,74 +1,83 @@ - + - - - ds_map_find_previous - - - - - - - - - - - -

    ds_map_find_previous

    -

    This function returns the previous key stored in the DS map before the one specified in the function. This can be useful if your have to iterate through the DS map looking for something, but should be avoided if possible as it can be slow. If no such key exists then the function will return undefined. You should always check this using the is_undefined() function.

    -

     

    -

    Syntax:

    -

    ds_map_find_previous(id, key);

    - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idThe id of the map to use.
    keyThe key to find the previous one to.
    -

     

    -

    Returns:

    -

    Variable or undefined

    -

     

    -

    Example:

    -

    var size = ds_map_size(inventory) - 1;
    - var key = ds_map_find_last(inventory);
    - for (var i = size; i > 0; i--;)
    - {
    -     if (key != "gold")
    -     {
    -         key = ds_map_find_previous(inventory, key);
    -     }
    -     else break;
    - }

    -

    The above code creates some temporary variables and then gets the ds_map size and finds the last key as stored by the computer in the map. It then uses a for loop to iterate back through the ds_map looking for the key value "gold". If it finds it, it breaks out the loop.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_find_previous + + + + + + + + + + +

    ds_map_find_previous

    +

    This function returns the previous key stored in the DS map before the one specified in the function. This can be useful if your have to iterate through the DS map looking for something, but should be avoided if possible as it can be slow. If no such key exists then the function will return undefined. You should always check this using the is_undefined() function.

    +

    +

    Syntax:

    +

    ds_map_find_previous(id, key);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idThe handle of the map to use.
    keyThe key to find the previous one to.
    +

    +

    Returns:

    +

    Variable or undefined

    +

    +

    Example:

    +

    var size = ds_map_size(inventory) - 1; +
    + var key = ds_map_find_last(inventory); +
    + for (var i = size; i > 0; i--;) +
    + { +
    + if (key != "gold") +
    + { +
    + key = ds_map_find_previous(inventory, key); +
    + } +
    + else break; +
    + }

    +

    The above code creates some temporary variables and then gets the ds_map size and finds the last key as stored by the computer in the map. It then uses a for loop to iterate back through the ds_map looking for the key value "gold". If it finds it, it breaks out the loop.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_find_value.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_find_value.htm index 70d6b18a2..97e4383b1 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_find_value.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_find_value.htm @@ -1,71 +1,68 @@ - + - - - ds_map_find_value - - - - - - - - - - - -

    ds_map_find_value

    -

    With this function you can get the value from a specified key. The input values of the function are the (previously created) DS map to use and the key to check for.

    -

     If no such key exists then the function will return undefined. You should always check this using the is_undefined() function.

    -

     

    -

    Syntax:

    -

    ds_map_find_value(id, key)

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Map IDThe id of the map to use.
    keyStringThe key to find.
    -

     

    -

    Returns:

    -

    Any or undefined

    -

     

    -

    Example:

    -

    amount = ds_map_find_value(inventory, "food");

    -

    Or, using the map accessor "?":

    -

    amount = inventory[? "food"];

    -

    The above code will get the value of the key "food" and store it in the variable "amount".

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_find_value + + + + + + + + + + +

    ds_map_find_value

    +

    With this function you can get the value from a specified key. The input values of the function are the (previously created) DS map to use and the key to check for.

    +

    If no such key exists then the function will return undefined. You should always check this using the is_undefined() function.

    +

    +

    Syntax:

    +

    ds_map_find_value(id, key)

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Map IDThe handle of the map to use.
    keyStringThe key to find.
    +

    +

    Returns:

    +

    Any or undefined

    +

    +

    Example:

    +

    amount = ds_map_find_value(inventory, "food");

    +

    Or, using the map accessor "?":

    +

    amount = inventory[? "food"];

    +

    The above code will get the value of the key "food" and store it in the variable "amount".

    +

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_is_list.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_is_list.htm index f623ca5b6..e75d87324 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_is_list.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_is_list.htm @@ -1,78 +1,85 @@ - + - - - ds_map_is_list - - - - - - - - - - - -

    ds_map_is_list

    -

    With this function you can check to see if a DS list is stored in the given map key. If the given key contains a DS list ID, then the function will return true otherwise it will return false.

    -

     This will only detect lists that were added using the ds_map_add_list function.

    -

     

    -

    Syntax:

    -

    ds_map_is_list(id, key)

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS MapThe ID of the map to use.
    keyStringThe key to check.
    -

     

    -

    Returns:

    -

    Boolean

    -

     

    -

    Example:

    -

    var size = ds_map_size(inventory);
    - var key = ds_map_find_first(inventory);
    - for (var i = 0; i < size; i++)
    - {
    -     if (ds_map_is_list(inventory, key))
    -     {
    -         ds_list_destroy(inventory[? key]);
    -     }
    -     key = ds_map_find_next(inventory);
    - }
    - ds_map_destroy(inventory);

    -

    The above code loops through a DS map and checks to see if any of the keys in it are for a DS list. If they are, then the DS list is destroyed, and the at the end of the loop the DS map is destroyed too.

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_is_list + + + + + + + + + + +

    ds_map_is_list

    +

    With this function you can check to see if a DS list is stored in the given map key. If the given key contains a DS list ID, then the function will return true otherwise it will return false.

    +

    This will only detect lists that were added using the ds_map_add_list function.

    +

    +

    Syntax:

    +

    ds_map_is_list(id, key)

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS MapThe handle of the map to use.
    keyStringThe key to check.
    +

    +

    Returns:

    +

    Boolean

    +

    +

    Example:

    +

    var size = ds_map_size(inventory); +
    + var key = ds_map_find_first(inventory); +
    + for (var i = 0; i < size; i++) +
    + { +
    + if (ds_map_is_list(inventory, key)) +
    + { +
    + ds_list_destroy(inventory[? key]); +
    + } +
    + key = ds_map_find_next(inventory); +
    + } +
    + ds_map_destroy(inventory);

    +

    The above code loops through a DS map and checks to see if any of the keys in it are for a DS list. If they are, then the DS list is destroyed, and the at the end of the loop the DS map is destroyed too.

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_is_map.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_is_map.htm index 962c2c23b..0cc1a781b 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_is_map.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_is_map.htm @@ -1,78 +1,85 @@ - + - - - ds_map_is_map - - - - - - - - - - - -

    ds_map_is_map

    -

    With this function you can check to see if a DS map is stored in the given map key. If the given key contains a DS map ID, then the function will return true otherwise it will return false.

    -

     This will only detect maps that were added using the ds_map_add_map function.

    -

     

    -

    Syntax:

    -

    ds_map_is_map(id, key)

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS MapThe ID of the map to use.
    keyStringThe key to replace.
    -

     

    -

    Returns:

    -

    Boolean

    -

     

    -

    Example:

    -

    var size = ds_map_size(inventory);
    - var key = ds_map_find_first(inventory);
    - for (var i = 0; i < size; i++)
    - {
    -     if (ds_map_is_map(inventory, key))
    -     {
    -         ds_map_destroy(inventory[? key]);
    -     }
    -     key = ds_map_find_next(inventory);
    - }
    - ds_map_destroy(inventory);

    -

    The above code loops through a DS map and checks to see if any of the keys within it are for other DS maps. If they are, then the stored DS map is destroyed, and the at the end of the loop the main DS map is destroyed too.

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_is_map + + + + + + + + + + +

    ds_map_is_map

    +

    With this function you can check to see if a DS map is stored in the given map key. If the given key contains a DS map ID, then the function will return true otherwise it will return false.

    +

    This will only detect maps that were added using the ds_map_add_map function.

    +

    +

    Syntax:

    +

    ds_map_is_map(id, key)

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS MapThe handle of the map to use.
    keyStringThe key to replace.
    +

    +

    Returns:

    +

    Boolean

    +

    +

    Example:

    +

    var size = ds_map_size(inventory); +
    + var key = ds_map_find_first(inventory); +
    + for (var i = 0; i < size; i++) +
    + { +
    + if (ds_map_is_map(inventory, key)) +
    + { +
    + ds_map_destroy(inventory[? key]); +
    + } +
    + key = ds_map_find_next(inventory); +
    + } +
    + ds_map_destroy(inventory);

    +

    The above code loops through a DS map and checks to see if any of the keys within it are for other DS maps. If they are, then the stored DS map is destroyed, and the at the end of the loop the main DS map is destroyed too.

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_keys_to_array.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_keys_to_array.htm index d2279eb21..6eaee39c5 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_keys_to_array.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_keys_to_array.htm @@ -1,67 +1,64 @@ - + - - - ds_map_keys_to_array - - - - - - - - - - - -

    ds_map_keys_to_array

    -

    With this function you can retrieve all of the keys that a DS map contains. You supply the DS map ID to get the keys from (as returned by ds_map_create()) and the function will return an array where each entry in the array is a key from the DS map. The function has an optional second argument where you can supply an array that you have created, in which case the map key data will be appended onto any existing data in the array. Note that the function will modify the array supplied directly, but will also return a reference to it (or a reference to a new array if none is supplied).

    -

     

    -

    Syntax:

    -

    ds_map_keys_to_array(id, [array])

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Map IDThe id of the map to use.
    [array]ArrayOPTIONAL The array to append the DS map keys to.
    -

     

    -

    Returns:

    -

    Array

    -

     

    -

    Example:

    -

    map_keys = ds_map_keys_to_array(inventory);

    -

    The above code retrieves the keys for a DS map and then stores them as an array for future use.

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_keys_to_array + + + + + + + + + + +

    ds_map_keys_to_array

    +

    With this function you can retrieve all of the keys that a DS map contains. You supply the DS map ID to get the keys from (as returned by ds_map_create()) and the function will return an array where each entry in the array is a key from the DS map. The function has an optional second argument where you can supply an array that you have created, in which case the map key data will be appended onto any existing data in the array. Note that the function will modify the array supplied directly, but will also return a reference to it (or a reference to a new array if none is supplied).

    +

    +

    Syntax:

    +

    ds_map_keys_to_array(id, [array])

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Map IDThe handle of the map to use.
    [array]ArrayOPTIONAL The array to append the DS map keys to.
    +

    +

    Returns:

    +

    Array

    +

    +

    Example:

    +

    map_keys = ds_map_keys_to_array(inventory);

    +

    The above code retrieves the keys for a DS map and then stores them as an array for future use.

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_read.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_read.htm index 6eb304d13..6a22fc88f 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_read.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_read.htm @@ -1,80 +1,84 @@ - + - - - ds_map_read - - - - - - - - - - -

    ds_map_read

    -

    This function will take a string that has previously been created by the function ds_map_write() and then read it into a previously created DS map. If the map that the string is being read into contains any key/value pairs, these will be cleared first before the saved map is re-constructed.

    -

    Note that if the specified DS string was written by the GameMaker: Studio 1.2.x runtime (or older), you should specify the optional argument "legacy", setting it to true as the string format changed after that.

    -

     

    -

    Syntax:

    -

    ds_map_read(id, str, [legacy]);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Map IDThe id of the data structure to read the string into
    strStringThe string to read
    legacyBooleanOPTIONAL Can be either true or false or omitted completely.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    inventory = ds_map_create();
    - ini_open("map.ini");
    - var t_string = ini_read_string("Saved", "0", "");
    - if (t_string != "")
    - {
    -     ds_map_read(inventory, t_string);
    - }
    - ini_close();

    -

    The above code creates a new DS map and stores its id index in the variable "inventory". It then opens an ini file and reads a string from that file into the temporary variable "t_string". Finally, it checks to make sure that the string is valid (not the default ini value of "") and if it is it then reads the string into the newly created DS map before closing the ini again.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_read + + + + + + + + + +

    ds_map_read

    +

    This function will take a string that has previously been created by the function ds_map_write() and then read it into a previously created DS map. If the map that the string is being read into contains any key/value pairs, these will be cleared first before the saved map is re-constructed.

    +

    Note that if the specified DS string was written by the GameMaker: Studio 1.2.x runtime (or older), you should specify the optional argument "legacy", setting it to true as the string format changed after that.

    +

    +

    Syntax:

    +

    ds_map_read(id, str, [legacy]);

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Map IDThe handle of the data structure to read the string into
    strStringThe string to read
    legacyBooleanOPTIONAL Can be either true or false or omitted completely.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    inventory = ds_map_create(); +
    + ini_open("map.ini"); +
    + var t_string = ini_read_string("Saved", "0", ""); +
    + if (t_string != "") +
    + { +
    + ds_map_read(inventory, t_string); +
    + } +
    + ini_close();

    +

    The above code creates a new DS map and stores its id index in the variable "inventory". It then opens an ini file and reads a string from that file into the temporary variable "t_string". Finally, it checks to make sure that the string is valid (not the default ini value of "") and if it is it then reads the string into the newly created DS map before closing the ini again.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_replace.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_replace.htm index e55f47f59..9a88e7a0d 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_replace.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_replace.htm @@ -1,72 +1,69 @@ - + - - - ds_map_replace - - - - - - - - - - -

    ds_map_replace

    -

    With this function you can change the value for the given key within the a DS map. You supply the index to the map (as returned by the function ds_map_create()) and then the key to replace - either a string or an integer - and the value to replace the key value with. If the given key does not exist then it will be created for you, and if it does then the current value will be replaced with the new value. The function will return true if the key exists and the value is replaced, and false if the key does not exist and a new key was created with the value.

    -

     

    -

    Syntax:

    -

    ds_map_replace( id, key, val );

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS MapThe id of the map to change.
    keyStringThe key with the value that should be replaced by the new one
    valAnyThe new value to replace the given value with
    -

     

    -

    Returns:

    -

    Boolean

    -

     

    -

    Example:

    -

    ds_map_replace(inventory, "torso", 55);

    -

    The above code looks up the DS map for the key "torso" and when it finds it (or it is created if it doesn't exist) the current value is replaced with the one specified.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_replace + + + + + + + + + +

    ds_map_replace

    +

    With this function you can change the value for the given key within the a DS map. You supply the index to the map (as returned by the function ds_map_create()) and then the key to replace - either a string or an integer - and the value to replace the key value with. If the given key does not exist then it will be created for you, and if it does then the current value will be replaced with the new value. The function will return true if the key exists and the value is replaced, and false if the key does not exist and a new key was created with the value.

    +

    +

    Syntax:

    +

    ds_map_replace( id, key, val );

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS MapThe handle of the map to change.
    keyStringThe key with the value that should be replaced by the new one
    valAnyThe new value to replace the given value with
    +

    +

    Returns:

    +

    Boolean

    +

    +

    Example:

    +

    ds_map_replace(inventory, "torso", 55);

    +

    The above code looks up the DS map for the key "torso" and when it finds it (or it is created if it doesn't exist) the current value is replaced with the one specified.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_replace_list.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_replace_list.htm index c5126569a..6a7f6f955 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_replace_list.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_replace_list.htm @@ -1,78 +1,81 @@ - + - - - ds_map_replace_list - - - - - - - - - - -

    ds_map_replace_list

    -

    With this function you can replace a DS list that has been stored in the given "key" with another list that has been created previously.

    -

    This function is designed for creating JSON compatible maps which you would then encode using json_encode and should only be used in conjunction with that functionality.

    -

     

    -

    Syntax:

    -

    ds_map_replace_list(id, key, value)

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS MapThe ID of the map to use.
    keyStringThe key to replace.
    valueDS ListThe ID of the DS list to use to replace the one previously stored in the given key.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    var j_list = ds_list_create();
    - ds_list_add(j_list, health);
    - ds_list_add(j_list, lives);
    - ds_list_add(j_list, score);
    - ds_map_replace_list(j_map, "list", j_list);
    - var j = json_encode(j_map);
    - ds_list_destroy(j_list);

    -

    The above code will create a DS List and populate it with the values of various global variables before replacing a previously stored list in the DS Map j_map.

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_replace_list + + + + + + + + + +

    ds_map_replace_list

    +

    With this function you can replace a DS list that has been stored in the given "key" with another list that has been created previously.

    +

    This function is designed for creating JSON compatible maps which you would then encode using json_encode and should only be used in conjunction with that functionality.

    +

    +

    Syntax:

    +

    ds_map_replace_list(id, key, value)

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS MapThe handle of the map to use.
    keyStringThe key to replace.
    valueDS ListThe handle of the DS list to use to replace the one previously stored in the given key.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    var j_list = ds_list_create(); +
    + ds_list_add(j_list, health); +
    + ds_list_add(j_list, lives); +
    + ds_list_add(j_list, score); +
    + ds_map_replace_list(j_map, "list", j_list); +
    + var j = json_encode(j_map); +
    + ds_list_destroy(j_list);

    +

    The above code will create a DS List and populate it with the values of various global variables before replacing a previously stored list in the DS Map j_map.

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_replace_map.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_replace_map.htm index 71ce64552..008540252 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_replace_map.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_replace_map.htm @@ -1,77 +1,79 @@ - + - - - ds_map_replace_map - - - - - - - - - - -

    ds_map_replace_map

    -

    With this function you can replace a DS Map that has been stored in the given key with another map that has been created previously.

    -

    This function is designed for creating JSON compatible maps which you would then encode using json_encode and should only be used in conjunction with that functionality.

    -

     

    -

    Syntax:

    -

    ds_map_replace_map(id, key, value)

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS MapThe ID of the DS map to use.
    keyStringThe key to replace.
    valueDS MapThe ID of the DS map to use to replace the one previously stored in the given key.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    var temp_map = ds_map_create();
    - ds_map_add_list(temp_map, "list", j_list);
    - ds_map_add(temp_map, "array", j_array);
    - ds_map_replace_map(j_map, "maps", temp_map);
    - var j = json_encode(j_map);
    - ds_map_destroy(temp_map);

    -

    The above code will create a DS Map and populate it with an array and a DS List before replacing a previously stored map in the DS Map j_map.

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_replace_map + + + + + + + + + +

    ds_map_replace_map

    +

    With this function you can replace a DS Map that has been stored in the given key with another map that has been created previously.

    +

    This function is designed for creating JSON compatible maps which you would then encode using json_encode and should only be used in conjunction with that functionality.

    +

    +

    Syntax:

    +

    ds_map_replace_map(id, key, value)

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS MapThe handle of the DS map to use.
    keyStringThe key to replace.
    valueDS MapThe handle of the DS map to use to replace the one previously stored in the given key.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    var temp_map = ds_map_create(); +
    + ds_map_add_list(temp_map, "list", j_list); +
    + ds_map_add(temp_map, "array", j_array); +
    + ds_map_replace_map(j_map, "maps", temp_map); +
    + var j = json_encode(j_map); +
    + ds_map_destroy(temp_map);

    +

    The above code will create a DS Map and populate it with an array and a DS List before replacing a previously stored map in the DS Map j_map.

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_secure_load.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_secure_load.htm index 973bf972a..917677304 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_secure_load.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_secure_load.htm @@ -4,7 +4,7 @@ ds_map_secure_load - + @@ -15,7 +15,7 @@

    ds_map_secure_load

    -

    This function will load a previously saved DS map from the given file. This file must have been previously created using the ds_map_secure_save function, and, when loaded, the function will return the index of the DS map that has been created from the loaded data. This DS map index should be stored in a variable and used for all further function calls to this map. Note that if the DS map being loaded was saved with an array as one of the key values, this array will have been converted into a DS list on load.

    +

    This function will load a previously saved DS map from the given file. This file must have been previously created using the ds_map_secure_save function, and, when loaded, the function will return the handle of the DS map that has been created from the loaded data. This DS map handle should be stored in a variable and used for all further function calls to this map. Note that if the DS map being loaded was saved with an array as one of the key values, this array will have been converted into a DS list on load.

     One of the features of a secure saved file is that it is locked to the device that it was created on, so you cannot load a file saved on one device into a project running on another device.

     

    Syntax:

    @@ -29,14 +29,14 @@

    Syntax:

    filename - String + String The name of the file to load the map data from.

     

    Returns:

    -

    DS Map ID

    +

    DS Map

     

    Example:

    p_map = ds_map_secure_load("p_data.dat");

    @@ -50,7 +50,7 @@

    Example:

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

    ds_map_secure_save

    -

    This function will save the contents of the given DS map to a file that is linked to the device it was created on (meaning it can't be read if transferred to any other device). The file itself can have almost any extension (for example, *.dat, - *.json, *.bin, etc...) and will be obfuscated and stored to local storage on the target platform. You can then re-load the ds_map using the function ds_map_secure_load(). Note that if - the DS map being saved contains an array, this array will be converted into a DS list instead when saved.

    -

    IMPORTANT! One of the features of a secure saved file is that it is locked to the device that it was created on, so you cannot load a file saved on one device into a project running on another device.

    -

     

    -

    Syntax:

    -

    ds_map_secure_save(map, filename);

    - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    mapThe id of the data structure to use
    filenameThe name of the file to save the map to
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    ds_map_secure_save(purchase_map, "p_data.dat");

    -

    The above code will save the DS map indexed in the variable "p_data" to the given file for later retrieval.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + + ds_map_secure_save + + + + + + + + + +

    ds_map_secure_save

    +

    This function will save the contents of the given DS map to a file that is linked to the device it was created on (meaning it can't be read if transferred to any other device). The file itself can have almost any extension (for example, *.dat, *.json, *.bin, etc...) and will be obfuscated and stored to local storage on the target platform. You can then re-load the ds_map using the function ds_map_secure_load(). Note that if the DS map being saved contains an array, this array will be converted into a DS list instead when saved.

    +

    IMPORTANT! One of the features of a secure saved file is that it is locked to the device that it was created on, so you cannot load a file saved on one device into a project running on another device.

    +

    +

    Syntax:

    +

    ds_map_secure_save(map, filename);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    mapThe handle of the data structure to use
    filenameThe name of the file to save the map to
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    ds_map_secure_save(purchase_map, "p_data.dat");

    +

    The above code will save the DS map indexed in the variable "p_data" to the given file for later retrieval.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - - \ No newline at end of file +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_secure_save_buffer.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_secure_save_buffer.htm index c502f148c..bf14af54c 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_secure_save_buffer.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_secure_save_buffer.htm @@ -15,7 +15,7 @@

    ds_map_secure_save_buffer

    -

    This function will save a previously created DS map to a buffer. You supply the DS map ID value (as returned by the function ds_map_create) and the buffer to write to (as returned by the function buffer_create). Note that if the DS map being saved contains an array, this will be converted into a DS list instead when saved.

    +

    This function will save a previously created DS map to a buffer. You supply the DS map handle (as returned by the function ds_map_create) and the buffer to write to (as returned by the function buffer_create). Note that if the DS map being saved contains an array, this will be converted into a DS list instead when saved.

     This function is not supported on HTML5.

    Usage Notes

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

    ds_map_set

    -

    This function sets the value of a key within a given DS map.

    -

    You supply the DS Map value (as returned by the function ds_map_create), then give the key you want to set and the value to set it to. If the given key does not exist then it will be created for you and set to the value.

    -

    You can also set a value in a map using the accessor "?", as shown below:

    -

    map[? 5] = undefined;
    - map[? "level"] = 1;
    - map[? 89.6] = "hello world";
    - map[? 5] = buffer_get_address(buff);

    -

    Since the function doesn't return anything, you can use the function ds_map_replace to check if the key value has been replaced or a new key has been created.

    -
    -

     This function is the same as using the DS map accessor to set/create a map key/value pair.

    -

     

    -

    Syntax:

    -

    ds_map_set(id, key, value)

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS MapThe id of the map to use.
    keyAnyThe key to set.
    valueAnyThe value to set the key to.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    struct_key = {a: 10, b: "Some text"};
    -
    - map_key_value_pairs = ds_map_create();
    - ds_map_set(map_key_value_pairs, "score", "the value belonging to the string key");
    - ds_map_set(map_key_value_pairs, 8, "The value belonging to the real number key");
    - ds_map_set(map_key_value_pairs, struct_key, "The value for the struct key");
    -
    - show_debug_message(map_key_value_pairs[? "score"]);
    - show_debug_message(map_key_value_pairs[? 8]);
    - show_debug_message(map_key_value_pairs[? struct_key]); -

    -

    The above code first creates a basic struct struct_key. It then creates a new DS map using ds_map_create and stores it in a variable map_key_value_pairs.

    -

    Next, three different keys in the DS map are set using ds_map_set, each having a different type: the first key is a string, the second a number and the last one a struct.

    -

    Finally, the three values are looked up using the DS map accessor ? and shown using show_debug_message.

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_set + + + + + + + + + +

    ds_map_set

    +

    This function sets the value of a key within a given DS map.

    +

    You supply the DS Map value (as returned by the function ds_map_create), then give the key you want to set and the value to set it to. If the given key does not exist then it will be created for you and set to the value.

    +

    You can also set a value in a map using the accessor "?", as shown below:

    +

    map[? 5] = undefined; +
    + map[? "level"] = 1; +
    + map[? 89.6] = "hello world"; +
    + map[? 5] = buffer_get_address(buff);

    +

    Since the function doesn't return anything, you can use the function ds_map_replace to check if the key value has been replaced or a new key has been created.

    +
    +

    This function is the same as using the DS map accessor to set/create a map key/value pair.

    +

    +

    Syntax:

    +

    ds_map_set(id, key, value)

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS MapThe handle of the map to use.
    keyAnyThe key to set.
    valueAnyThe value to set the key to.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    struct_key = {a: 10, b: "Some text"}; +
    +
    + map_key_value_pairs = ds_map_create(); +
    + ds_map_set(map_key_value_pairs, "score", "the value belonging to the string key"); +
    + ds_map_set(map_key_value_pairs, 8, "The value belonging to the real number key"); +
    + ds_map_set(map_key_value_pairs, struct_key, "The value for the struct key"); +
    +
    + show_debug_message(map_key_value_pairs[? "score"]); +
    + show_debug_message(map_key_value_pairs[? 8]); +
    + show_debug_message(map_key_value_pairs[? struct_key]);

    +

    The above code first creates a basic struct struct_key. It then creates a new DS map using ds_map_create and stores it in a variable map_key_value_pairs.

    +

    Next, three different keys in the DS map are set using ds_map_set, each having a different type: the first key is a string, the second a number and the last one a struct.

    +

    Finally, the three values are looked up using the DS map accessor ? and shown using show_debug_message.

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_size.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_size.htm index 8d1d4a7d2..4ed15234b 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_size.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_size.htm @@ -1,64 +1,66 @@ - + - - - ds_map_size - - - - - - - - - - - -

    ds_map_size

    -

    With this function you can find how many key/values pairs the (previously created) DS map contains.

    -

     

    -

    Syntax:

    -

    ds_map_size(id);

    - - - - - - - - - - - -
    ArgumentTypeDescription
    idThe id of the data structure to check.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    if (ds_map_size(inventory) > 49)
    - {
    -     full = true;
    - }

    -

    The above code will check the size of the DS map (ie: number of key/value pairs) and if it is greater than 49 it sets the variable "full" to true.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_size + + + + + + + + + + +

    ds_map_size

    +

    With this function you can find how many key/values pairs the (previously created) DS map contains.

    +

    +

    Syntax:

    +

    ds_map_size(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idThe handle of the data structure to check.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    if (ds_map_size(inventory) > 49) +
    + { +
    + full = true; +
    + }

    +

    The above code will check the size of the DS map (ie: number of key/value pairs) and if it is greater than 49 it sets the variable "full" to true.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_values_to_array.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_values_to_array.htm index d0fa4386f..46e23cbfd 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_values_to_array.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_values_to_array.htm @@ -1,78 +1,81 @@ - + - - - ds_map_values_to_array - - - - - - - - - - - -

    ds_map_values_to_array

    -

    With this function you can retrieve all of the values that a DS map contains for each key in the map. You supply the DS map ID to get the keys from (as returned by ds_map_create()) and the function will return an array where each entry in the array is a value from the DS map (for example, if the map has 10 keys, then an array of 10 entries will be returned with each entry corresponding to a value for a key). The function has an optional second argument where you can supply an array that you have created, in which case the map key value data will be appended onto any existing data in the array. Note that the function will modify the array supplied directly, but will also return a reference to it (or a reference to a new array if none is supplied).

    -

     

    -

    Syntax:

    -

    ds_map_values_to_array(id, [array])

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Map IDThe id of the map to use.
    [array]ArrayOPTIONAL The array to append the DS map values to.
    -

     

    -

    Returns:

    -

    Array

    -

     

    -

    Example:

    -

    var _values = ds_map_values_to_array(lvl_score);
    - var _total = 0;
    - var _length = array_length(_values);
    -
    - for (var i = 0; i < _length; i ++)
    - {
    -     _total += _values[i];
    - }
    -
    - draw_text(32, 32, "Total score for all levels: " + string(_total)); -

    -

    The above retrieves all the values from a DS map for each key in the map and stores them in a local variable as an array. It then loops through the array and adds each of the values to a local variable which is then used to display the total of all the values.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    -
    Next: ds_map_set
    + + + ds_map_values_to_array + + + + + + + + + + +

    ds_map_values_to_array

    +

    With this function you can retrieve all of the values that a DS map contains for each key in the map. You supply the DS map ID to get the keys from (as returned by ds_map_create()) and the function will return an array where each entry in the array is a value from the DS map (for example, if the map has 10 keys, then an array of 10 entries will be returned with each entry corresponding to a value for a key). The function has an optional second argument where you can supply an array that you have created, in which case the map key value data will be appended onto any existing data in the array. Note that the function will modify the array supplied directly, but will also return a reference to it (or a reference to a new array if none is supplied).

    +

    +

    Syntax:

    +

    ds_map_values_to_array(id, [array])

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Map IDThe handle of the map to use.
    [array]ArrayOPTIONAL The array to append the DS map values to.
    +

    +

    Returns:

    +

    Array

    +

    +

    Example:

    +

    var _values = ds_map_values_to_array(lvl_score); +
    + var _total = 0; +
    + var _length = array_length(_values); +
    +
    + for (var i = 0; i < _length; i ++) +
    + { +
    + _total += _values[i]; +
    + } +
    +
    + draw_text(32, 32, "Total score for all levels: " + string(_total));

    +

    The above retrieves all the values from a DS map for each key in the map and stores them in a local variable as an array. It then loops through the array and adds each of the values to a local variable which is then used to display the total of all the values.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_write.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_write.htm index b6d732b36..17f45c0c5 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_write.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_write.htm @@ -1,69 +1,70 @@ - + - - - ds_map_write - - - - - - - - - - - -

    ds_map_write

    -

    This function will turn the DS map data of the specified map into string format which can then be written to an *.ini or a *.txt file for easy storage. This string can then be later read back into a new ds_map using ds_map_read().

    -

    Within the DS map any Real, String and Array values (including arrays nested within arrays) will be stored into the string properly, however structs are not supported.

    -
    -

     

    -

    Syntax:

    -

    ds_map_write(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS MapThe id of the data structure to use
    -

     

    -

    Returns:

    -

    String

    -

     

    -

    Example:

    -

    ini_open("map.ini");
    - var t_string;
    - t_string = ds_map_write(inventory);
    - ini_write_string("Saved", "0", t_string);
    - ini_close();

    -

    The above code opens an ini file ready to be written to. It then uses ds_map_write() to generate a string which is stored in the temporary variable "t_string". Finally, it writes that string to the ini file before closing it.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Maps
    - + + + ds_map_write + + + + + + + + + + +

    ds_map_write

    +

    This function will turn the DS map data of the specified map into string format which can then be written to an *.ini or a *.txt file for easy storage. This string can then be later read back into a new ds_map using ds_map_read().

    +

    Within the DS map any Real, String and Array values (including arrays nested within arrays) will be stored into the string properly, however structs are not supported.

    +
    +

    +

    Syntax:

    +

    ds_map_write(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS MapThe handle of the data structure to use
    +

    +

    Returns:

    +

    String

    +

    +

    Example:

    +

    ini_open("map.ini"); +
    + var t_string; +
    + t_string = ds_map_write(inventory); +
    + ini_write_string("Saved", "0", t_string); +
    + ini_close();

    +

    The above code opens an ini file ready to be written to. It then uses ds_map_write() to generate a string which is stored in the temporary variable "t_string". Finally, it writes that string to the ini file before closing it.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Maps
    + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_add.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_add.htm index 6f66fcb6d..64ee01d64 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_add.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_add.htm @@ -1,72 +1,69 @@ - + - - - ds_priority_add - - - - - - - - - - -

    ds_priority_add

    -

    With this function you can add a value (either a real number or a string) to a priority queue, at the same time assigning it a priority value.

    -

     

    -

    Syntax:

    -

    ds_priority_add(id, val, priority);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Priority IDThe id of the priority queue to add to.
    valVariableThe value to add to the priority queue.
    priorityRealThe priority of the value to add.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    ds_priority_add(ai_priority, AI_Search, 5);

    -

    The above code adds a script function to the priority queue indexed in the variable "ai_priority" and assigns it a priority of 5.

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + ds_priority_add + + + + + + + + + +

    ds_priority_add

    +

    With this function you can add a value (either a real number or a string) to a priority queue, at the same time assigning it a priority value.

    +

    +

    Syntax:

    +

    ds_priority_add(id, val, priority);

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Priority IDThe handle of the priority queue to add to.
    valVariableThe value to add to the priority queue.
    priorityRealThe priority of the value to add.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    ds_priority_add(ai_priority, AI_Search, 5);

    +

    The above code adds a script function to the priority queue indexed in the variable "ai_priority" and assigns it a priority of 5.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_change_priority.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_change_priority.htm index 0399908b1..3dfbd0752 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_change_priority.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_change_priority.htm @@ -1,75 +1,75 @@ - + - - - ds_priority_change_priority - - - - - - - - - - -

    ds_priority_change_priority

    -

    This function will take a given value and change its priority within the referenced priority queue. The given value should already exist in the priority queue.

    -

     

    -

    Syntax:

    -

    ds_priority_change_priority(id, val, priority);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Priority IDThe id of the priority queue to change.
    valVariableThe value to change the priority of.
    priorityRealThe new priority of the value.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    if (global.Game_Time < 1000)
    - {
    -     ds_priority_change(ai_priority, AI_Search, 1);
    - }

    -

    The above code checks a global variable and if it is below a certain value it will then change the priority of the script function index held in the priority queue.

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + ds_priority_change_priority + + + + + + + + + +

    ds_priority_change_priority

    +

    This function will take a given value and change its priority within the referenced priority queue. The given value should already exist in the priority queue.

    +

    +

    Syntax:

    +

    ds_priority_change_priority(id, val, priority);

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Priority IDThe handle of the priority queue to change.
    valVariableThe value to change the priority of.
    priorityRealThe new priority of the value.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    if (global.Game_Time < 1000) +
    + { +
    + ds_priority_change(ai_priority, AI_Search, 1); +
    + }

    +

    The above code checks a global variable and if it is below a certain value it will then change the priority of the script function index held in the priority queue.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_clear.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_clear.htm index 80ab98ea7..a5a31d75b 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_clear.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_clear.htm @@ -1,66 +1,68 @@ - + - - - ds_priority_clear - - - - - - - - - - -

    ds_priority_clear

    -

    With this function you can clear all data from the given priority queue data-structure. This does NOT destroy the data-structure (for that you should use ds_priority_destroy()) it only wipes all data from it and returns an empty priority queue.

    -

     

    -

    Syntax:

    -

    ds_priority_clear(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Priority IDThe id of the data structure to clear.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    if (count = 15) && (!ds_priority_empty(command_queue))
    - {
    -     ds_priority_clear(command_queue);
    -     alarm[0] = game_get_speed(gamespeed_fps);
    -     ai_count = 0;
    - }

    -

    The above code checks a variable to see if it has reached a specific value and if it has it clears the DS priority queue indexed in the variable "command_queue", sets an alarm, and resets the variable to 0.

    -

     

    -

     

    -
    -
    -
    - - + + + ds_priority_clear + + + + + + + + + +

    ds_priority_clear

    +

    With this function you can clear all data from the given priority queue data-structure. This does NOT destroy the data-structure (for that you should use ds_priority_destroy()) it only wipes all data from it and returns an empty priority queue.

    +

    +

    Syntax:

    +

    ds_priority_clear(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Priority IDThe handle of the data structure to clear.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    if (count = 15) && (!ds_priority_empty(command_queue)) +
    + { +
    + ds_priority_clear(command_queue); +
    + alarm[0] = game_get_speed(gamespeed_fps); +
    + ai_count = 0; +
    + }

    +

    The above code checks a variable to see if it has reached a specific value and if it has it clears the DS priority queue indexed in the variable "command_queue", sets an alarm, and resets the variable to 0.

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_copy.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_copy.htm index d227a44cc..495600b9a 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_copy.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_copy.htm @@ -1,68 +1,72 @@ - + - - - ds_priority_copy - - - - - - - - - - -

    ds_priority_copy

    -

    This function can be used to copy the contents of one priority queue into another. Note that this does NOT remove the contents from the original priority queue, nor does it destroy the original priority queue. When using this function the priority queue being copied to must have been previously created and if it contained any items before the copy, then these will be cleared first (meaning this information will be lost).

    -

     

    -

    Syntax:

    -

    ds_priority_copy(id, source);

    - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idThe id of the priority queue to copy to.
    sourceThe id of the priority queue to copy from.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    with (instance_create_layer(x, y, "Enemies", obj_Enemy))
    - {
    -     p_queue = ds_priority_create();
    -     ds_priority_copy(p_queue, other.p_queue);
    - }

    -

    The above function creates a new instance and then in that instance it creates a new DS priority queue and copies the contents of the priority queue in the instance running the code block, into the newly created instance priority queue.

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + ds_priority_copy + + + + + + + + + +

    ds_priority_copy

    +

    This function can be used to copy the contents of one priority queue into another. Note that this does NOT remove the contents from the original priority queue, nor does it destroy the original priority queue. When using this function the priority queue being copied to must have been previously created and if it contained any items before the copy, then these will be cleared first (meaning this information will be lost).

    +

    +

    Syntax:

    +

    ds_priority_copy(id, source);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idThe handle of the priority queue to copy to.
    sourceThe handle of the priority queue to copy from.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    with (instance_create_layer(x, y, "Enemies", obj_Enemy)) +
    + { +
    + p_queue = ds_priority_create(); +
    + ds_priority_copy(p_queue, other.p_queue); +
    + }

    +

    The above function creates a new instance and then in that instance it creates a new DS priority queue and copies the contents of the priority queue in the instance running the code block, into the newly created instance priority queue.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_delete_max.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_delete_max.htm index b5c9ae369..bab493592 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_delete_max.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_delete_max.htm @@ -1,67 +1,67 @@ - + - - - ds_priority_delete_max - - - - - - - - - - - -

    ds_priority_delete_max

    -

    This function will return the value that has the highest priority in the queue and then remove the value (and priority) from the data structure. If more than one value has the same priority, then any one of them could be returned in any order, but all other values with the same priority will still be in the queue.

    -

     If the priority queue is empty, this function will return 0.

    -

     

    -

    Syntax:

    -

    ds_priority_delete_max(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Priority IDThe id of the priority queue to use.
    -

     

    -

    Returns:

    -

    Any (Data type stored in the priority)

    -

     

    -

    Example:

    -

    if (ai_move)
    - {
    -     script_execute(ds_priority_delete_max(ai_priority));
    - }

    -

    The above code checks an instance variable and if it returns true it will execute a script indexed in the priority queue with the highest priority value and then remove that script from the queue.

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + ds_priority_delete_max + + + + + + + + + + +

    ds_priority_delete_max

    +

    This function will return the value that has the highest priority in the queue and then remove the value (and priority) from the data structure. If more than one value has the same priority, then any one of them could be returned in any order, but all other values with the same priority will still be in the queue.

    +

    If the priority queue is empty, this function will return 0.

    +

    +

    Syntax:

    +

    ds_priority_delete_max(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Priority IDThe handle of the priority queue to use.
    +

    +

    Returns:

    +

    Any (Data type stored in the priority)

    +

    +

    Example:

    +

    if (ai_move) +
    + { +
    + script_execute(ds_priority_delete_max(ai_priority)); +
    + }

    +

    The above code checks an instance variable and if it returns true it will execute a script indexed in the priority queue with the highest priority value and then remove that script from the queue.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_delete_min.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_delete_min.htm index a31234f5f..a427db81f 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_delete_min.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_delete_min.htm @@ -1,67 +1,67 @@ - + - - - ds_priority_delete_min - - - - - - - - - - - -

    ds_priority_delete_min

    -

    This function will return the value that has the lowest priority in the queue and then remove the value (and priority) from the data structure. If more than one value has the same priority, then any one of them could be returned in any order, but all other values with the same priority will still be in the queue.

    -

     If the priority queue is empty, this function will return 0.

    -

     

    -

    Syntax:

    -

    ds_priority_delete_min(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Priority IDThe id of the priority queue to use.
    -

     

    -

    Returns:

    -

    Any (Data type stored in the priority)

    -

     

    -

    Example:

    -

    if (ai_move)
    - {
    -     script_execute(ds_priority_delete_min(ai_priority));
    - }

    -

    The above code checks an instance variable and if it returns true it will execute a script function indexed in the priority queue with the lowest priority value and then remove that script from the queue.

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + ds_priority_delete_min + + + + + + + + + + +

    ds_priority_delete_min

    +

    This function will return the value that has the lowest priority in the queue and then remove the value (and priority) from the data structure. If more than one value has the same priority, then any one of them could be returned in any order, but all other values with the same priority will still be in the queue.

    +

    If the priority queue is empty, this function will return 0.

    +

    +

    Syntax:

    +

    ds_priority_delete_min(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Priority IDThe handle of the priority queue to use.
    +

    +

    Returns:

    +

    Any (Data type stored in the priority)

    +

    +

    Example:

    +

    if (ai_move) +
    + { +
    + script_execute(ds_priority_delete_min(ai_priority)); +
    + }

    +

    The above code checks an instance variable and if it returns true it will execute a script function indexed in the priority queue with the lowest priority value and then remove that script from the queue.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_delete_value.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_delete_value.htm index 2a556acc9..6c1354092 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_delete_value.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_delete_value.htm @@ -1,67 +1,70 @@ - + - - - ds_priority_delete_value - - - - - - - - - - -

    ds_priority_delete_value

    -

    This function will simply delete the given value, along with its priority, from the indexed priority queue.

    -

     

    -

    Syntax:

    -

    ds_priority_delete_value(id,val);

    - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idThe id of the priority queue to use.
    valThe value to delete from the priority queue.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    if (ai_move == false)
    - {
    -     ds_priority_delete_value(ai_priority, AI_Move);
    - }

    -

    The above code checks an instance variable and if it returns false it will remove the indexed script function from the priority queue.

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + ds_priority_delete_value + + + + + + + + + +

    ds_priority_delete_value

    +

    This function will simply delete the given value, along with its priority, from the indexed priority queue.

    +

    +

    Syntax:

    +

    ds_priority_delete_value(id,val);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idThe handle of the priority queue to use.
    valThe value to delete from the priority queue.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    if (ai_move == false) +
    + { +
    + ds_priority_delete_value(ai_priority, AI_Move); +
    + }

    +

    The above code checks an instance variable and if it returns false it will remove the indexed script function from the priority queue.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_empty.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_empty.htm index bcb4c811c..dc6572393 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_empty.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_empty.htm @@ -1,67 +1,69 @@ - + - - - ds_priority_empty - - - - - - - - - - - -

    ds_priority_empty

    -

    With this function you can check the given DS priority queue to see if it is empty (returns true) or not (returns false).

    -

     

    -

    Syntax:

    -

    ds_priority_empty(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Priority IDThe id of the data structure to check.
    -

     

    -

    Returns:

    -

    Boolean

    -

     

    -

    Example:

    -

    if (count == 15) && (!ds_priority_empty(command_queue))
    - {
    -     ds_priority_clear(command_queue);
    -     alarm[0] = game_get_speed(gamespeed_fps);
    -     ai_count = 0;
    - }

    -

    The above code checks a variable to see if it has reached a specific value and if it has it clears the DS priority queue indexed in the variable "command_queue", sets an alarm, and resets the variable to 0.

    -

     

    -

     

    -
    -
    -
    - - + + + ds_priority_empty + + + + + + + + + + +

    ds_priority_empty

    +

    With this function you can check the given DS priority queue to see if it is empty (returns true) or not (returns false).

    +

    +

    Syntax:

    +

    ds_priority_empty(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Priority IDThe handle of the data structure to check.
    +

    +

    Returns:

    +

    Boolean

    +

    +

    Example:

    +

    if (count == 15) && (!ds_priority_empty(command_queue)) +
    + { +
    + ds_priority_clear(command_queue); +
    + alarm[0] = game_get_speed(gamespeed_fps); +
    + ai_count = 0; +
    + }

    +

    The above code checks a variable to see if it has reached a specific value and if it has it clears the DS priority queue indexed in the variable "command_queue", sets an alarm, and resets the variable to 0.

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_find_max.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_find_max.htm index f8cf4186f..d94fd868f 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_find_max.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_find_max.htm @@ -1,67 +1,67 @@ - + - - - ds_priority_find_max - - - - - - - - - - - -

    ds_priority_find_max

    -

    With this function you can find the value stored in the priority queue with the highest priority, and if more than one value has the same priority then any one of them could be returned in any order. However, unlike ds_priority_delete_max(), this function will not remove the value from the queue.

    -
    -

     

    -

    Syntax:

    -

    ds_priority_find_max(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Priority IDThe id of the priority queue to use.
    -

     

    -

    Returns:

    -

    Any (Data type stored in the priority)

    -

     

    -

    Example:

    -

    if (ai_move)
    - {
    -     script_execute(ds_priority_find_max(ai_priority));
    - }

    -

    The above code checks an instance variable and if it returns true it will execute a script function indexed in the priority queue with the highest priority value.

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + ds_priority_find_max + + + + + + + + + + +

    ds_priority_find_max

    +

    With this function you can find the value stored in the priority queue with the highest priority, and if more than one value has the same priority then any one of them could be returned in any order. However, unlike ds_priority_delete_max(), this function will not remove the value from the queue.

    +
    +

    +

    Syntax:

    +

    ds_priority_find_max(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Priority IDThe handle of the priority queue to use.
    +

    +

    Returns:

    +

    Any (Data type stored in the priority)

    +

    +

    Example:

    +

    if (ai_move) +
    + { +
    + script_execute(ds_priority_find_max(ai_priority)); +
    + }

    +

    The above code checks an instance variable and if it returns true it will execute a script function indexed in the priority queue with the highest priority value.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_find_min.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_find_min.htm index 6e224efb1..75d8e9f13 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_find_min.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_find_min.htm @@ -1,67 +1,67 @@ - + - - - ds_priority_find_min - - - - - - - - - - - -

    ds_priority_find_min

    -

    With this function you can find the value stored in the priority queue with the lowest priority, and if more than one value has the same priority then any one of them could be returned in any order. However, unlike ds_priority_delete_min(), this function will not remove the value from the queue.

    -
    -

     

    -

    Syntax:

    -

    ds_priority_find_min(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Priority IDThe id of the priority queue to use.
    -

     

    -

    Returns:

    -

    Any (Data type stored in the priority)

    -

     

    -

    Example:

    -

    if (ai_move)
    - {
    -     script_execute(ds_priority_find_min(ai_priority));
    - }

    -

    The above code checks an instance variable and if it returns true it will execute a script function indexed in the priority queue with the lowest priority value.

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + ds_priority_find_min + + + + + + + + + + +

    ds_priority_find_min

    +

    With this function you can find the value stored in the priority queue with the lowest priority, and if more than one value has the same priority then any one of them could be returned in any order. However, unlike ds_priority_delete_min(), this function will not remove the value from the queue.

    +
    +

    +

    Syntax:

    +

    ds_priority_find_min(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Priority IDThe handle of the priority queue to use.
    +

    +

    Returns:

    +

    Any (Data type stored in the priority)

    +

    +

    Example:

    +

    if (ai_move) +
    + { +
    + script_execute(ds_priority_find_min(ai_priority)); +
    + }

    +

    The above code checks an instance variable and if it returns true it will execute a script function indexed in the priority queue with the lowest priority value.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_find_priority.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_find_priority.htm index 1822b6d60..2fe38257a 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_find_priority.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_find_priority.htm @@ -1,70 +1,67 @@ - + - - - ds_priority_find_priority - - - - - - - - - - - -

    ds_priority_find_priority

    -

    With this function you can retrieve the priority of any given value. If the value does not exist in the priority queue then undefined will be returned.

    -

     

    -

    Syntax:

    -

    ds_priority_find_priority(id, val);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Priority IDThe id of the priority queue to use.
    valAnyThe value to find the priority of.
    -

     

    -

    Returns:

    -

    Real or undefined

    -

     

    -

     

    -

     

    -

    Example:

    -

    p = ds_priority_find_priority(ai_priority, "intelligence");

    -

    The above code will store the returned priority for the given value in the instance variable "p".

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + ds_priority_find_priority + + + + + + + + + + +

    ds_priority_find_priority

    +

    With this function you can retrieve the priority of any given value. If the value does not exist in the priority queue then undefined will be returned.

    +

    +

    Syntax:

    +

    ds_priority_find_priority(id, val);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Priority IDThe handle of the priority queue to use.
    valAnyThe value to find the priority of.
    +

    +

    Returns:

    +

    Real or undefined

    +

    +

    +

    +

    Example:

    +

    p = ds_priority_find_priority(ai_priority, "intelligence");

    +

    The above code will store the returned priority for the given value in the instance variable "p".

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_read.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_read.htm index 59863b72a..345674f7d 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_read.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_read.htm @@ -1,80 +1,84 @@ - + - - - ds_priority_read - - - - - - - - - - -

    ds_priority_read

    -

    With this function you can recreate a saved DS priority (one that has previously been written as a string using ds_priority_write()). You must first create a new DS priority to read the string into, and if the DS priority already exists and has information stored in it, then this will be cleared before reading. This function is of vital importance when creating save/load mechanisms for your game.

    -

    Note that if the specified DS string was written by the GameMaker: Studio 1.2.x runtime (or older), you should specify the optional argument "legacy", setting it to true as the string format changed after that.

    -

     

    -

    Syntax:

    -

    ds_priority_read(id, str, [legacy]);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Priority IDThe id of the data structure to write.
    strStringThe string to read from.
    legacyBooleanOPTIONAL Can be either true or false or omitted completely.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    p_queue = ds_priority_create();
    - ini_open("save.ini");
    - var str = ini_read_string("P_Queues", "0", "");
    - if (str != "")
    - {
    -     ds_priority_read(p_queue, str);
    - }
    - ini_close();

    -

    The above code creates a priority queue and stores the index in the variable "p_queue". It then opens an ini file and reads a string from that, checking to make sure that the string is not returned as empty first. This string is then read into the newly created DS priority.

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + ds_priority_read + + + + + + + + + +

    ds_priority_read

    +

    With this function you can recreate a saved DS priority (one that has previously been written as a string using ds_priority_write()). You must first create a new DS priority to read the string into, and if the DS priority already exists and has information stored in it, then this will be cleared before reading. This function is of vital importance when creating save/load mechanisms for your game.

    +

    Note that if the specified DS string was written by the GameMaker: Studio 1.2.x runtime (or older), you should specify the optional argument "legacy", setting it to true as the string format changed after that.

    +

    +

    Syntax:

    +

    ds_priority_read(id, str, [legacy]);

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Priority IDThe handle of the data structure to write.
    strStringThe string to read from.
    legacyBooleanOPTIONAL Can be either true or false or omitted completely.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    p_queue = ds_priority_create(); +
    + ini_open("save.ini"); +
    + var str = ini_read_string("P_Queues", "0", ""); +
    + if (str != "") +
    + { +
    + ds_priority_read(p_queue, str); +
    + } +
    + ini_close();

    +

    The above code creates a priority queue and stores the index in the variable "p_queue". It then opens an ini file and reads a string from that, checking to make sure that the string is not returned as empty first. This string is then read into the newly created DS priority.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_size.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_size.htm index 1e664c226..693ad41b7 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_size.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_size.htm @@ -1,64 +1,66 @@ - + - - - ds_priority_size - - - - - - - - - - - -

    ds_priority_size

    -

    This function will return the "size" of the priority queue, ie: the number of items that have been prioritized in it.

    -

     

    -

    Syntax:

    -

    ds_priority_size(id);

    - - - - - - - - - - - -
    ArgumentTypeDescription
    idThe id of the data structure to check.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    if (!ds_priority_empty(control_priority))
    - {
    -     num = ds_priority_size(control_priority);
    - }

    -

    The above code checks a DS priority queue to see if it is empty or not, and if it is not, it gets the number of items that it contains and stores the value in a variable.

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + ds_priority_size + + + + + + + + + + +

    ds_priority_size

    +

    This function will return the "size" of the priority queue, ie: the number of items that have been prioritized in it.

    +

    +

    Syntax:

    +

    ds_priority_size(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idThe handle of the data structure to check.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    if (!ds_priority_empty(control_priority)) +
    + { +
    + num = ds_priority_size(control_priority); +
    + }

    +

    The above code checks a DS priority queue to see if it is empty or not, and if it is not, it gets the number of items that it contains and stores the value in a variable.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_write.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_write.htm index f5025f5a1..3bb477a39 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_write.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_write.htm @@ -1,69 +1,71 @@ - + - - - ds_priority_write - - - - - - - - - - - -

    ds_priority_write

    -

    This function returns a string which can then be stored or transferred to another data structure using the ds_priority_read() function.

    -
    -

     

    -

    Syntax:

    -

    ds_priority_write(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Priority IDThe id of the data structure to check.
    -

     

    -

    Returns:

    -

    String

    -

     

    -

    Example:

    -

    var str;
    - ini_open("save.ini");
    - str = ds_priority_write(p_queue);
    - ini_write_string("P_Queues", "0", str);
    - ds_priority_clear(p_queue);
    - ini_close();

    -

    The above code opens an ini file and then writes a string containing the information stored in the DS priority queue indexed in the variable "p_queue". The priority queue is then cleared and the ini file closed.

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + ds_priority_write + + + + + + + + + + +

    ds_priority_write

    +

    This function returns a string which can then be stored or transferred to another data structure using the ds_priority_read() function.

    +
    +

    +

    Syntax:

    +

    ds_priority_write(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Priority IDThe handle of the data structure to check.
    +

    +

    Returns:

    +

    String

    +

    +

    Example:

    +

    var str; +
    + ini_open("save.ini"); +
    + str = ds_priority_write(p_queue); +
    + ini_write_string("P_Queues", "0", str); +
    + ds_priority_clear(p_queue); +
    + ini_close();

    +

    The above code opens an ini file and then writes a string containing the information stored in the DS priority queue indexed in the variable "p_queue". The priority queue is then cleared and the ini file closed.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_clear.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_clear.htm index 93f9b967e..21f226c2e 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_clear.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_clear.htm @@ -1,67 +1,69 @@ - + - - - ds_queue_clear - - - - - - - - - - -

    ds_queue_clear

    -

    With this function you can clear all data from the given queue data-structure. This does NOT destroy the data-structure (for that you should use ds_queue_destroy()) it only wipes all data from it and returns an empty queue.

    -

     

    -

    Syntax:

    -

    ds_queue_clear(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Queue IDThe id of the data structure to clear.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    if (count = 15) && (!ds_queue_empty(command_queue))
    - {
    -     ds_queue_clear(command_queue);
    -     alarm[0] = game_get_speed(gamespeed_fps);
    -     ai_count = 0;
    - }

    -

    The above code checks a variable to see if it has reached a specific value and if it has it clears the DS queue indexed in the variable "command_queue", sets an alarm, and resets the variable to 0.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Queues
    - + + + ds_queue_clear + + + + + + + + + +

    ds_queue_clear

    +

    With this function you can clear all data from the given queue data-structure. This does NOT destroy the data-structure (for that you should use ds_queue_destroy()) it only wipes all data from it and returns an empty queue.

    +

    +

    Syntax:

    +

    ds_queue_clear(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Queue IDThe handle of the data structure to clear.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    if (count = 15) && (!ds_queue_empty(command_queue)) +
    + { +
    + ds_queue_clear(command_queue); +
    + alarm[0] = game_get_speed(gamespeed_fps); +
    + ai_count = 0; +
    + }

    +

    The above code checks a variable to see if it has reached a specific value and if it has it clears the DS queue indexed in the variable "command_queue", sets an alarm, and resets the variable to 0.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Queues
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_copy.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_copy.htm index 33254e889..36458dc51 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_copy.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_copy.htm @@ -1,71 +1,72 @@ - + - - - ds_queue_copy - - - - - - - - - - -

    ds_queue_copy

    -

    This function can be used to copy the contents of one queue into another. Note that this does NOT remove the contents from the original queue, nor does it destroy the original queue. When using this function the queue being copied to must have been previously created and if it contained any items before the copy, then these will be cleared first (meaning this information will be lost).

    -

     

    -

    Syntax:

    -

    ds_queue_copy(id, source);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Queue IDThe id of the new queue.
    sourceDS Queue IDThe original queue to copy from.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    with (instance_create_layer(x, y, "Enemies", obj_Enemy))
    - {
    -     queue = ds_queue_create();
    -     ds_queue_copy(queue, other.queue);
    - }

    -

    The above function creates a new instance and then in that instance it creates a new DS queue and copies the contents of the queue in the instance running the code block, into the newly created instance queue.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Queues
    - + + + ds_queue_copy + + + + + + + + + +

    ds_queue_copy

    +

    This function can be used to copy the contents of one queue into another. Note that this does NOT remove the contents from the original queue, nor does it destroy the original queue. When using this function the queue being copied to must have been previously created and if it contained any items before the copy, then these will be cleared first (meaning this information will be lost).

    +

    +

    Syntax:

    +

    ds_queue_copy(id, source);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Queue IDThe handle of the new queue.
    sourceDS Queue IDThe original queue to copy from.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    with (instance_create_layer(x, y, "Enemies", obj_Enemy)) +
    + { +
    + queue = ds_queue_create(); +
    + ds_queue_copy(queue, other.queue); +
    + }

    +

    The above function creates a new instance and then in that instance it creates a new DS queue and copies the contents of the queue in the instance running the code block, into the newly created instance queue.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Queues
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_dequeue.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_dequeue.htm index f897e6461..422f7ae1d 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_dequeue.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_dequeue.htm @@ -1,66 +1,70 @@ - + - - - ds_queue_dequeue - - - - - - - - - - -

    ds_queue_dequeue

    -

    This function will dequeue the head value off of the DS queue, removing it from the queue and returning the value to be stored in a variable. If the queue is empty then the function will return the constant undefined, otherwise it will return the value contained in the queue.

    -

     

    -

    Syntax:

    -

    ds_queue_dequeue(id);

    - - - - - - - - - - - -
    ArgumentTypeDescription
    idThe id of the queue to dequeue from.
    -

     

    -

     

    -

    Returns:

    -

    Variable (Data type value stored in the queue) or undefined

    -

     

    -

    Example:

    -

    if (!ds_queue_empty(move_queue))
    - {
    -     var xx = ds_queue_dequeue(move_queue);
    -     var yy = ds_queue_dequeue(move_queue);
    -     move_towards_point(xx, yy, 4);
    - }

    -

    The above code checks the DS queue indexed in the variable "move_queue" to see if it is empty, and if it is not, it then dequeues the two values from the head of the queue and use them to set a direction for movement.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Queues
    - + + + ds_queue_dequeue + + + + + + + + + +

    ds_queue_dequeue

    +

    This function will dequeue the head value off of the DS queue, removing it from the queue and returning the value to be stored in a variable. If the queue is empty then the function will return the constant undefined, otherwise it will return the value contained in the queue.

    +

    +

    Syntax:

    +

    ds_queue_dequeue(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idThe handle of the queue to dequeue from.
    +

    +

    +

    Returns:

    +

    Variable (Data type value stored in the queue) or undefined

    +

    +

    Example:

    +

    if (!ds_queue_empty(move_queue)) +
    + { +
    + var xx = ds_queue_dequeue(move_queue); +
    + var yy = ds_queue_dequeue(move_queue); +
    + move_towards_point(xx, yy, 4); +
    + }

    +

    The above code checks the DS queue indexed in the variable "move_queue" to see if it is empty, and if it is not, it then dequeues the two values from the head of the queue and use them to set a direction for movement.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Queues
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_destroy.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_destroy.htm index 8a6711d3d..b1e95eb1c 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_destroy.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_destroy.htm @@ -1,67 +1,69 @@ - + - - - ds_queue_destroy - - - - - - - - - - -

    ds_queue_destroy

    -

    This function will remove the given queue data structure from memory, freeing up the resources it was using and removing all values that it contained. This function should always be used when you are finished using the DS queue to prevent memory leaks that can slow down and crash your game.

    -
    -

     

    -

    Syntax:

    -

    ds_queue_destroy(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS QueueThe id of the data structure to remove.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    if (lives == 0)
    - {
    -     ds_queue_destroy(AI_queue);
    -     AI_queue = -1;
    -     room_goto(rm_Menu);
    - }

    -

    The above code will check the value of the built-in global variable lives and if it is 0, it destroys the DS queue indexed in the variable AI_queue and then changes rooms.

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Queues
    - + + + ds_queue_destroy + + + + + + + + + +

    ds_queue_destroy

    +

    This function will remove the given queue data structure from memory, freeing up the resources it was using and removing all values that it contained. This function should always be used when you are finished using the DS queue to prevent memory leaks that can slow down and crash your game.

    +
    +

    +

    Syntax:

    +

    ds_queue_destroy(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS QueueThe handle of the data structure to remove.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    if (lives == 0) +
    + { +
    + ds_queue_destroy(AI_queue); +
    + AI_queue = -1; +
    + room_goto(rm_Menu); +
    + }

    +

    The above code will check the value of the built-in global variable lives and if it is 0, it destroys the DS queue indexed in the variable AI_queue and then changes rooms.

    +

    +

    +
    +
    +
    +
    Back: DS Queues
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_empty.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_empty.htm index b66e74f9d..b9bbdcf29 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_empty.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_empty.htm @@ -1,68 +1,70 @@ - + - - - ds_queue_empty - - - - - - - - - - - -

    ds_queue_empty

    -

    With this function you can check the given DS queue to see if it is empty (returns true) or not (returns false).

    -

     

    -

    Syntax:

    -

    ds_queue_empty(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Queue IDThe id of the data structure to check.
    -

     

    -

    Returns:

    -

    Boolean

    -

     

    -

    Example:

    -

    if (count == 15) && (!ds_queue_empty(command_queue))
    - {
    -     ds_queue_clear(command_queue);
    -     alarm[0] = game_get_speed(gamespeed_fps);
    -     ai_count = 0;
    - }

    -

    The above code checks a variable to see if it has reached a specific value and if it has it clears the DS queue indexed in the variable "command_queue", sets an alarm, and resets the variable to 0.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Queues
    - + + + ds_queue_empty + + + + + + + + + + +

    ds_queue_empty

    +

    With this function you can check the given DS queue to see if it is empty (returns true) or not (returns false).

    +

    +

    Syntax:

    +

    ds_queue_empty(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Queue IDThe handle of the data structure to check.
    +

    +

    Returns:

    +

    Boolean

    +

    +

    Example:

    +

    if (count == 15) && (!ds_queue_empty(command_queue)) +
    + { +
    + ds_queue_clear(command_queue); +
    + alarm[0] = game_get_speed(gamespeed_fps); +
    + ai_count = 0; +
    + }

    +

    The above code checks a variable to see if it has reached a specific value and if it has it clears the DS queue indexed in the variable "command_queue", sets an alarm, and resets the variable to 0.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Queues
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_enqueue.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_enqueue.htm index a65dccfd2..ab3cf8e88 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_enqueue.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_enqueue.htm @@ -1,71 +1,85 @@ - - + - - - ds_queue_enqueue - - - - - - - - - - - -

    ds_queue_enqueue

    -

    This function will add a value (real or string) onto the tail of the DS queue. The function can take a further 14 optional arguments (making a total of 15 possible additions), permitting you to add multiple values - consecutively to the tail of the queue in a single call.

    -

     

    -

    Syntax:

    -

    ds_queue_enqueue(id, val [, val2, ... val15]);

    - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idThe id of the queue to add to.
    valThe value to add to the queue.
    [val2, ... val15]Optional values to be added to the queue.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    move_queue = ds_queue_create();
    ds_queue_enqueue(move_queue, x + 200);
    ds_queue_enqueue(move_queue, y);
    ds_queue_enqueue(move_queue, x + 200);
    ds_queue_enqueue(move_queue, y + 200);
    ds_queue_enqueue(move_queue, x);
    ds_queue_enqueue(move_queue, - y + 200);
    ds_queue_enqueue(move_queue, x);
    ds_queue_enqueue(move_queue, y);

    -

    The above code creates a new DS queue and stores its index in the variable "move_queue". It then pushes a number of values onto the queue for future use.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Queues
    - + + + + ds_queue_enqueue + + + + + + + + + +

    ds_queue_enqueue

    +

    This function will add a value (real or string) onto the tail of the DS queue. The function can take a further 14 optional arguments (making a total of 15 possible additions), permitting you to add multiple values consecutively to the tail of the queue in a single call.

    +

    +

    Syntax:

    +

    ds_queue_enqueue(id, val [, val2, ... val15]);

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idThe handle of the queue to add to.
    valThe value to add to the queue.
    [val2, ... val15]Optional values to be added to the queue.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    move_queue = ds_queue_create(); +
    + ds_queue_enqueue(move_queue, x + 200); +
    + ds_queue_enqueue(move_queue, y); +
    + ds_queue_enqueue(move_queue, x + 200); +
    + ds_queue_enqueue(move_queue, y + 200); +
    + ds_queue_enqueue(move_queue, x); +
    + ds_queue_enqueue(move_queue, y + 200); +
    + ds_queue_enqueue(move_queue, x); +
    + ds_queue_enqueue(move_queue, y);

    +

    The above code creates a new DS queue and stores its index in the variable "move_queue". It then pushes a number of values onto the queue for future use.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Queues
    + +
    +
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - - \ No newline at end of file +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_head.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_head.htm index f864ffecb..571ee3aeb 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_head.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_head.htm @@ -1,63 +1,60 @@ - + - - - ds_queue_head - - - - - - - - - - - -

    ds_queue_head

    -

    This function will only read the first value of the queue (that which is "at the head"). It will not dequeue the value, meaning that it can still be read in the future by this function or ds_queue_dequeue(). If the queue is empty then the function will return the constant undefined, otherwise it will return the value contained in the queue.

    -

     

    -

    Syntax:

    -

    ds_queue_head(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS QueueThe id of the data structure to read from.
    -

     

    -

    Returns:

    -

    Any (Data type value stored in the queue)

    -

     

    -

    Example:

    -

    num = ds_queue_head(control_queue);

    -

    The above code will read the head value from the queue indexed in the variable "control_queue" and store the return value in the variable "num".

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Queues
    - + + + ds_queue_head + + + + + + + + + + +

    ds_queue_head

    +

    This function will only read the first value of the queue (that which is "at the head"). It will not dequeue the value, meaning that it can still be read in the future by this function or ds_queue_dequeue(). If the queue is empty then the function will return the constant undefined, otherwise it will return the value contained in the queue.

    +

    +

    Syntax:

    +

    ds_queue_head(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS QueueThe handle of the data structure to read from.
    +

    +

    Returns:

    +

    Any (Data type value stored in the queue)

    +

    +

    Example:

    +

    num = ds_queue_head(control_queue);

    +

    The above code will read the head value from the queue indexed in the variable "control_queue" and store the return value in the variable "num".

    +

    +

    +

    +
    +
    +
    +
    Back: DS Queues
    + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_read.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_read.htm index 39e2f8dfd..e9e9cfc32 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_read.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_read.htm @@ -1,80 +1,84 @@ - + - - - ds_queue_read - - - - - - - - - - -

    ds_queue_read

    -

    With this function you can recreate a saved DS queue (one that has previously been written as a string using ds_queue_write()). You must first create a new DS queue to read the string into, and if the DS queue already exists and has information stored in it, then this will be cleared before reading. This function is of vital importance when creating save/load mechanisms for your game.

    -

    Note that if the specified DS string was written by the GameMaker: Studio 1.2.x runtime (or older), you should specify the optional argument "legacy", setting it to true as the string format changed after that.

    -

     

    -

    Syntax:

    -

    ds_queue_read(id, str [, legacy]);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Queue IDThe id of the data structure to read into.
    strStringThe string to read from.
    legacyBooleanOPTIONAL Can be either true or false or omitted completely.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    queue = ds_queue_create();
    - ini_open("save.ini");
    - var str = ini_read_string("Queues", "0", "");
    - if (str != "")
    - {
    -     ds_queue_read(queue, str);
    - }
    - ini_close();

    -

    The above code creates a queue and stores the index in the variable "queue". It then opens an ini file and reads a string from that, checking to make sure that the string is not returned as empty first. This string is then read into the newly created DS queue.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Queues
    - + + + ds_queue_read + + + + + + + + + +

    ds_queue_read

    +

    With this function you can recreate a saved DS queue (one that has previously been written as a string using ds_queue_write()). You must first create a new DS queue to read the string into, and if the DS queue already exists and has information stored in it, then this will be cleared before reading. This function is of vital importance when creating save/load mechanisms for your game.

    +

    Note that if the specified DS string was written by the GameMaker: Studio 1.2.x runtime (or older), you should specify the optional argument "legacy", setting it to true as the string format changed after that.

    +

    +

    Syntax:

    +

    ds_queue_read(id, str [, legacy]);

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Queue IDThe handle of the data structure to read into.
    strStringThe string to read from.
    legacyBooleanOPTIONAL Can be either true or false or omitted completely.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    queue = ds_queue_create(); +
    + ini_open("save.ini"); +
    + var str = ini_read_string("Queues", "0", ""); +
    + if (str != "") +
    + { +
    + ds_queue_read(queue, str); +
    + } +
    + ini_close();

    +

    The above code creates a queue and stores the index in the variable "queue". It then opens an ini file and reads a string from that, checking to make sure that the string is not returned as empty first. This string is then read into the newly created DS queue.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Queues
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_size.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_size.htm index 8cc496231..2918ccb84 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_size.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_size.htm @@ -1,64 +1,66 @@ - + - - - ds_queue_size - - - - - - - - - - - -

    ds_queue_size

    -

    This function will return the "size" of the queue, ie: the number of items that have been queued onto it.

    -

     

    -

    Syntax:

    -

    ds_queue_size(id);

    - - - - - - - - - - - -
    ArgumentTypeDescription
    idThe id of the data structure to check.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    if (!ds_queue_empty(control_queue))
    - {
    -     num = ds_queue_size(control_queue);
    - }

    -

    The above code checks a DS queue to see if it is empty or not, and if it is not, it gets the number of items that it contains and stores the value in a variable.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Queues
    - + + + ds_queue_size + + + + + + + + + + +

    ds_queue_size

    +

    This function will return the "size" of the queue, ie: the number of items that have been queued onto it.

    +

    +

    Syntax:

    +

    ds_queue_size(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idThe handle of the data structure to check.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    if (!ds_queue_empty(control_queue)) +
    + { +
    + num = ds_queue_size(control_queue); +
    + }

    +

    The above code checks a DS queue to see if it is empty or not, and if it is not, it gets the number of items that it contains and stores the value in a variable.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Queues
    + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_tail.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_tail.htm index 2ab34adf7..6122a6370 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_tail.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_tail.htm @@ -1,63 +1,60 @@ - + - - - ds_queue_tail - - - - - - - - - - - -

    ds_queue_tail

    -

    This function will only read the last value of the queue (that which is "at the tail"). It will not remove the value from the structure, meaning that it can be read again by calling this function. If the queue is empty then the function will return the constant undefined, otherwise it will return the value contained in the queue.

    -

     

    -

    Syntax:

    -

    ds_queue_tail(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS QueueThe id of the data structure to read from.
    -

     

    -

    Returns:

    -

    Any (Data type value stored in the queue)

    -

     

    -

    Example:

    -

    num = ds_queue_tail(control_queue);

    -

    The above code will read the tail value from the queue indexed in the variable "control_queue" and store the return value in the variable "num".

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Queues
    - + + + ds_queue_tail + + + + + + + + + + +

    ds_queue_tail

    +

    This function will only read the last value of the queue (that which is "at the tail"). It will not remove the value from the structure, meaning that it can be read again by calling this function. If the queue is empty then the function will return the constant undefined, otherwise it will return the value contained in the queue.

    +

    +

    Syntax:

    +

    ds_queue_tail(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS QueueThe handle of the data structure to read from.
    +

    +

    Returns:

    +

    Any (Data type value stored in the queue)

    +

    +

    Example:

    +

    num = ds_queue_tail(control_queue);

    +

    The above code will read the tail value from the queue indexed in the variable "control_queue" and store the return value in the variable "num".

    +

    +

    +

    +
    +
    +
    +
    Back: DS Queues
    + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_write.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_write.htm index ee6e630d3..c2348251c 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_write.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_write.htm @@ -1,68 +1,69 @@ - + - - - ds_queue_write - - - - - - - - - - - -

    ds_queue_write

    -

    This function returns a string which can then be stored or transferred to another data structure using the ds_queue_read() function.

    -
    -

     

    -

    Syntax:

    -

    ds_queue_write(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Queue IDThe id of the data structure to write.
    -

     

    -

    Returns:

    -

    String

    -

     

    -

    Example:

    -

    ini_open("save.ini");
    - var str =ds_queue_write(queue);
    - ini_write_string("Queues", "0", str);
    - ds_queue_clear(queue);
    - ini_close();

    -

    The above code opens an ini file and then writes a string containing the information stored in the DS queue indexed in the variable "queue". The queue is then cleared and the ini file closed.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Queues
    - + + + ds_queue_write + + + + + + + + + + +

    ds_queue_write

    +

    This function returns a string which can then be stored or transferred to another data structure using the ds_queue_read() function.

    +
    +

    +

    Syntax:

    +

    ds_queue_write(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Queue IDThe handle of the data structure to write.
    +

    +

    Returns:

    +

    String

    +

    +

    Example:

    +

    ini_open("save.ini"); +
    + var str =ds_queue_write(queue); +
    + ini_write_string("Queues", "0", str); +
    + ds_queue_clear(queue); +
    + ini_close();

    +

    The above code opens an ini file and then writes a string containing the information stored in the DS queue indexed in the variable "queue". The queue is then cleared and the ini file closed.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Queues
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_clear.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_clear.htm index 8faf3f569..6e8dec85f 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_clear.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_clear.htm @@ -1,67 +1,69 @@ - + - - - ds_stack_clear - - - - - - - - - - -

    ds_stack_clear

    -

    With this function you can clear all data from the given stack data-structure. This does NOT destroy the data-structure (for that you should use ds_stack_destroy()) it only wipes all data from it and returns an empty stack.

    -

     

    -

    Syntax:

    -

    ds_stack_clear(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Stack IDThe id of the data structure to clear.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    if (ai_count = 15 && !ds_stack_empty(AI_stack))
    - {
    -     ds_stack_clear(AI_stack);
    -     alarm[0] = game_get_speed(gamespeed_fps);
    -     ai_count = 0;
    - }

    -

    The above code checks a variable to see if it has reached a specific value and if it has it clears the DS stack indexed in the variable "AI_stack", sets an alarm, and resets the variable to 0.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Stacks
    - + + + ds_stack_clear + + + + + + + + + +

    ds_stack_clear

    +

    With this function you can clear all data from the given stack data-structure. This does NOT destroy the data-structure (for that you should use ds_stack_destroy()) it only wipes all data from it and returns an empty stack.

    +

    +

    Syntax:

    +

    ds_stack_clear(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Stack IDThe handle of the data structure to clear.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    if (ai_count = 15 && !ds_stack_empty(AI_stack)) +
    + { +
    + ds_stack_clear(AI_stack); +
    + alarm[0] = game_get_speed(gamespeed_fps); +
    + ai_count = 0; +
    + }

    +

    The above code checks a variable to see if it has reached a specific value and if it has it clears the DS stack indexed in the variable "AI_stack", sets an alarm, and resets the variable to 0.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Stacks
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_copy.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_copy.htm index 03c0d8856..f725dd377 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_copy.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_copy.htm @@ -1,71 +1,72 @@ - + - - - ds_stack_copy - - - - - - - - - - -

    ds_stack_copy

    -

    This function can be used to copy the contents of one stack into another. Note that this does NOT remove the contents from the original stack, nor does it destroy the original stack. When using this function the stack being copied to must have been previously created and if it contained any items before the copy, then these will be cleared first (meaning this information will be lost).

    -

     

    -

    Syntax:

    -

    ds_stack_copy(id, source);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Stack IDThe id of the new stack.
    sourceDS Stack IDThe original stack to copy from.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    with (instance_create_layer(x, y, "Enemies", obj_Enemy))
    - {
    -     stack = ds_stack_create();
    -     ds_stack_copy(stack, other.stack);
    - }

    -

    The above function creates a new instance and then in that instance it creates a new DS stack and copies the contents of the stack in the instance running the code block, into the newly created instance stack.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Stacks
    - + + + ds_stack_copy + + + + + + + + + +

    ds_stack_copy

    +

    This function can be used to copy the contents of one stack into another. Note that this does NOT remove the contents from the original stack, nor does it destroy the original stack. When using this function the stack being copied to must have been previously created and if it contained any items before the copy, then these will be cleared first (meaning this information will be lost).

    +

    +

    Syntax:

    +

    ds_stack_copy(id, source);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Stack IDThe handle of the new stack.
    sourceDS Stack IDThe original stack to copy from.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    with (instance_create_layer(x, y, "Enemies", obj_Enemy)) +
    + { +
    + stack = ds_stack_create(); +
    + ds_stack_copy(stack, other.stack); +
    + }

    +

    The above function creates a new instance and then in that instance it creates a new DS stack and copies the contents of the stack in the instance running the code block, into the newly created instance stack.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Stacks
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_empty.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_empty.htm index a91febd81..2ea188f64 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_empty.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_empty.htm @@ -4,7 +4,7 @@ ds_stack_empty - + @@ -29,21 +29,21 @@

    Syntax:

    id - DS Stack ID - The id of the data structure to check. + DS Stack + The handle of the data structure to check.

     

    Returns:

    -

    Boolean

    +

    Boolean

     

    Example:

    if (ai_count == 15 && !ds_stack_empty(AI_stack))
    {
    -     ds_stack_clear(AI_stack);
    -     alarm[0] = game_get_speed(gamespeed_fps);
    -     ai_count = 0;
    + ds_stack_clear(AI_stack);
    + alarm[0] = game_get_speed(gamespeed_fps);
    + ai_count = 0;
    }

    The above code checks a variable to see if it has reached a specific value and if it has it clears the DS stack indexed in the variable "AI_stack", sets an alarm, and resets the variable to 0.

     

    @@ -52,11 +52,11 @@

    Example:

    -
    Back: DS Stacks
    +
    Back: DS Stacks
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -

    ds_stack_pop

    -

    This function will pop the top value off of the DS stack, removing it from the stack and returning the value to be stored in a variable. If the stack is empty then the function will return the constant undefined, otherwise it will return the real or string value contained in the stack.

    -

     

    -

    Syntax:

    -

    ds_stack_pop(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Stack IDThe id of the data structure to pop from.
    -

     

    -

    Returns:

    -

    Any (Data type value that is stored in the stack) or undefined

    -

     

    -

    Example:

    -

    if (!ds_stack_empty(move_stack))
    - {
    -     var xx = ds_stack_pop(move_stack);
    -     var yy = ds_stack_pop(move_stack);
    -     move_towards_point(xx, yy, 4);
    - }

    -

    The above code checks the DS stack indexed in the variable "move_stack" to see if it is empty, and if it is not, it then pops the top two values from the stack and use them to set a direction for movement.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Stacks
    - + + + ds_stack_pop + + + + + + + + + +

    ds_stack_pop

    +

    This function will pop the top value off of the DS stack, removing it from the stack and returning the value to be stored in a variable. If the stack is empty then the function will return the constant undefined, otherwise it will return the real or string value contained in the stack.

    +

    +

    Syntax:

    +

    ds_stack_pop(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Stack IDThe handle of the data structure to pop from.
    +

    +

    Returns:

    +

    Any (Data type value that is stored in the stack) or undefined

    +

    +

    Example:

    +

    if (!ds_stack_empty(move_stack)) +
    + { +
    + var xx = ds_stack_pop(move_stack); +
    + var yy = ds_stack_pop(move_stack); +
    + move_towards_point(xx, yy, 4); +
    + }

    +

    The above code checks the DS stack indexed in the variable "move_stack" to see if it is empty, and if it is not, it then pops the top two values from the stack and use them to set a direction for movement.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Stacks
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_push.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_push.htm index 89234ceb7..884b8aa8c 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_push.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_push.htm @@ -1,73 +1,71 @@ - + - - - ds_stack_push - - - - - - - - - - -

    ds_stack_push

    -

    This function will push (add) a value, which can be of any data type, onto the top of the stack. The function can take any number of additional arguments, permitting you to push multiple values consecutively to the stack in a single call.

    -

     

    -

    Syntax:

    -

    ds_stack_push(id, val [, val2, ...]);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS StackThe id of the data structure to push onto.
    valAnyThe value to push onto the stack.
    [val2, ...]AnyOptional values to be added to the stack, each one a new argument.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    move_stack = ds_stack_create();
    - ds_stack_push(move_stack, x, y, x, y + 200, x + 200, y + 200, x + 200, y);

    -

    The above code creates a new DS stack and stores its index in the variable "move_stack". It then pushes a number of values onto the stack for future use.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Stacks
    - + + + ds_stack_push + + + + + + + + + +

    ds_stack_push

    +

    This function will push (add) a value, which can be of any data type, onto the top of the stack. The function can take any number of additional arguments, permitting you to push multiple values consecutively to the stack in a single call.

    +

    +

    Syntax:

    +

    ds_stack_push(id, val [, val2, ...]);

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS StackThe handle of the data structure to push onto.
    valAnyThe value to push onto the stack.
    [val2, ...]AnyOptional values to be added to the stack, each one a new argument.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    move_stack = ds_stack_create(); +
    + ds_stack_push(move_stack, x, y, x, y + 200, x + 200, y + 200, x + 200, y);

    +

    The above code creates a new DS stack and stores its index in the variable "move_stack". It then pushes a number of values onto the stack for future use.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Stacks
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_read.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_read.htm index 09f6e95db..5a035232b 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_read.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_read.htm @@ -1,80 +1,84 @@ - + - - - ds_stack_read - - - - - - - - - - -

    ds_stack_read

    -

    With this function you can recreate a saved DS stack (one that has previously been written as a string using ds_stack_write()). You must first create a new DS stack to read the string into, and if the DS stack already exists and has information stored in it, then this will be cleared before reading. This function is of vital importance when creating save/load mechanisms for your game.

    -

    Note that if the specified DS string was written by the GameMaker: Studio 1.2.x runtime (or older), you should specify the optional argument "legacy", setting it to true as the string format changed after that.

    -

     

    -

    Syntax:

    -

    ds_stack_read(id, str [, legacy]);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Stack IDThe id of the data structure to read into.
    strStringThe string to read from.
    legacyBooleanOPTIONAL Can be either true or false or omitted completely.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    stack = ds_stack_create();
    - ini_open("save.ini");
    - var str = ini_read_string("Stacks", "0", "");
    - if (str != "")
    - {
    -     ds_stack_read(stack, str);
    - }
    - ini_close();

    -

    The above code creates a stack and stores the index in the variable "stack". It then opens an ini file and reads a string from that, checking to make sure that the string is not returned as empty first. This string is then read into the newly created DS stack .

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Stacks
    - + + + ds_stack_read + + + + + + + + + +

    ds_stack_read

    +

    With this function you can recreate a saved DS stack (one that has previously been written as a string using ds_stack_write()). You must first create a new DS stack to read the string into, and if the DS stack already exists and has information stored in it, then this will be cleared before reading. This function is of vital importance when creating save/load mechanisms for your game.

    +

    Note that if the specified DS string was written by the GameMaker: Studio 1.2.x runtime (or older), you should specify the optional argument "legacy", setting it to true as the string format changed after that.

    +

    +

    Syntax:

    +

    ds_stack_read(id, str [, legacy]);

    + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Stack IDThe handle of the data structure to read into.
    strStringThe string to read from.
    legacyBooleanOPTIONAL Can be either true or false or omitted completely.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    stack = ds_stack_create(); +
    + ini_open("save.ini"); +
    + var str = ini_read_string("Stacks", "0", ""); +
    + if (str != "") +
    + { +
    + ds_stack_read(stack, str); +
    + } +
    + ini_close();

    +

    The above code creates a stack and stores the index in the variable "stack". It then opens an ini file and reads a string from that, checking to make sure that the string is not returned as empty first. This string is then read into the newly created DS stack .

    +

    +

    +

    +
    +
    +
    +
    Back: DS Stacks
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_size.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_size.htm index a4686f4b7..97451daa7 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_size.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_size.htm @@ -1,66 +1,66 @@ - + - - - ds_stack_size - - - - - - - - - - - -

    ds_stack_size

    -

    This function will return the "size" of the stack, ie: the number of items that have been pushed onto it.

    -

     

    -

    Syntax:

    -

    ds_stack_size(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Stack IDThe id of the data structure to check.
    -

     

    -

    Returns:

    -

    Real

    -

     

    -

    Example:

    -

    if (!ds_stack_empty(control_stack))
    - {
    -     num = ds_stack_size(control_stack);
    - }

    -

    The above code checks a DS stack to see if it is empty or not, and if it is not, it gets the number of items that it contains and stores the value in a variable.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Stacks
    - + + + ds_stack_size + + + + + + + + + + +

    ds_stack_size

    +

    This function will return the "size" of the stack, ie: the number of items that have been pushed onto it.

    +

    +

    Syntax:

    +

    ds_stack_size(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Stack IDThe handle of the data structure to check.
    +

    +

    Returns:

    +

    Real

    +

    +

    Example:

    +

    if (!ds_stack_empty(control_stack)) +
    + { +
    + num = ds_stack_size(control_stack); +
    + }

    +

    The above code checks a DS stack to see if it is empty or not, and if it is not, it gets the number of items that it contains and stores the value in a variable.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Stacks
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_top.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_top.htm index 43ad095bb..e628c50b4 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_top.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_top.htm @@ -1,63 +1,60 @@ - + - - - ds_stack_top - - - - - - - - - - - -

    ds_stack_top

    -

    This function will only read the first value of the stack (that which is "on top"). It will not pop the value, meaning that it can still be read in the future by this function or the ds_stack_pop(). If the stack is empty then the function will return the constant undefined, otherwise it will return the real or string value contained in the stack.

    -

     

    -

    Syntax:

    -

    ds_stack_top(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Stack IDThe id of the data structure to read from.
    -

     

    -

    Returns:

    -

    Any (Data type value that is stored in the stack) or undefined

    -

     

    -

    Example:

    -

    num = ds_stack_top(control_stack);

    -

    The above code will read the value from the stack indexed in the variable "control_stack" and store the return value in the variable "num".

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Stacks
    - + + + ds_stack_top + + + + + + + + + + +

    ds_stack_top

    +

    This function will only read the first value of the stack (that which is "on top"). It will not pop the value, meaning that it can still be read in the future by this function or the ds_stack_pop(). If the stack is empty then the function will return the constant undefined, otherwise it will return the real or string value contained in the stack.

    +

    +

    Syntax:

    +

    ds_stack_top(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Stack IDThe handle of the data structure to read from.
    +

    +

    Returns:

    +

    Any (Data type value that is stored in the stack) or undefined

    +

    +

    Example:

    +

    num = ds_stack_top(control_stack);

    +

    The above code will read the value from the stack indexed in the variable "control_stack" and store the return value in the variable "num".

    +

    +

    +

    +
    +
    +
    +
    Back: DS Stacks
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_write.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_write.htm index 04382ce15..db2ff6426 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_write.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_write.htm @@ -1,68 +1,69 @@ - + - - - ds_stack_write - - - - - - - - - - - -

    ds_stack_write

    -

    This function returns a string which can then be stored or transferred to another data structure using the ds_stack_read() function.

    -
    -

     

    -

    Syntax:

    -

    ds_stack_write(id);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Stack IDThe id of the data structure to write.
    -

     

    -

    Returns:

    -

    String

    -

     

    -

    Example:

    -

    ini_open("save.ini");
    - var str = ds_stack_write(stack);
    - ini_write_string("Stacks", "0", str);
    - ds_stack_clear(stack);
    - ini_close();

    -

    The above code opens an ini file and then writes a string containing the information stored in the DS stack indexed in the variable "stack". The stack is then cleared and the ini file closed.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: DS Stacks
    - + + + ds_stack_write + + + + + + + + + + +

    ds_stack_write

    +

    This function returns a string which can then be stored or transferred to another data structure using the ds_stack_read() function.

    +
    +

    +

    Syntax:

    +

    ds_stack_write(id);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    idDS Stack IDThe handle of the data structure to write.
    +

    +

    Returns:

    +

    String

    +

    +

    Example:

    +

    ini_open("save.ini"); +
    + var str = ds_stack_write(stack); +
    + ini_write_string("Stacks", "0", str); +
    + ds_stack_clear(stack); +
    + ini_close();

    +

    The above code opens an ini file and then writes a string containing the information stored in the DS stack indexed in the variable "stack". The stack is then cleared and the ini file closed.

    +

    +

    +

    +
    +
    +
    +
    Back: DS Stacks
    + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_get_tex_max_aniso_ext.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_get_tex_max_aniso_ext.htm index 218e245b6..e5d7e38b6 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_get_tex_max_aniso_ext.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_get_tex_max_aniso_ext.htm @@ -1,69 +1,76 @@ - + - - - gpu_get_tex_max_aniso_ext - - - - - - - - - - - -

    gpu_get_tex_max_aniso_ext

    -

    With this function you can get the current maximum level of anisotropy when using the tf_anisotropic filter mode (see gpu_get_tex_mip_filter() for more information) on a shader sampler. You supply the index value for the shader sampler (as returned by the function shader_get_sampler_index(), and the function will return a value within the range of 1 and 16.

    -

     

    -

    Syntax:

    -

    gpu_get_tex_max_aniso_ext(sampler_index);

    - - - - - - - - - - - -
    ArgumentTypeDescription
    sampler_indexThe index of the shader sampler to get
    -

     

    -

    Returns:

    -

    (default: 16)

    -

     

    -

    Example:

    -

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background");
    - var _spriteTex = sprite_get_texture(sprite_index, 0);
    - shader_set(shd_Glass);
    - if (gpu_get_tex_max_aniso_ext(_sampleIndex) != 8)
    - {
    -     gpu_set_tex_max_aniso_ext(_sampleIndex, 8);
    - }
    - texture_set_stage(_sampleIndex , _spriteTex);
    - shader_reset();

    -

    The above code sets the maximum level of anisotropy to 8 for the given shader texture sampler if it has not already been set to 8.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: Mipmapping
    - + + + gpu_get_tex_max_aniso_ext + + + + + + + + + + +

    gpu_get_tex_max_aniso_ext

    +

    With this function you can get the current maximum level of anisotropy when using the tf_anisotropic filter mode (see gpu_get_tex_mip_filter() for more information) on a shader sampler. You supply the handle for the shader sampler (as returned by the function shader_get_sampler_index(), and the function will return a value within the range of 1 and 16.

    +

    +

    Syntax:

    +

    gpu_get_tex_max_aniso_ext(sampler_index);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    sampler_indexShader Sampler HandleThe shader sampler to get
    +

    +

    Returns:

    +

    Real (default: 16)

    +

    +

    Example:

    +

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background"); +
    + var _spriteTex = sprite_get_texture(sprite_index, 0); +
    + shader_set(shd_Glass); +
    + if (gpu_get_tex_max_aniso_ext(_sampleIndex) != 8) +
    + { +
    + gpu_set_tex_max_aniso_ext(_sampleIndex, 8); +
    + } +
    + texture_set_stage(_sampleIndex , _spriteTex); +
    + shader_reset();

    +

    The above code sets the maximum level of anisotropy to 8 for the given shader texture sampler if it has not already been set to 8.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_get_tex_max_mip_ext.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_get_tex_max_mip_ext.htm index 78eaa08f0..b489578d3 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_get_tex_max_mip_ext.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_get_tex_max_mip_ext.htm @@ -1,69 +1,76 @@ - + - - - gpu_get_tex_max_mip_ext - - - - - - - - - - - -

    gpu_get_tex_max_mip_ext

    -

    With this function you can get the currently set maximum mipmap level which is to be used for a given shader sampler. You supply the index value for the shader sampler (as returned by the function shader_get_sampler_index(), and the function will return the current maximum mipmap level, where a value of 0 is the highest resolution, 1 is to use the first mipmap, 2 is the second etc... Note that this can be quite useful for avoiding bleeding artifacts when rendering textures, for example, setting the texture page border to 8px and then setting the max mipmap level to 3 will ensure you don't get any bleeding problems at greater render distances.

    -

     

    -

    Syntax:

    -

    gpu_get_tex_max_mip_ext(sampler_index);

    - - - - - - - - - - - -
    ArgumentTypeDescription
    sampler_indexThe index of the shader sampler to get
    -

     

    -

    Returns:

    -

    (default: 16)

    -

     

    -

    Example:

    -

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background");
    - var _spriteTex = sprite_get_texture(sprite_index, 0);
    - shader_set(shd_Glass);
    - if (gpu_get_tex_max_mip_ext(_sampleIndex) != 4)
    - {
    -     gpu_set_tex_max_mip_ext(_sampleIndex, 4);
    - }
    - texture_set_stage(_sampleIndex , _spriteTex);
    - shader_reset();

    -

    The above code sets the maximum mipmap level to 4 for the given shader texture sampler if it has not already been set to 4.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: Mipmapping
    - + + + gpu_get_tex_max_mip_ext + + + + + + + + + + +

    gpu_get_tex_max_mip_ext

    +

    With this function you can get the currently set maximum mipmap level which is to be used for a given shader sampler. You supply the handle for the shader sampler (as returned by the function shader_get_sampler_index(), and the function will return the current maximum mipmap level, where a value of 0 is the highest resolution, 1 is to use the first mipmap, 2 is the second etc... Note that this can be quite useful for avoiding bleeding artifacts when rendering textures, for example, setting the texture page border to 8px and then setting the max mipmap level to 3 will ensure you don't get any bleeding problems at greater render distances.

    +

    +

    Syntax:

    +

    gpu_get_tex_max_mip_ext(sampler_index);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    sampler_indexShader Sampler HandleThe shader sampler to get
    +

    +

    Returns:

    +

    Real (default: 16)

    +

    +

    Example:

    +

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background"); +
    + var _spriteTex = sprite_get_texture(sprite_index, 0); +
    + shader_set(shd_Glass); +
    + if (gpu_get_tex_max_mip_ext(_sampleIndex) != 4) +
    + { +
    + gpu_set_tex_max_mip_ext(_sampleIndex, 4); +
    + } +
    + texture_set_stage(_sampleIndex , _spriteTex); +
    + shader_reset();

    +

    The above code sets the maximum mipmap level to 4 for the given shader texture sampler if it has not already been set to 4.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_get_tex_min_mip_ext.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_get_tex_min_mip_ext.htm index ed0fe8692..4e1aa2512 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_get_tex_min_mip_ext.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_get_tex_min_mip_ext.htm @@ -4,7 +4,7 @@ gpu_get_tex_min_mip_ext - + @@ -16,33 +16,35 @@

    gpu_get_tex_min_mip_ext

    -

    With this function you can get the minimum mipmap level which is currently used for a given shader sampler. You supply the index value for the shader sampler (as returned by the function shader_get_sampler_index(), and the function will return a value of 0 for full resolution, 1 for the first mipmap, 2 for the second etc...

    +

    With this function you can get the minimum mipmap level which is currently used for a given shader sampler. You supply the handle for the shader sampler (as returned by the function shader_get_sampler_index(), and the function will return a value of 0 for full resolution, 1 for the first mipmap, 2 for the second etc...

     

    Syntax:

    gpu_get_tex_min_mip_ext(sampler_index);

    - + + - + - - - + + + +
    ArgumentTypeArgumentType Description
    sampler_indexThe index of the shader sampler to get
    sampler_indexShader Sampler HandleThe shader sampler to get

     

    Returns:

    -

    (default: 0)

    +

    Real (default: 0)

     

    Example:

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background");
    var _spriteTex = sprite_get_texture(sprite_index, 0);
    shader_set(shd_Glass);
    - if (gpu_get_tex_min_mip_ext(_sampleIndex) != 0)
    + if (gpu_get_tex_min_mip_ext(_sampleIndex) != 0)
    {
    -     gpu_set_tex_min_mip_ext(_sampleIndex, 0);
    + gpu_set_tex_min_mip_ext(_sampleIndex, 0);
    }
    texture_set_stage(_sampleIndex , _spriteTex);
    shader_reset();

    @@ -53,11 +55,11 @@

    Example:

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

    gpu_get_tex_mip_bias_ext

    -

    With this function you can retrieve the mipmap bias value for a given shader sampler. You supply the index value for the shader sampler (as returned by the function shader_get_sampler_index(), and the function will return a value of 0.0 for no bias, or a greater value where 1 equals the first mipmap, 2 equals the second mipmap etc... This controls the rate at which the mip map is swapped and will generally make the shader textures blurrier the higher the value and the greater the "distance" being viewed. Note that this can return negative values too, in which case shader textures will be sharper over a greater distance the lower the value.

    -

     

    -

    Syntax:

    -

    gpu_get_tex_mip_bias_ext(sampler_index);

    - - - - - - - - - - - -
    ArgumentTypeDescription
    sampler_indexThe index of the shader sampler to get
    -

     

    -

    Returns:

    -

    (default: 0)

    -

     

    -

    Example:

    -

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background");
    - var _spriteTex = sprite_get_texture(sprite_index, 0);
    - shader_set(shd_Glass);
    - if (gpu_get_tex_mip_bias_ext(_sampleIndex) != 0)
    - {
    -     gpu_set_tex_mip_bias_ext(_sampleIndex, 0);
    - }
    - texture_set_stage(_sampleIndex , _spriteTex);
    - shader_reset();

    -

    The above code sets the mip filter bias to 0 for the given shader texture sampler if it has not already been set to 0.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: Mipmapping
    - + + + gpu_get_tex_mip_bias_ext + + + + + + + + + + +

    gpu_get_tex_mip_bias_ext

    +

    With this function you can retrieve the mipmap bias value for a given shader sampler. You supply the handle for the shader sampler (as returned by the function shader_get_sampler_index(), and the function will return a value of 0.0 for no bias, or a greater value where 1 equals the first mipmap, 2 equals the second mipmap etc... This controls the rate at which the mip map is swapped and will generally make the shader textures blurrier the higher the value and the greater the "distance" being viewed. Note that this can return negative values too, in which case shader textures will be sharper over a greater distance the lower the value.

    +

    +

    Syntax:

    +

    gpu_get_tex_mip_bias_ext(sampler_index);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    sampler_indexShader Sampler HandleThe shader sampler to get
    +

    +

    Returns:

    +

    Real (default: 0)

    +

    +

    Example:

    +

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background"); +
    + var _spriteTex = sprite_get_texture(sprite_index, 0); +
    + shader_set(shd_Glass); +
    + if (gpu_get_tex_mip_bias_ext(_sampleIndex) != 0) +
    + { +
    + gpu_set_tex_mip_bias_ext(_sampleIndex, 0); +
    + } +
    + texture_set_stage(_sampleIndex , _spriteTex); +
    + shader_reset();

    +

    The above code sets the mip filter bias to 0 for the given shader texture sampler if it has not already been set to 0.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_get_tex_mip_enable_ext.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_get_tex_mip_enable_ext.htm index 59a9fb5b3..a70b6f65c 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_get_tex_mip_enable_ext.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_get_tex_mip_enable_ext.htm @@ -1,94 +1,99 @@ - + - - - gpu_get_tex_mip_enable_ext - - - - - - - - - - - -

    gpu_get_tex_mip_enable_ext

    -

    With this function you can get whether mipmapping is switched off, switched on for everything or switched on only for texture groups selected in the Texture Group Manager on a shader sampler. You supply the index value for the shader sampler (as returned by the function shader_get_sampler_index(), and the function will return one of the constants listed below.

    -

     

    -

    Syntax:

    -

    gpu_get_tex_mip_enable_ext(sampler_index);

    - - - - - - - - - - - - - -
    ArgumentTypeDescription
    sampler_indexShader Sampler HandleThe index of the shader sampler to get
    -

     

    -

    Returns:

    -

    Constant

    - - - - - - - - - - - - - - - - - - - -
    ConstantDescription
    mip_offMipmapping is disabled.
    mip_onMipmapping for all textures is enabled.
    mip_markedonlyMipmapping is enabled for textures that have it enabled in the Texture Group options.
    -

     

    -

    Example:

    -

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background");
    - var _spriteTex = sprite_get_texture(sprite_index, 0);
    - shader_set(shd_Glass);
    - if (gpu_get_tex_mip_enable_ext(_sampleIndex) != mip_on)
    - {
    -     gpu_set_tex_mip_enable_ext(_sampleIndex, mip_on);
    - }
    - texture_set_stage(_sampleIndex , _spriteTex);
    - shader_reset();

    -

    The above code enables mipmapping for the given shader texture sampler if it has not already been enabled.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: Mipmapping
    - + + + gpu_get_tex_mip_enable_ext + + + + + + + + + + +

    gpu_get_tex_mip_enable_ext

    +

    With this function you can get whether mipmapping is switched off, switched on for everything or switched on only for texture groups selected in the Texture Group Manager on a shader sampler. You supply the handle for the shader sampler (as returned by the function shader_get_sampler_index(), and the function will return one of the constants listed below.

    +

    +

    Syntax:

    +

    gpu_get_tex_mip_enable_ext(sampler_index);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    sampler_indexShader Sampler HandleThe shader sampler to get
    +

    +

    Returns:

    +

    Constant

    + + + + + + + + + + + + + + + + + + + +
    ConstantDescription
    mip_offMipmapping is disabled.
    mip_onMipmapping for all textures is enabled.
    mip_markedonlyMipmapping is enabled for textures that have it enabled in the Texture Group options.
    +

    +

    Example:

    +

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background"); +
    + var _spriteTex = sprite_get_texture(sprite_index, 0); +
    + shader_set(shd_Glass); +
    + if (gpu_get_tex_mip_enable_ext(_sampleIndex) != mip_on) +
    + { +
    + gpu_set_tex_mip_enable_ext(_sampleIndex, mip_on); +
    + } +
    + texture_set_stage(_sampleIndex , _spriteTex); +
    + shader_reset();

    +

    The above code enables mipmapping for the given shader texture sampler if it has not already been enabled.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_get_tex_mip_filter_ext.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_get_tex_mip_filter_ext.htm index 12f666c05..a917087b7 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_get_tex_mip_filter_ext.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_get_tex_mip_filter_ext.htm @@ -1,93 +1,100 @@ - + - - - gpu_get_tex_mip_filter_ext - - - - - - - - - - - -

    gpu_get_tex_mip_filter_ext

    -

    With this function you can get the current mip filter mode for a given shader sampler. You supply the index value for the shader sampler (as returned by the function shader_get_sampler_index(), and the function will return one of the mode value constants listed below.

    -

     

    -

    Syntax:

    -

    gpu_get_tex_mip_filter_ext(sampler_index);

    - - - - - - - - - - - -
    ArgumentTypeDescription
    sampler_indexThe index of the shader sampler to get
    -

     

    -

    Returns:

    -

    Mipmapping Filter Constant (listed below):

    - - - - - - - - - - - - - - - - - - - -
    ConstantDescription
    tf_pointThis means that blending between mipmap levels is disabled, which can cause visible texture transitions, but gives the best performance.
    tf_linearThis means that blending between mipmap levels is enabled (this is also known as trilinear filtering), which smooths the texture transitions, but it will give a minor hit to performance.
    tf_anisotropicThis means that anisotropic filtering is enabled, which greatly improves texture transition quality and can reduce the blurring visible with other filtering modes, but it has the highest hit on performance.
    -

     

    -

     

    -

    Example:

    -

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background");
    - var _spriteTex = sprite_get_texture(sprite_index, 0);
    - shader_set(shd_Glass);
    - if (gpu_get_tex_mip_filter_ext(_sampleIndex) != tf_point)
    - {
    -     gpu_set_tex_mip_filter_ext(_sampleIndex, tf_point);
    - }
    - texture_set_stage(_sampleIndex , _spriteTex);
    - shader_reset();

    -

    The above code sets the mip filter mode to tf_point (disabling mipmapping) for the given shader texture sampler if it has not already been set.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: Mipmapping
    - + + + gpu_get_tex_mip_filter_ext + + + + + + + + + + +

    gpu_get_tex_mip_filter_ext

    +

    With this function you can get the current mip filter mode for a given shader sampler. You supply the handle for the shader sampler (as returned by the function shader_get_sampler_index(), and the function will return one of the mode value constants listed below.

    +

    +

    Syntax:

    +

    gpu_get_tex_mip_filter_ext(sampler_index);

    + + + + + + + + + + + + + +
    ArgumentTypeDescription
    sampler_indexShader Sampler HandleThe shader sampler to get
    +

    +

    Returns:

    +

    Mipmapping Filter Constant (listed below):

    + + + + + + + + + + + + + + + + + + + +
    ConstantDescription
    tf_pointThis means that blending between mipmap levels is disabled, which can cause visible texture transitions, but gives the best performance.
    tf_linearThis means that blending between mipmap levels is enabled (this is also known as trilinear filtering), which smooths the texture transitions, but it will give a minor hit to performance.
    tf_anisotropicThis means that anisotropic filtering is enabled, which greatly improves texture transition quality and can reduce the blurring visible with other filtering modes, but it has the highest hit on performance.
    +

    +

    +

    Example:

    +

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background"); +
    + var _spriteTex = sprite_get_texture(sprite_index, 0); +
    + shader_set(shd_Glass); +
    + if (gpu_get_tex_mip_filter_ext(_sampleIndex) != tf_point) +
    + { +
    + gpu_set_tex_mip_filter_ext(_sampleIndex, tf_point); +
    + } +
    + texture_set_stage(_sampleIndex , _spriteTex); +
    + shader_reset();

    +

    The above code sets the mip filter mode to tf_point (disabling mipmapping) for the given shader texture sampler if it has not already been set.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_set_tex_max_aniso_ext.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_set_tex_max_aniso_ext.htm index 8e3c20f95..0d152cda8 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_set_tex_max_aniso_ext.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_set_tex_max_aniso_ext.htm @@ -1,73 +1,81 @@ - + - - - gpu_set_tex_max_aniso_ext - - - - - - - - - - - -

    gpu_set_tex_max_aniso_ext

    -

    With this function you can set the maximum level of anisotropy when using the tf_anisotropic filter mode (see gpu_get_tex_mip_filter() for more information) on a shader sampler. You supply the index value for the shader sampler (as returned by the function shader_get_sampler_index(), and then a value within the range of 1 and 16 to set the level.

    -

     

    -

    Syntax:

    -

    gpu_set_tex_max_aniso_ext(sampler_index, maxaniso);

    - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    sampler_indexThe index of the shader sampler to get
    maxanisoThe maximum anisotropic level to use (default: 16).
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background");
    - var _spriteTex = sprite_get_texture(sprite_index, 0);
    - shader_set(shd_Glass);
    - if (gpu_get_tex_max_aniso_ext(_sampleIndex) != 8)
    - {
    -     gpu_set_tex_max_aniso_ext(_sampleIndex, 8);
    - }
    - texture_set_stage(_sampleIndex , _spriteTex);
    - shader_reset();

    -

    The above code sets the maximum level of anisotropy to 8 for the given shader texture sampler if it has not already been set to 8.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: Mipmapping
    - + + + gpu_set_tex_max_aniso_ext + + + + + + + + + + +

    gpu_set_tex_max_aniso_ext

    +

    With this function you can set the maximum level of anisotropy when using the tf_anisotropic filter mode (see gpu_get_tex_mip_filter() for more information) on a shader sampler. You supply the handle for the shader sampler (as returned by the function shader_get_sampler_index(), and then a value within the range of 1 and 16 to set the level.

    +

    +

    Syntax:

    +

    gpu_set_tex_max_aniso_ext(sampler_index, maxaniso);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    sampler_indexShader Sampler HandleThe shader sampler to get
    maxanisoRealThe maximum anisotropic level to use (default: 16).
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background"); +
    + var _spriteTex = sprite_get_texture(sprite_index, 0); +
    + shader_set(shd_Glass); +
    + if (gpu_get_tex_max_aniso_ext(_sampleIndex) != 8) +
    + { +
    + gpu_set_tex_max_aniso_ext(_sampleIndex, 8); +
    + } +
    + texture_set_stage(_sampleIndex , _spriteTex); +
    + shader_reset();

    +

    The above code sets the maximum level of anisotropy to 8 for the given shader texture sampler if it has not already been set to 8.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_set_tex_max_mip_ext.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_set_tex_max_mip_ext.htm index 6648f6e93..df4aa4e4f 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_set_tex_max_mip_ext.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_set_tex_max_mip_ext.htm @@ -4,7 +4,7 @@ gpu_set_tex_max_mip_ext - + @@ -16,35 +16,38 @@

    gpu_set_tex_max_mip_ext

    -

    With this function you can get the currently set maximum mipmap level which is to be used for a given shader sampler. You supply the index value for the shader sampler (as returned by the function shader_get_sampler_index(), and the function will return the current maximum mipmap level, where a value of 0 is the highest resolution, 1 is to use the first mipmap, 2 is the second etc... Note that this can be quite useful for avoiding bleeding artifacts when rendering textures, for example, setting the texture page border to 8px and then setting the max mipmap level to 3 will ensure you don't get any bleeding problems at greater render distances.

    +

    With this function you can get the currently set maximum mipmap level which is to be used for a given shader sampler. You supply the handle for the shader sampler (as returned by the function shader_get_sampler_index(), and the function will return the current maximum mipmap level, where a value of 0 is the highest resolution, 1 is to use the first mipmap, 2 is the second etc... Note that this can be quite useful for avoiding bleeding artifacts when rendering textures, for example, setting the texture page border to 8px and then setting the max mipmap level to 3 will ensure you don't get any bleeding problems at greater render distances.

     

    Syntax:

    gpu_set_tex_max_mip_ext(sampler_index, maxmip);

    - + + - + - + + - + - + + - +
    ArgumentTypeArgumentType Description
    sampler_indexsampler_indexShader Sampler Handle The index of the shader sampler to get
    maxmipmaxmipReal The maximum mipmap level value to use (default: 16)

     

    Returns:

    -

    +

    N/A

     

    Example:

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background");
    var _spriteTex = sprite_get_texture(sprite_index, 0);
    shader_set(shd_Glass);
    - if (gpu_get_tex_max_mip_ext(_sampleIndex) != 4)
    + if (gpu_get_tex_max_mip_ext(_sampleIndex) != 4)
    {
        gpu_set_tex_max_mip_ext(_sampleIndex, 4);
    }
    @@ -61,7 +64,7 @@

    Example:

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

    gpu_set_tex_min_mip_ext

    -

    With this function you can set the minimum mipmap level which is currently used for a given shader sampler. You supply the index value for the shader sampler (as returned by the function shader_get_sampler_index(), and then give a value, where 0 is for full resolution, 1 is for the first mipmap, 2 for the second etc...

    -

     

    -

    Syntax:

    -

    gpu_set_tex_min_mip_ext(sampler_index, minmip);

    - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    sampler_indexThe index of the shader sampler to get
    minmipThe minimum mipmap level to use
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background");
    - var _spriteTex = sprite_get_texture(sprite_index, 0);
    - shader_set(shd_Glass);
    - if (gpu_get_tex_min_mip_ext(_sampleIndex) != 0)
    - {
    -     gpu_set_tex_min_mip_ext(_sampleIndex, 0);
    - }
    - texture_set_stage(_sampleIndex , _spriteTex);
    - shader_reset();

    -

    The above code sets the minimum mipmap level to 0 for the given shader texture sampler if it has not already been set to 0.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: Mipmapping
    - + + + gpu_set_tex_min_mip_ext + + + + + + + + + + +

    gpu_set_tex_min_mip_ext

    +

    With this function you can set the minimum mipmap level which is currently used for a given shader sampler. You supply the handle for the shader sampler (as returned by the function shader_get_sampler_index(), and then give a value, where 0 is for full resolution, 1 is for the first mipmap, 2 for the second etc...

    +

    +

    Syntax:

    +

    gpu_set_tex_min_mip_ext(sampler_index, minmip);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    sampler_indexShader Sampler HandleThe shader sampler to get
    minmipRealThe minimum mipmap level to use
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background"); +
    + var _spriteTex = sprite_get_texture(sprite_index, 0); +
    + shader_set(shd_Glass); +
    + if (gpu_get_tex_min_mip_ext(_sampleIndex) != 0) +
    + { +
    + gpu_set_tex_min_mip_ext(_sampleIndex, 0); +
    + } +
    + texture_set_stage(_sampleIndex , _spriteTex); +
    + shader_reset();

    +

    The above code sets the minimum mipmap level to 0 for the given shader texture sampler if it has not already been set to 0.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_set_tex_mip_bias_ext.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_set_tex_mip_bias_ext.htm index e3cfbc19a..4cd6319a7 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_set_tex_mip_bias_ext.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_set_tex_mip_bias_ext.htm @@ -1,72 +1,80 @@ - + - - - gpu_set_tex_mip_bias_ext - - - - - - - - - - -

    gpu_set_tex_mip_bias_ext

    -

    With this function you can set the mipmap bias value for a given shader sampler. You supply the index value for the shader sampler (as returned by the function shader_get_sampler_index(), and then the bias value, where 0 is for no bias, 1 equals the first mipmap, 2 equals the second mipmap etc... This controls the rate at which the mip map is swapped and will generally make the shader textures blurrier the higher the value and the greater the "distance" being viewed. Note that this function can also take negative values too, in which case shader textures will be sharper over a greater distance the lower the value.

    -

     

    -

    Syntax:

    -

    gpu_set_tex_mip_bias_ext(sampler_index, bias);

    - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    sampler_indexThe index of the shader sampler to get
    biasThe mipmap bias value to use (default: 0)
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background");
    - var _spriteTex = sprite_get_texture(sprite_index, 0);
    - shader_set(shd_Glass);
    - if (gpu_get_tex_mip_bias_ext(_sampleIndex) != 0)
    - {
    -     gpu_set_tex_mip_bias_ext(_sampleIndex, 0);
    - }
    - texture_set_stage(_sampleIndex , _spriteTex);
    - shader_reset();

    -

    The above code sets the mip filter bias to 0 for the given shader texture sampler if it has not already been set to 0.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: Mipmapping
    - + + + gpu_set_tex_mip_bias_ext + + + + + + + + + +

    gpu_set_tex_mip_bias_ext

    +

    With this function you can set the mipmap bias value for a given shader sampler. You supply the handle for the shader sampler (as returned by the function shader_get_sampler_index(), and then the bias value, where 0 is for no bias, 1 equals the first mipmap, 2 equals the second mipmap etc... This controls the rate at which the mip map is swapped and will generally make the shader textures blurrier the higher the value and the greater the "distance" being viewed. Note that this function can also take negative values too, in which case shader textures will be sharper over a greater distance the lower the value.

    +

    +

    Syntax:

    +

    gpu_set_tex_mip_bias_ext(sampler_index, bias);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    sampler_indexShader Sampler HandleThe shader sampler to get
    biasRealThe mipmap bias value to use (default: 0)
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background"); +
    + var _spriteTex = sprite_get_texture(sprite_index, 0); +
    + shader_set(shd_Glass); +
    + if (gpu_get_tex_mip_bias_ext(_sampleIndex) != 0) +
    + { +
    + gpu_set_tex_mip_bias_ext(_sampleIndex, 0); +
    + } +
    + texture_set_stage(_sampleIndex , _spriteTex); +
    + shader_reset();

    +

    The above code sets the mip filter bias to 0 for the given shader texture sampler if it has not already been set to 0.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_set_tex_mip_enable_ext.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_set_tex_mip_enable_ext.htm index e5c2be3f1..5763f5879 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_set_tex_mip_enable_ext.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_set_tex_mip_enable_ext.htm @@ -1,98 +1,103 @@ - + - - - gpu_set_tex_mip_enable_ext - - - - - - - - - - -

    gpu_set_tex_mip_enable_ext

    -

    With this function you can set whether mipmapping is switched off, switched on for everything or switched on only for texture groups selected in the Texture Group Manager on a shader sampler. You supply the index value for the shader sampler (as returned by the function shader_get_sampler_index(), and then one of the constants listed below.

    - - - - - - - - - - - - - - - - - - - -
    ConstantDescription
    mip_offMipmapping is disabled.
    mip_onMipmapping for all textures is enabled.
    mip_markedonlyMipmapping is enabled for textures that have it enabled in the Texture Group options (default).
    -

     

    -

    Syntax:

    -

    gpu_set_tex_mip_enable_ext(sampler_index, setting);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    sampler_indexShader Sampler HandleThe index of the shader sampler to get
    settingMipmapping ConstantThe mipmap setting (a constant, default: mip_markedonly)
    -

     

    -

    Returns:

    -

    N/A

    -

    -

    Example:

    -

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background");
    - var _spriteTex = sprite_get_texture(sprite_index, 0);
    - shader_set(shd_Glass);
    - if (gpu_get_tex_mip_enable_ext(_sampleIndex) != mip_on)
    - {
    -     gpu_set_tex_mip_enable_ext(_sampleIndex, mip_on);
    - }
    - texture_set_stage(_sampleIndex , _spriteTex);
    - shader_reset();

    -

    The above code enables mipmapping for the given shader texture sampler if it has not already been enabled.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: Mipmapping
    - + + + gpu_set_tex_mip_enable_ext + + + + + + + + + +

    gpu_set_tex_mip_enable_ext

    +

    With this function you can set whether mipmapping is switched off, switched on for everything or switched on only for texture groups selected in the Texture Group Manager on a shader sampler. You supply the handle for the shader sampler (as returned by the function shader_get_sampler_index(), and then one of the constants listed below.

    + + + + + + + + + + + + + + + + + + + +
    ConstantDescription
    mip_offMipmapping is disabled.
    mip_onMipmapping for all textures is enabled.
    mip_markedonlyMipmapping is enabled for textures that have it enabled in the Texture Group options (default).
    +

    +

    Syntax:

    +

    gpu_set_tex_mip_enable_ext(sampler_index, setting);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    sampler_indexShader Sampler HandleThe shader sampler to get
    settingMipmapping ConstantThe mipmap setting (a constant, default: mip_markedonly)
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background"); +
    + var _spriteTex = sprite_get_texture(sprite_index, 0); +
    + shader_set(shd_Glass); +
    + if (gpu_get_tex_mip_enable_ext(_sampleIndex) != mip_on) +
    + { +
    + gpu_set_tex_mip_enable_ext(_sampleIndex, mip_on); +
    + } +
    + texture_set_stage(_sampleIndex , _spriteTex); +
    + shader_reset();

    +

    The above code enables mipmapping for the given shader texture sampler if it has not already been enabled.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_set_tex_mip_filter_ext.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_set_tex_mip_filter_ext.htm index 2b2abfbd9..b5ebebdaf 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_set_tex_mip_filter_ext.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Mipmapping/gpu_set_tex_mip_filter_ext.htm @@ -1,100 +1,105 @@ - + - - - gpu_set_tex_mip_filter_ext - - - - - - - - - - -

    gpu_set_tex_mip_filter_ext

    -

    With this function you can set the mip filter mode for a given shader sampler. You supply the index value for the shader sampler (as returned by the function shader_get_sampler_index(), and then one of the mode value constants listed below.

    -

     

    - - - - - - - - - - - - - - - - - - - -
    ConstantDescription
    tf_pointThis means that blending between mipmap levels is disabled, which can cause visible texture transitions, but gives the best performance.
    tf_linearThis means that blending between mipmap levels is enabled (this is also known as trilinear filtering), which smooths the texture transitions, but it will give a minor hit to performance.
    tf_anisotropicThis means that anisotropic filtering is enabled, which greatly improves texture transition quality and can reduce the blurring visible with other filtering modes, but it has the highest hit on performance.
    -

     

    -

    Syntax:

    -

    gpu_set_tex_mip_filter_ext(sampler_index, filter);

    -

     

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    sampler_indexShader Sampler HandleThe index of the shader sampler to get.
    filterMipmapping Filter ConstantThe mip filter mode to use (a constant, default: tf_point).
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background");
    - var _spriteTex = sprite_get_texture(sprite_index, 0);
    - shader_set(shd_Glass);
    - if (gpu_get_tex_mip_filter_ext(_sampleIndex) != tf_point)
    - {
    -     gpu_set_tex_mip_filter_ext(_sampleIndex, tf_point);
    - }
    - texture_set_stage(_sampleIndex, _spriteTex);
    - shader_reset();

    -

    The above code sets the mip filter mode to tf_point (disabling mipmapping) for the given shader texture sampler if it has not already been set.

    -

     

    -

     

    -

     

    -
    -
    -
    -
    Back: Mipmapping
    - + + + gpu_set_tex_mip_filter_ext + + + + + + + + + +

    gpu_set_tex_mip_filter_ext

    +

    With this function you can set the mip filter mode for a given shader sampler. You supply the handle for the shader sampler (as returned by the function shader_get_sampler_index(), and then one of the mode value constants listed below.

    +

    + + + + + + + + + + + + + + + + + + + +
    ConstantDescription
    tf_pointThis means that blending between mipmap levels is disabled, which can cause visible texture transitions, but gives the best performance.
    tf_linearThis means that blending between mipmap levels is enabled (this is also known as trilinear filtering), which smooths the texture transitions, but it will give a minor hit to performance.
    tf_anisotropicThis means that anisotropic filtering is enabled, which greatly improves texture transition quality and can reduce the blurring visible with other filtering modes, but it has the highest hit on performance.
    +

    +

    Syntax:

    +

    gpu_set_tex_mip_filter_ext(sampler_index, filter);

    +

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    sampler_indexShader Sampler HandleThe shader sampler to get.
    filterMipmapping Filter ConstantThe mip filter mode to use (a constant, default: tf_point).
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    var _sampleIndex = shader_get_sampler_index(shd_Glass, "s_Background"); +
    + var _spriteTex = sprite_get_texture(sprite_index, 0); +
    + shader_set(shd_Glass); +
    + if (gpu_get_tex_mip_filter_ext(_sampleIndex) != tf_point) +
    + { +
    + gpu_set_tex_mip_filter_ext(_sampleIndex, tf_point); +
    + } +
    + texture_set_stage(_sampleIndex, _spriteTex); +
    + shader_reset();

    +

    The above code sets the mip filter mode to tf_point (disabling mipmapping) for the given shader texture sampler if it has not already been set.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © 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_Emitters/Particle_Emitters.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Emitters/Particle_Emitters.htm index fe1c8e1e9..34644cb95 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Emitters/Particle_Emitters.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Emitters/Particle_Emitters.htm @@ -1,56 +1,53 @@ - + - - - Particle Emitters - - - - - - - - - - -

    Particle Emitters

    -

    Particle emitters are used by GameMaker to emit particles over an area of the screen which can have different forms and distributions. They can also either create a continuous stream of particles or they can burst out a number of particles all at once, depending on the way the functions are used.

    -
    -

    Since a particle emitter is a dynamically created resource, you must create it and store the returned index in a variable to reference the emitter in all further function calls, and it is very important that you also destroy the emitter when it is no longer needed or else you will have a memory leak that will slow down and eventually crash your game.

    -

    Particle emitters are tied to a particle system at creation so destroying the particle system will destroy its associated emitters as well. However you can also individually destroy emitters while the system continues to exist.

    -

    Function Reference

    -

       Each of these functions takes the index of the particle system to which it belongs as a first argument.

    - -

     

    -

     

    -
    -
    -
    -
    Back: Particles
    - + + + Particle Emitters + + + + + + + + + +

    Particle Emitters

    +

    Particle emitters are used by GameMaker to emit particles over an area of the screen which can have different forms and distributions. They can also either create a continuous stream of particles or they can burst out a number of particles all at once, depending on the way the functions are used.

    +
    +

    Since a particle emitter is a dynamically created resource, you must create it and store the returned index in a variable to reference the emitter in all further function calls, and it is very important that you also destroy the emitter when it is no longer needed or else you will have a memory leak that will slow down and eventually crash your game.

    +

    Particle emitters are tied to a particle system at creation so destroying the particle system will destroy its associated emitters as well. However you can also individually destroy emitters while the system continues to exist.

    +

    Function Reference

    +

    Each of these functions takes the particle system to which it belongs as a first argument.

    + +

    +

    +
    +
    +
    +
    Back: Particles
    + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Emitters/part_emitter_create.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Emitters/part_emitter_create.htm index df6a5f66e..e35615b85 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Emitters/part_emitter_create.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Emitters/part_emitter_create.htm @@ -17,7 +17,7 @@

    part_emitter_create

    This function creates a new particle emitter in the given particle system.

    -

    The function will return the index value for the new emitter which must be stored in a variable and used in all further functions that reference the emitter, and the emitter itself must be destroyed when no longer being used to prevent memory leaks (this can be achieved using the specific emitter destroy functions or by destroying the whole particle system that the emitter belongs to).

    +

    The function will return the handle for the new emitter which must be stored in a variable and used in all further functions that reference the emitter, and the emitter itself must be destroyed when no longer being used to prevent memory leaks (this can be achieved using the specific emitter destroy functions or by destroying the whole particle system that the emitter belongs to).

     Emitter IDs returned by this function are reused, e.g. if you first create three particle emitters they will have IDs 0, 1 and 2 assigned. If you then destroy the second emitter (which got an ID of 1) using part_emitter_destroy and then create another emitter, then this emitter will reuse the ID of 1. Since emitter ID 2 is in use, the next emitter will get an ID of 3, and so on.

    Syntax:

    part_emitter_create(ps);

    @@ -30,14 +30,14 @@

    Syntax:

    ps - Particle System ID + Particle System Instance The particle system to create the emitter in.

     

    Returns:

    -

    Particle Emitter ID

    +

    Particle Emitter ID

     

    Example:

    p_emit1 = part_emitter_create(Sname);

    @@ -51,7 +51,7 @@

    Example:

    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    - - +--> \ No newline at end of file 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 c407bad3c..988e61d71 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,66 +1,67 @@ - + - - - 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 index of the 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

    +

    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.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © 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 87d9cd400..23a55d273 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,67 +1,68 @@ - + - - - 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 index of the 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

    +

    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.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © 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 cbfeba760..a1179cea9 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,86 @@ - + - - - 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 index of the 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 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.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © 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 f2a9c7124..eef9cddc0 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,93 +1,94 @@ - + - - - 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 index of the 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 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.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © 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 4baf2d633..5f2e78c19 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,72 +1,71 @@ - + - - - 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 index of the 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 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.

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © 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 075a951f2..0622dc206 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,68 +1,65 @@ - + - - - 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 index of the 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 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".

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © 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 1981e57cd..e6d6fd01b 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 index of the 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, 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.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © 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 c901b8f3d..82fc1a829 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,64 +1,61 @@ - + - - - 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 index of the 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

    +

    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.

    +

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © 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 be322001b..5f59c6cef 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,13 +1,12 @@ - + - - - 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 index of the 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_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.

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © 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_create.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_create.htm index 2e21e3f38..5a8027642 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_create.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_create.htm @@ -4,7 +4,7 @@ part_system_create - + @@ -16,9 +16,9 @@

    part_system_create

    -

    This function creates a new particle system and returns its unique index number.

    +

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

    The system will be assigned a managed layer and will be set to have a depth of 0. Managed layers are not accessible to the user and are used only for internal management when depth is used instead of layers. Normally you would use the function part_system_create_layer instead of this one.

    -

    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.

    +

    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.

     

    Syntax:

    part_system_create([partsys]);

    @@ -31,14 +31,14 @@

    Syntax:

    partsys - Particle System Asset + Particle System Asset  The particle system asset to create an instance of

     

    Returns:

    -

    Particle System ID

    +

    Particle System Instance

     

    Example:

    global.p_sys = part_system_create();

    @@ -52,7 +52,7 @@

    Example:

    -
    © 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 unique index number.

    +

    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.

    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).

    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 5745bc52e..ad2ceab41 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,68 +1,66 @@ - + - - - 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 index of the 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
    -
    © 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_destroy.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_destroy.htm index 56cd11e78..cd59d6975 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,67 +1,68 @@ - + - - - 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 index of the 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

    +

    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.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © 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_draw_order.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_draw_order.htm index 61c229f2e..dd301b078 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_draw_order.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Systems/part_system_draw_order.htm @@ -1,71 +1,68 @@ - + - - - part_system_draw_order - - - - - - - - - - - -

    part_system_draw_order

    -

    With this function you can set the way in which particles are drawn when created on the screen. The default system uses an old > new look (the function is set to true), where old particles are drawn at a higher depth than newer ones and so appear "beneath" them new particles, but by setting this function to false you can reverse this order and have the new particles drawn higher and so appear "beneath" the older ones. The images below illustrate this, with the image on the left being the default value of true and the image on the right being false:

    -
    Old to new particle example New to old particle example
    -

     When the particles are being drawn with an additive blend mode, the effect of this function may not always be obvious.

    -

     

    -

    Syntax:

    -

    part_system_draw_order(ind, oldtonew);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indParticle System IDThe index of the particle system to change.
    oldtonewBooleanWhether old particles should be drawn behind newer ones (true) or vice versa (false).
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    mysystem = part_system_create();
    - part_system_draw_order(mysystem, true); -

    -

    This will create a new particle system with the index mysystem, and then it sets particles to draw newer particles atop older ones.

    -

     

    -

     

    -
    -
    -
    - - + + + part_system_draw_order + + + + + + + + + + +

    part_system_draw_order

    +

    With this function you can set the way in which particles are drawn when created on the screen. The default system uses an old > new look (the function is set to true), where old particles are drawn at a higher depth than newer ones and so appear "beneath" them new particles, but by setting this function to false you can reverse this order and have the new particles drawn higher and so appear "beneath" the older ones. The images below illustrate this, with the image on the left being the default value of true and the image on the right being false:

    +
    Old to new particle example New to old particle example
    +

    When the particles are being drawn with an additive blend mode, the effect of this function may not always be obvious.

    +

    +

    Syntax:

    +

    part_system_draw_order(ind, oldtonew);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indParticle System IDThe particle system to change.
    oldtonewBooleanWhether old particles should be drawn behind newer ones (true) or vice versa (false).
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    mysystem = part_system_create(); +
    + part_system_draw_order(mysystem, true);

    +

    This will create a new particle system with the index mysystem, and then it sets particles to draw newer particles atop older ones.

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © 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 e3bc1800a..cf6ac3590 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,69 +1,71 @@ - + - - - 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 index of the 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 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.

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © 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 e2d337e50..1909f3700 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 index of the 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

    +

    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.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © 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 e190ab3cb..567d8b90d 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 @@ -4,7 +4,7 @@ part_system_get_layer - + @@ -16,7 +16,7 @@

    part_system_get_layer

    -

    This function can be used to retrieve the unique layer ID value for the given particle system. You supply the particle system ID value (as returned by the function part_system_create_layer()) and the function will return the ID value of the 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.

     

    Syntax:

    part_system_get_layer(ind);

    @@ -29,14 +29,14 @@

    Syntax:

    ind - Particle System ID - The particle system ID value to get the layer ID of + Particle System Instance + The particle system handle to get the layer handle of

     

    Returns:

    -

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

    +

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

     

    Example:

    if (part_system_get_layer(global.p_sys) != "effects_layer")
    @@ -54,7 +54,7 @@

    Example:

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

    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 ID value (as returned by the function part_system_create_layer()) and then 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" - as defined in the room editor), and the system will be moved to the new 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.

     

    Syntax:

    part_system_layer(ps, layer);

    @@ -28,13 +28,13 @@

    Syntax:

    ps - Particle System ID - The particle system ID + Particle System Instance + The particle system handle layer - String or Layer ID - The new layer ID + String or Layer + The new layer handle @@ -58,7 +58,7 @@

    Example:

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

    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 index of the 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

    +

    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

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © 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 150764cfe..de2be2248 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 index of the 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 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.

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © 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_sprite.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Types/part_type_sprite.htm index 64ca8de04..2765cf58a 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Types/part_type_sprite.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/Particle_Types/part_type_sprite.htm @@ -1,101 +1,109 @@ - + - - - part_type_sprite - - - - - - - - - - -

    part_type_sprite

    -

    This function sets a particle type to use a custom sprite from the game assets.

    -

     Use part_type_shape to use one of the built-in particle shapes instead.

    -

     This function can be used to change the sprite of existing particles of a particle type.

    -

    Usage Notes

    -
      -
    • You can select the sprite and then tell GameMaker to use the sprite and animate it or not.
      • -
    • If you choose to animate it you can also choose to stretch the animation; i.e. have the sub-images changed at an interval such that the animation will begin and end at the beginning and end of the lifetime of each particle created (so that if you have a lifetime set to a 15 step minimum and a 30 step maximum, no matter what value the lifetime has the animation will be made to fit, with it running faster for the shorter lifetimes and slower for the longer).
      • -
    • You can also select to choose a random sub-image so that if the sprite isn't animated, a different image will be chosen at random to create the sprite, or if the particle is animated it will start the animation at a random point.
      • -
    • You can use part_type_subimage to change the sub-image of the sprite to create the particle with, or start the animation with, in case random is false.
      • -
    -

     

    -

    Syntax:

    -

    part_type_sprite(ind, sprite, animate, stretch, random);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    indParticle Type IDThe index of the particle type to change
    spriteSprite AssetThe index of the sprite to set the particle type to
    animateBooleanWhether to follow the sprite's animation normally (true) or not (false)
    stretchBooleanWhether to stretch the sprite's animation to match the particle lifespan (true) or not (false), as set using part_type_life
    randomBooleanWhether to choose a random sub-image at the start (true) or not (false)
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    global.p1 = part_type_create();
    - part_type_sprite(global.p1 , spr_Coins, 1, 0, 0);
    - part_type_size(global.p1, 1, 3, 0, 0);
    - part_type_scale(global.p1, 1, 1);
    - part_type_colour1(global.p1, c_white);
    - part_type_alpha2(global.p1, 1, 0);
    - part_type_speed(global.p1, 2, 4, 0, 0);
    - part_type_direction(global.p1, 0, 180, 0, 0);
    - part_type_gravity(global.p1, 0.20, 270);
    - part_type_orientation(global.p1, 0, 0, 0, 0, 1);
    - part_type_blend(global.p1, 1);
    - part_type_life(global.p1, 15, 60);

    -

    The above code sets the particle type indexed in the global variable "p1" to the shape of the sprite indexed in "spr_Coins", and then sets various other particle properties.

    -

     

    -

     

    -
    -
    -
    - - + + + part_type_sprite + + + + + + + + + +

    part_type_sprite

    +

    This function sets a particle type to use a custom sprite from the game assets.

    +

    Use part_type_shape to use one of the built-in particle shapes instead.

    +

    This function can be used to change the sprite of existing particles of a particle type.

    +

    Usage Notes

    +
      +
    • You can select the sprite and then tell GameMaker to use the sprite and animate it or not.
      • +
    • If you choose to animate it you can also choose to stretch the animation; i.e. have the sub-images changed at an interval such that the animation will begin and end at the beginning and end of the lifetime of each particle created (so that if you have a lifetime set to a 15 step minimum and a 30 step maximum, no matter what value the lifetime has the animation will be made to fit, with it running faster for the shorter lifetimes and slower for the longer).
      • +
    • You can also select to choose a random sub-image so that if the sprite isn't animated, a different image will be chosen at random to create the sprite, or if the particle is animated it will start the animation at a random point.
      • +
    • You can use part_type_subimage to change the sub-image of the sprite to create the particle with, or start the animation with, in case random is false.
      • +
    +

    +

    Syntax:

    +

    part_type_sprite(ind, sprite, animate, stretch, random);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    indParticle Type IDThe index of the particle type to change
    spriteSprite AssetThe sprite to set the particle type to
    animateBooleanWhether to follow the sprite's animation normally (true) or not (false)
    stretchBooleanWhether to stretch the sprite's animation to match the particle lifespan (true) or not (false), as set using part_type_life
    randomBooleanWhether to choose a random sub-image at the start (true) or not (false)
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    global.p1 = part_type_create(); +
    + part_type_sprite(global.p1 , spr_Coins, 1, 0, 0); +
    + part_type_size(global.p1, 1, 3, 0, 0); +
    + part_type_scale(global.p1, 1, 1); +
    + part_type_colour1(global.p1, c_white); +
    + part_type_alpha2(global.p1, 1, 0); +
    + part_type_speed(global.p1, 2, 4, 0, 0); +
    + part_type_direction(global.p1, 0, 180, 0, 0); +
    + part_type_gravity(global.p1, 0.20, 270); +
    + part_type_orientation(global.p1, 0, 0, 0, 0, 1); +
    + part_type_blend(global.p1, 1); +
    + part_type_life(global.p1, 15, 60);

    +

    The above code sets the particle type indexed in the global variable "p1" to the shape of the sprite indexed in "spr_Coins", and then sets various other particle properties.

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    -
    © 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_get_info.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/particle_get_info.htm index fe4954d5b..42ced143d 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/particle_get_info.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Particles/particle_get_info.htm @@ -1,569 +1,593 @@ - + - - - particle_get_info - - - - - - - - - - -

    particle_get_info

    -

    This function returns a struct with information about a Particle System Asset created using The Particle System Editor.

    -

    The returned struct is a Particle System Info Struct, which contains an Array of Particle Emitter Info Structs. Each of these emitter structs stores info on the particle type that the emitter uses in its parttype variable, which contains a Particle Type Info Struct.

    -

     If no valid Particle System Asset is passed to the function, GameMaker will throw an error.

    -

    In a simplified way, the contents of the struct returned by this function look something like the following:

    -

    part_sys_info_struct =
    - {
    -     emitters:
    -     [
    -         {
    -             parttype:
    -             {
    -                 // Particle type properties...
    -             }
    -             // All other particle emitter properties...
    -         }
    -         // More emitters...
    -     ]
    -     // All other particle system properties...
    - };

    -

    The tables below list all variables that are available in each of these three structs.

    -

    Particle System Info

    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Particle System Info Struct
    Variable NameData TypeDescription
    nameStringThe name of the particle system asset.
    xoriginRealThe X origin of the particle system.
    yoriginRealThe Y origin of the particle system.
    global_spaceBooleanWhether this particle system has global space particles enabled (see part_system_global_space).
    oldtonewBooleanWhether old particles should be drawn behind new ones (true) or not (false).
    emittersArray of Particle Emitter Info StructAn array of emitter info structs, ordered the same as in The Particle System Editor.
    -
    -

    Particle Emitter Info

    -
    - - + + + particle_get_info + + + + + + + + + + +

    particle_get_info

    +

    This function returns a struct with information about a Particle System Asset created using The Particle System Editor.

    +

    The returned struct is a Particle System Info Struct, which contains an Array of Particle Emitter Info Structs. Each of these emitter structs stores info on the particle type that the emitter uses in its parttype variable, which contains a Particle Type Info Struct.

    +

    If no valid Particle System Asset is passed to the function, GameMaker will throw an error.

    +

    In a simplified way, the contents of the struct returned by this function look something like the following:

    +

    part_sys_info_struct = +
    + { +
    + emitters: +
    + [ +
    + { +
    + parttype: +
    + { +
    + // Particle type properties... +
    + } +
    + // All other particle emitter properties... +
    + } +
    + // More emitters... +
    + ] +
    + // All other particle system properties... +
    + };

    +

    The tables below list all variables that are available in each of these three structs.

    +

    Particle System Info

    +
    +
    Particle Emitter Info Struct
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Particle System Info Struct
    Variable NameData TypeDescription
    nameStringThe name of the particle system asset.
    xoriginRealThe X origin of the particle system.
    yoriginRealThe Y origin of the particle system.
    global_spaceBooleanWhether this particle system has global space particles enabled (see part_system_global_space).
    oldtonewBooleanWhether old particles should be drawn behind new ones (true) or not (false).
    emittersArray of Particle Emitter Info StructAn array of emitter info structs, ordered the same as in The Particle System Editor.
    +
    +

    Particle Emitter Info

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Particle Emitter Info Struct
    Variable NameData TypeDescription
    indParticle Emitter IDThe ID of the particle emitter.
    nameStringThe name of the particle emitter.
    modeParticle Emitter Mode ConstantThe mode in which to emit particles. Either ps_mode_stream or ps_mode_burst.
    enabledBooleanWhether the particle emitter is enabled.
    numberRealThe number of particles to create every frame if mode is ps_mode_stream or to create only once if mode is ps_mode_burst. Density (percent coverage) when in relative mode.
    relativeBooleanWhether the emitter is in relative mode, in which the number of particles created by the emitter is relative to the area of its region (see part_emitter_relative).
    xminRealThe X coordinate of the left side of the emitter's region.
    xmaxRealThe X coordinate of the right side of the emitter's region.
    yminRealThe Y coordinate of the top of the emitter's region.
    ymaxRealThe Y coordinate of the bottom of the emitter's region.
    distributionParticle Emitter Distribution ConstantThe distribution style of the particles. One of the ps_distr_* constants.
    shapeParticle Emitter Shape ConstantThe shape of the emitter's region. One of the ps_shape_* constants.
    parttypeParticle Type Info StructThe particle type info struct containing information this emitter's particle type.
    delay_minRealThe minimum delay between particle bursts in stream mode, expressed in delay_unit.
    delay_maxRealThe maximum delay between particle bursts in stream mode, expressed in delay_unit.
    delay_unitTime Source Unit Constant The unit in which delay_min and delay_max are expressed
    interval_minRealThe minimum time between particle bursts in stream mode, expressed in interval_unit.
    interval_maxReal The maximum time between particle bursts in stream mode, expressed in interval_unit.
    interval_unitTime Source Unit ConstantThe unit in which interval_min and interval_max are expressed.
    +
    +

    Particle Type Info

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Particle Type Info Struct
    Variable NameData TypeDescription
    General
    indParticle Type IDThe index of the particle type. This can be used e.g. with the function part_particles_create.
    Shape / Sprite
    spriteSprite AssetThe sprite that the particle type uses or -1.
    frameRealThe sprite subimage in case a sprite is used.
    animateBooleanIf true then the sprite is animated, starting from the frame subimage.
    stretchBooleanIf true then the animation is stretched over the particle's lifetime.
    randomBooleanIf true then a random subimage is used instead of frame.
    shapeParticle Shape ConstantThe particle shape. One of the pt_shape_* constants. Used only if sprite is -1.
    Size
    size_xminRealThe minimum size a particle of this type can have on the X axis when it is created (the size is determined randomly for each particle and can vary from size_xmin to size_xmax).
    size_yminRealThe minimum size a particle of this type can have on the Y axis when it is created (the size is determined randomly for each particle and can vary from size_ymin to size_ymax).
    size_xmaxRealThe maximum size a particle of this type can have on the X axis when it is created (the size is determined randomly for each particle and can vary from size_xmin to size_xmax).
    size_ymaxRealThe maximum size a particle of this type can have on the Y axis when it is created (the size is determined randomly for each particle and can vary from size_ymin to size_ymax).
    size_xincrRealThe value to increase/decrease the particle size on the X axis by each frame.
    size_yincrRealThe value to increase/decrease the particle size on the Y axis by each frame.
    size_xwiggleRealValue randomly added or subtracted from the particle's X size each frame.
    size_ywiggleRealValue randomly added or subtracted from the particle's Y size each frame.
    Scale
    xscaleRealThe X scale of the particle image (sprite or shape).
    yscaleRealThe Y scale of the particle image (sprite or shape).
    Life
    life_minRealThe minimum life of particles of this type (in number of frames).
    life_maxRealThe maximum life of particles of this type (in number of frames).
    Secondary Particles
    death_typeParticle Type IDThe type of particle spawned on death or -1.
    death_numberRealThe number of particles spawned on death.
    step_typeParticle Type IDThe type of particle spawned each step or -1.
    step_numberRealThe number of particles spawned each step.
    Speed
    speed_minRealThe minimum speed (in pixels per frame) of the particle when it's created (this starting speed is determined randomly for each particle and ranges from speed_min to speed_max).
    speed_maxRealThe maximum speed (in pixels per frame) of the particle when it's created (this starting speed is determined randomly for each particle and ranges from speed_min to speed_max).
    speed_incrRealThe value to increase/decrease the particle speed by each frame.
    speed_wiggleRealA value randomly added or subtracted from the particle speed each frame.
    Direction
    dir_minRealThe minimum direction (in degrees) for a particle when it's created (this starting direction is determined randomly for each particle and ranges from dir_min to dir_max).
    dir_maxRealThe maximum direction (in degrees) for a particle when it's created (this starting direction is determined randomly for each particle and ranges from dir_min to dir_max).
    dir_incrRealThe value to increase/decrease the particle direction by each frame.
    dir_wiggleRealA value randomly added or subtracted from the particle direction each frame.
    Gravity
    grav_amountRealThe amount of gravity applied to the particle each frame (in pixels per frame).
    grav_dirRealThe gravity direction.
    Orientation
    ang_minRealThe minimum starting angle (in degrees) of the particle sprite when created (this starting angle is determined randomly for each particle and ranges from ang_min to ang_max).
    ang_maxRealThe maximum starting angle (in degrees) of the particle sprite when created (this starting angle is determined randomly for each particle and ranges from ang_min to ang_max).
    ang_incrRealThe value to increase/decrease the particle angle by each frame.
    ang_wiggleRealA value randomly added or subtracted from the particle angle each frame.
    ang_relativeBooleanIf true then the particle angle is relative to its direction.
    Color & Alpha
    color1ColourThe color of the particle when created.
    color2ColourThe color of the particle when halfway through its lifespan.
    color3ColourThe color of the particle at the end of its lifespan.
    alpha1RealThe alpha of the particle when created.
    alpha2RealThe alpha of the particle when halfway through its lifespan.
    alpha3RealThe alpha of the particle at the end of its lifespan.
    additiveBooleanIf true then the particle is drawn with additive blending (i.e. using the Blend Mode Constant bm_add).
    +
    +

    +

    Finally there is also a constant for the particle emitter mode:

    + + - - - + + - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + - - - - - - - - - - - - - + +
    Particle Emitter Mode Constant
    Variable NameData TypeConstant Description
    indParticle Emitter IDThe ID of the particle emitter.
    nameStringThe name of the particle emitter.
    modeParticle Emitter Mode ConstantThe mode in which to emit particles. Either ps_mode_stream or ps_mode_burst.
    enabledBooleanWhether the particle emitter is enabled.
    numberRealThe number of particles to create every frame if mode is ps_mode_stream or to create only once if mode is ps_mode_burst. Density (percent coverage) when in relative mode.
    relativeBooleanWhether the emitter is in relative mode, in which the number of particles created by the emitter is relative to the area of its region (see part_emitter_relative).
    xminRealThe X coordinate of the left side of the emitter's region.
    xmaxRealThe X coordinate of the right side of the emitter's region.
    yminRealThe Y coordinate of the top of the emitter's region.
    ymaxRealThe Y coordinate of the bottom of the emitter's region.
    distributionParticle Emitter Distribution ConstantThe distribution style of the particles. One of the ps_distr_* constants.
    shapeParticle Emitter Shape ConstantThe shape of the emitter's region. One of the ps_shape_* constants.
    parttypeParticle Type Info StructThe particle type info struct containing information this emitter's particle type.
    delay_minRealThe minimum delay between particle bursts in stream mode, expressed in delay_unit.
    delay_maxRealThe maximum delay between particle bursts in stream mode, expressed in delay_unit.
    delay_unitTime Source Unit Constant The unit in which delay_min and delay_max are expressedps_mode_streamThe particle emitter streams the given number of particles continuously (see part_emitter_stream)
    interval_minRealThe minimum time between particle bursts in stream mode, expressed in interval_unit.
    interval_maxReal The maximum time between particle bursts in stream mode, expressed in interval_unit.
    interval_unitTime Source Unit ConstantThe unit in which interval_min and interval_max are expressed.ps_mode_burstThe particle emitter emits a single burst of the given number of particles (see part_emitter_burst)
    -
    -

    Particle Type Info

    -
    - - +

    +

    Syntax:

    +

    particle_get_info(partsys);

    +
    Particle Type Info Struct
    - - - + + + - - + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + +
    Variable NameData TypeArgumentType Description
    General
    indParticle Type IDThe index of the particle type. This can be used e.g. with the function part_particles_create.
    Shape / Sprite
    spriteSprite AssetThe index of the sprite that the particle type uses or -1.
    frameRealThe sprite subimage in case a sprite is used.
    animateBooleanIf true then the sprite is animated, starting from the frame subimage.
    stretchBooleanIf true then the animation is stretched over the particle's lifetime.
    randomBooleanIf true then a random subimage is used instead of frame.
    shapeParticle Shape ConstantThe particle shape. One of the pt_shape_* constants. Used only if sprite is -1.
    Size
    size_xminRealThe minimum size a particle of this type can have on the X axis when it is created (the size is determined randomly for each particle and can vary from size_xmin to size_xmax).
    size_yminRealThe minimum size a particle of this type can have on the Y axis when it is created (the size is determined randomly for each particle and can vary from size_ymin to size_ymax).
    size_xmaxRealThe maximum size a particle of this type can have on the X axis when it is created (the size is determined randomly for each particle and can vary from size_xmin to size_xmax).
    size_ymaxRealThe maximum size a particle of this type can have on the Y axis when it is created (the size is determined randomly for each particle and can vary from size_ymin to size_ymax).
    size_xincrRealThe value to increase/decrease the particle size on the X axis by each frame.
    size_yincrRealThe value to increase/decrease the particle size on the Y axis by each frame.
    size_xwiggleRealValue randomly added or subtracted from the particle's X size each frame.
    size_ywiggleRealValue randomly added or subtracted from the particle's Y size each frame.
    Scale
    xscaleRealThe X scale of the particle image (sprite or shape).
    yscaleRealThe Y scale of the particle image (sprite or shape).
    Life
    life_minRealThe minimum life of particles of this type (in number of frames).
    life_maxRealThe maximum life of particles of this type (in number of frames).
    Secondary Particles
    death_typeParticle Type IDThe type of particle spawned on death or -1.
    death_numberRealThe number of particles spawned on death.
    step_typeParticle Type IDThe type of particle spawned each step or -1.
    step_numberRealThe number of particles spawned each step.
    Speed
    speed_minRealThe minimum speed (in pixels per frame) of the particle when it's created (this starting speed is determined randomly for each particle and ranges from speed_min to speed_max).
    speed_maxRealThe maximum speed (in pixels per frame) of the particle when it's created (this starting speed is determined randomly for each particle and ranges from speed_min to speed_max).
    speed_incrRealThe value to increase/decrease the particle speed by each frame.
    speed_wiggleRealA value randomly added or subtracted from the particle speed each frame.
    Direction
    dir_minRealThe minimum direction (in degrees) for a particle when it's created (this starting direction is determined randomly for each particle and ranges from dir_min to dir_max).
    dir_maxRealThe maximum direction (in degrees) for a particle when it's created (this starting direction is determined randomly for each particle and ranges from dir_min to dir_max).
    dir_incrRealThe value to increase/decrease the particle direction by each frame.
    dir_wiggleRealA value randomly added or subtracted from the particle direction each frame.
    Gravity
    grav_amountRealThe amount of gravity applied to the particle each frame (in pixels per frame).
    grav_dirRealThe gravity direction.
    Orientation
    ang_minRealThe minimum starting angle (in degrees) of the particle sprite when created (this starting angle is determined randomly for each particle and ranges from ang_min to ang_max).
    ang_maxRealThe maximum starting angle (in degrees) of the particle sprite when created (this starting angle is determined randomly for each particle and ranges from ang_min to ang_max).
    ang_incrRealThe value to increase/decrease the particle angle by each frame.
    ang_wiggleRealA value randomly added or subtracted from the particle angle each frame.
    ang_relativeBooleanIf true then the particle angle is relative to its direction.
    Color & Alpha
    color1ColourThe color of the particle when created.
    color2ColourThe color of the particle when halfway through its lifespan.
    color3ColourThe color of the particle at the end of its lifespan.
    alpha1RealThe alpha of the particle when created.
    alpha2RealThe alpha of the particle when halfway through its lifespan.
    alpha3RealThe alpha of the particle at the end of its lifespan.
    additiveBooleanIf true then the particle is drawn with additive blending (i.e. using the Blend Mode Constant bm_add).partsysParticle System AssetThe particle system asset to get the info from.
    -
    -

     

    -

    Finally there is also a constant for the particle emitter mode: 

    - - - - - - - - - - - - - - - - - - - - -
    Particle Emitter Mode Constant
    ConstantDescription
    ps_mode_streamThe particle emitter streams the given number of particles continuously (see part_emitter_stream)
    ps_mode_burstThe particle emitter emits a single burst of the given number of particles (see part_emitter_burst)
    -

     

    -

    Syntax:

    -

    particle_get_info(partsys);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    partsysParticle System AssetThe particle system asset to get the info from.
    -

     

    -

    Returns:

    -

    Particle System Info Struct

    -

     

    -

    Example 1: Particle Type Info

    -

    var _particle_info = particle_get_info(ps_Clouds);
    - var _asset_name = _particle_info.name;
    -
    - var _arr_emitters = _particle_info.emitters;
    - if (array_length(_arr_emitters) > 0)
    - {
    -     var _type_info = _arr_emitters[0].parttype;
    -    
    -     if (_type_info.additive)
    -     {
    -         show_debug_message("The first emitter in {0} creates shiny particles!", _asset_name);
    -     }
    - } -

    -

    The above code first gets information from an existing Particle System Asset ps_Clouds using particle_get_info and assigns the returned struct to a temporary variable _particle_info. It then looks up the emitters in the particle system through the Particle System Info Struct's emitters variable. If the particle system contains any emitters (i.e. the array's length is greater than 0), the first emitter's parttype variable is assigned to a temporary variable _type_info and checked for additive blending (bm_add). Finally a debug message is shown if additive blending is used for the particle type.

    -

     

    -

    Example 2: Listing Emitter Names

    -

    var _particle_info = particle_get_info(ps_Environment);
    - var _asset_name = _particle_info.name;
    -
    - var _emitter_names = array_map(_particle_info.emitters, function(_element, _index) { return _element.name; });
    - _emitter_names = string_join_ext(", ", _emitter_names);
    -
    - show_debug_message("{0} contains the following particle emitters: {1}", _asset_name, _emitter_names); -

    -

    The above code first calls particle_get_info to retrieve information about an existing Particle System Asset ps_Environment. The asset's name is stored in a temporary variable _asset_name. After that, an array of emitter names is generated from the Particle System Info Struct's emitters variable and converted to a string listing all names, separated by a comma, using string_join_ext. Finally a debug message displays the information in a readable form.

    -

     

    -

     

    -
    -
    -
    -
    Back: Particles
    - +

    +

    Returns:

    +

    Particle System Info Struct

    +

    +

    Example 1: Particle Type Info

    +

    var _particle_info = particle_get_info(ps_Clouds); +
    + var _asset_name = _particle_info.name; +
    +
    + var _arr_emitters = _particle_info.emitters; +
    + if (array_length(_arr_emitters) > 0) +
    + { +
    + var _type_info = _arr_emitters[0].parttype; +
    +
    + if (_type_info.additive) +
    + { +
    + show_debug_message("The first emitter in {0} creates shiny particles!", _asset_name); +
    + } +
    + }

    +

    The above code first gets information from an existing Particle System Asset ps_Clouds using particle_get_info and assigns the returned struct to a temporary variable _particle_info. It then looks up the emitters in the particle system through the Particle System Info Struct's emitters variable. If the particle system contains any emitters (i.e. the array's length is greater than 0), the first emitter's parttype variable is assigned to a temporary variable _type_info and checked for additive blending (bm_add). Finally a debug message is shown if additive blending is used for the particle type.

    +

    +

    Example 2: Listing Emitter Names

    +

    var _particle_info = particle_get_info(ps_Environment); +
    + var _asset_name = _particle_info.name; +
    +
    + var _emitter_names = array_map(_particle_info.emitters, function(_element, _index) { return _element.name; }); +
    + _emitter_names = string_join_ext(", ", _emitter_names); +
    +
    + show_debug_message("{0} contains the following particle emitters: {1}", _asset_name, _emitter_names);

    +

    The above code first calls particle_get_info to retrieve information about an existing Particle System Asset ps_Environment. The asset's name is stored in a temporary variable _asset_name. After that, an array of emitter names is generated from the Particle System Info Struct's emitters variable and converted to a string listing all names, separated by a comma, using string_join_ext. Finally a debug message displays the information in a readable form.

    +

    +

    +
    +
    +
    +
    Back: Particles
    + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite.htm index c8340cbed..7b35537d1 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite.htm @@ -1,80 +1,78 @@ - + - - - draw_sprite - - - - - - - - - - - -

    draw_sprite

    -

    This function draws the given sprite and sub-image at a position within the game room. For the sprite you can use the instance variable sprite_index to get the current sprite that is assigned to the instance running the code, or you can use any other sprite asset. The same goes for the sub-image, as this can also be set to the instance variable image_index which will set the sub-image to that selected for the current instance sprite (note, that you can draw a different sprite and still use the sub-image value for the current instance), or you can use any other value for this to draw a specific sub-image of the chosen sprite. If the value is larger than the number of sub-images, then GameMaker will automatically loop the number to select the corresponding image (for example, if the sprite being drawn has 5 sub-images numbered 0 to 4 and we set the index value to 7, then the function will draw the third sub-image, numbered 2). Finally, the x and y position is the position within the room that the sprite will be drawn, and it is centered on the sprite x offset and y offset.

    -

    NOTE This function may not work as expected when using skeleton animation sprites, and you may find that the function only draws the first frame of the default pose. You should be using the draw_skeleton_* functions instead.

    -

     

    -

    Syntax:

    -

    draw_sprite(sprite, subimg, x, y);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    spriteSprite AssetThe index of the sprite to draw.
    subimgRealThe sub-image (frame) of the sprite to draw (image_index or -1 correlate to the current frame of animation in the object).
    xRealThe x coordinate of where to draw the sprite.
    yRealThe y coordinate of where to draw the sprite.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    draw_sprite(sprite_index, image_index, x, y);
    - draw_sprite(spr_Halo, 0, x, y-32);

    -

    This will draw the instances assigned sprite (sprite_index) with the current sub-image at the x and y position of the instance within the room. It will then draw the first frame of the sprite indexed by "spr_Halo" at the same x and y position but 32 pixels 'above'.

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + draw_sprite + + + + + + + + + + +

    draw_sprite

    +

    This function draws the given sprite and sub-image at a position within the game room. For the sprite you can use the instance variable sprite_index to get the current sprite that is assigned to the instance running the code, or you can use any other sprite asset. The same goes for the sub-image, as this can also be set to the instance variable image_index which will set the sub-image to that selected for the current instance sprite (note, that you can draw a different sprite and still use the sub-image value for the current instance), or you can use any other value for this to draw a specific sub-image of the chosen sprite. If the value is larger than the number of sub-images, then GameMaker will automatically loop the number to select the corresponding image (for example, if the sprite being drawn has 5 sub-images numbered 0 to 4 and we set the index value to 7, then the function will draw the third sub-image, numbered 2). Finally, the x and y position is the position within the room that the sprite will be drawn, and it is centered on the sprite x offset and y offset.

    +

    NOTE This function may not work as expected when using skeleton animation sprites, and you may find that the function only draws the first frame of the default pose. You should be using the draw_skeleton_* functions instead.

    +

    +

    Syntax:

    +

    draw_sprite(sprite, subimg, x, y);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    spriteSprite AssetThe sprite to draw.
    subimgRealThe sub-image (frame) of the sprite to draw (image_index or -1 correlate to the current frame of animation in the object).
    xRealThe x coordinate of where to draw the sprite.
    yRealThe y coordinate of where to draw the sprite.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    draw_sprite(sprite_index, image_index, x, y); +
    + draw_sprite(spr_Halo, 0, x, y-32);

    +

    This will draw the instances assigned sprite (sprite_index) with the current sub-image at the x and y position of the instance within the room. It will then draw the first frame of the sprite indexed by "spr_Halo" at the same x and y position but 32 pixels 'above'.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_ext.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_ext.htm index 5da26faa2..89b075ffb 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_ext.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_ext.htm @@ -1,97 +1,104 @@ - + - - - draw_sprite_ext - - - - - - - - - - - -

    draw_sprite_ext

    -

    This function will draw the given sprite as in the function draw_sprite() but with additional options to change the scale, blending, rotation and alpha of the sprite being drawn. Changing these values does not modify the resource in any way (only how it is drawn), and you can use any of the available sprite variables instead of direct values for all the arguments in the function. The image below illustrates how different values affect the drawing of the sprite:

    -

    sraw_sprite_ext examples

    -

    -

    NOTE: Colour blending is only recommended for the HTML5 target when WebGL is enabled, although you can still set the blending colour if it is not enabled and it will blend the sprite as normal. However all blending in this way creates a duplicate sprite which is then stored in the cache and used when required. This is far from optimal and if you use multiple colour changes it will slow down your games performance unless you activate WebGL. if you do not wish to use WebGL, then you can set the font cache size to try and limit this should it be necessary using the function sprite_set_cache_size().

    -

    NOTE: This function may not work as expected when using skeleton animation sprites, and you may find that the function only draws the first frame of the default pose. You should be using the draw_skeleton_* functions instead.

    -

     

    -

    Syntax:

    -

    draw_sprite_ext( sprite, subimg, x, y, xscale, yscale, rot, colour, alpha );

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    spriteThe index of the sprite to draw.
    subimgThe subimg (frame) of the sprite to draw (image_index or -1 correlate to the current frame of animation in the object).
    xThe x coordinate of where to draw the sprite.
    yThe y coordinate of where to draw the sprite.
    xscaleThe horizontal scaling of the sprite, as a multiplier: 1 = normal scaling, 0.5 is half etc...
    yscaleThe vertical scaling of the sprite as a multiplier: 1 = normal scaling, 0.5 is half etc...
    rotThe rotation of the sprite. 0=right way up, 90=rotated 90 degrees counter-clockwise etc...
    colourThe colour with which to blend the sprite. c_white is to display it normally.
    alphaThe alpha of the sprite (from 0 to 1 where 0 is transparent and 1 opaque).
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    draw_sprite_ext(sprite_index, image_index, x, y, image_xscale, image_yscale, image_angle, image_blend, image_alpha);

    -

    This will draw the instances assigned sprite with all its default values (essentially the same as using draw_self).

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + draw_sprite_ext + + + + + + + + + + +

    draw_sprite_ext

    +

    This function will draw the given sprite as in the function draw_sprite() but with additional options to change the scale, blending, rotation and alpha of the sprite being drawn. Changing these values does not modify the resource in any way (only how it is drawn), and you can use any of the available sprite variables instead of direct values for all the arguments in the function. The image below illustrates how different values affect the drawing of the sprite:

    +

    sraw_sprite_ext examples

    +

    +

    NOTE: Colour blending is only recommended for the HTML5 target when WebGL is enabled, although you can still set the blending colour if it is not enabled and it will blend the sprite as normal. However all blending in this way creates a duplicate sprite which is then stored in the cache and used when required. This is far from optimal and if you use multiple colour changes it will slow down your games performance unless you activate WebGL. if you do not wish to use WebGL, then you can set the font cache size to try and limit this should it be necessary using the function sprite_set_cache_size().

    +

    NOTE: This function may not work as expected when using skeleton animation sprites, and you may find that the function only draws the first frame of the default pose. You should be using the draw_skeleton_* functions instead.

    +

    +

    Syntax:

    +

    draw_sprite_ext( sprite, subimg, x, y, xscale, yscale, rot, colour, alpha );

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    spriteThe sprite to draw.
    subimgThe subimg (frame) of the sprite to draw (image_index or -1 correlate to the current frame of animation in the object).
    xThe x coordinate of where to draw the sprite.
    yThe y coordinate of where to draw the sprite.
    xscaleThe horizontal scaling of the sprite, as a multiplier: 1 = normal scaling, 0.5 is half etc...
    yscaleThe vertical scaling of the sprite as a multiplier: 1 = normal scaling, 0.5 is half etc...
    rotThe rotation of the sprite. 0=right way up, 90=rotated 90 degrees counter-clockwise etc...
    colourThe colour with which to blend the sprite. c_white is to display it normally.
    alphaThe alpha of the sprite (from 0 to 1 where 0 is transparent and 1 opaque).
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    draw_sprite_ext(sprite_index, image_index, x, y, image_xscale, image_yscale, image_angle, image_blend, image_alpha);

    +

    This will draw the instances assigned sprite with all its default values (essentially the same as using draw_self).

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_general.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_general.htm index 339a2e151..c76e7f231 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_general.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_general.htm @@ -1,143 +1,140 @@ - + - - - draw_sprite_general - - - - - - - - - - - -

    draw_sprite_general

    -

    This function combines the function draw_sprite_ext() with the function draw_sprite_part(), adding in some additional blending options so that each corner of the final sprite part can be blended with an individual colour.

    -

    Note that applying colours to corners may not look exactly as you expect due to how sprites are drawn. See the following example, where the image on the left is drawn with a different bottom-left colour, and the image on the right is drawn with a different bottom-right colour:

    -

    In each image the gradients do not seamlessly span the whole rectangle and instead seem to be split into halves. This is due to a rectangle actually being made up of two triangles, where the corner colours supplied into this function are applied to each vertex of the two triangles (hence 6 vertices at 3 per triangle). This causes the colours between the vertices to be interpolated for each triangle separately.

    -

    Colour blending is only recommended for the HTML5 target when WebGL is enabled, although you can still set the blending colour if it is not enabled and it will blend the sprite as normal. However all blending in this way creates a duplicate sprite which is then stored in the cache and used when required. This is far from optimal and if you use multiple colour changes it will slow down your games performance unless you activate WebGL. If you do not wish to use WebGL, then you can set the sprite cache size to try and limit this should it be necessary using the function sprite_set_cache_size().

    -

    This function may not work as expected when using skeleton animation sprites, and you may find that the function only draws the first frame of the default pose. You should be using the draw_skeleton_* functions instead.

    -

    When drawing with this function, the sprite x offset and y offset are ignored and the sprite part will be drawn with the top left corner at the specified x / y position in the room.

    -

     

    -

    Syntax:

    -

    draw_sprite_general(sprite, subimg, left, top, width, height, x, y, xscale, yscale, rot, c1, c2, c3, c4, alpha);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    spriteSprite AssetThe index of the sprite to draw.
    subimgRealThe subimg (frame) of the sprite to draw (image_index or -1 correlate to the current frame of animation in the object).
    leftRealThe x position on the sprite of the top left corner of the area to draw.
    topRealThe y position on the sprite of the top left corner of the area to draw.
    widthRealThe width of the area to draw.
    heightRealThe height of the area to draw.
    xRealThe x coordinate of where to draw the sprite.
    yRealThe y coordinate of where to draw the sprite.
    xscaleRealThe horizontal scaling of the sprite, as a multiplier: 1 = normal scaling, 0.5 is half etc...
    yscaleRealThe vertical scaling of the sprite, as a multiplier: 1 = normal scaling, 0.5 is half etc...
    rotRealThe rotation of the sprite. 0=normal, 90=turned 90 degrees counter-clockwise etc.
    c1ColourThe colour with which to blend the top left area of the sprite.
    c2ColourThe colour with which to blend the top right area of the sprite.
    c3ColourThe colour with which to blend the bottom right area of the sprite.
    c4ColourThe colour with which to blend the bottom left area of the sprite.
    alphaRealThe alpha of the sprite (from 0 to 1 where 0 is transparent and 1 opaque).
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    draw_sprite_general(sprite_index, image_index, 8, 8, sprite_width-16, sprite_height-16, x, y, 2, 0.5, 180, c_white, c_white, c_black, c_black, 1);

    -

    This will draw the instances assigned sprite (sprite_index) and its current frame of animation (image_index), however it will shave an 8px margin off all four sides of the sprite. It will be stretched to double its usual width but half its usual height. It will be opaque, and upside down. The top area of the sprite will be blended white and hence normal, but the bottom area will be black, meaning the sprite will go from normal to a silhouette downwards in a smooth gradient.

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + draw_sprite_general + + + + + + + + + + +

    draw_sprite_general

    +

    This function combines the function draw_sprite_ext() with the function draw_sprite_part(), adding in some additional blending options so that each corner of the final sprite part can be blended with an individual colour.

    +

    Note that applying colours to corners may not look exactly as you expect due to how sprites are drawn. See the following example, where the image on the left is drawn with a different bottom-left colour, and the image on the right is drawn with a different bottom-right colour:

    +

    In each image the gradients do not seamlessly span the whole rectangle and instead seem to be split into halves. This is due to a rectangle actually being made up of two triangles, where the corner colours supplied into this function are applied to each vertex of the two triangles (hence 6 vertices at 3 per triangle). This causes the colours between the vertices to be interpolated for each triangle separately.

    +

    Colour blending is only recommended for the HTML5 target when WebGL is enabled, although you can still set the blending colour if it is not enabled and it will blend the sprite as normal. However all blending in this way creates a duplicate sprite which is then stored in the cache and used when required. This is far from optimal and if you use multiple colour changes it will slow down your games performance unless you activate WebGL. If you do not wish to use WebGL, then you can set the sprite cache size to try and limit this should it be necessary using the function sprite_set_cache_size().

    +

    This function may not work as expected when using skeleton animation sprites, and you may find that the function only draws the first frame of the default pose. You should be using the draw_skeleton_* functions instead.

    +

    When drawing with this function, the sprite x offset and y offset are ignored and the sprite part will be drawn with the top left corner at the specified x / y position in the room.

    +

    +

    Syntax:

    +

    draw_sprite_general(sprite, subimg, left, top, width, height, x, y, xscale, yscale, rot, c1, c2, c3, c4, alpha);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    spriteSprite AssetThe sprite to draw.
    subimgRealThe subimg (frame) of the sprite to draw (image_index or -1 correlate to the current frame of animation in the object).
    leftRealThe x position on the sprite of the top left corner of the area to draw.
    topRealThe y position on the sprite of the top left corner of the area to draw.
    widthRealThe width of the area to draw.
    heightRealThe height of the area to draw.
    xRealThe x coordinate of where to draw the sprite.
    yRealThe y coordinate of where to draw the sprite.
    xscaleRealThe horizontal scaling of the sprite, as a multiplier: 1 = normal scaling, 0.5 is half etc...
    yscaleRealThe vertical scaling of the sprite, as a multiplier: 1 = normal scaling, 0.5 is half etc...
    rotRealThe rotation of the sprite. 0=normal, 90=turned 90 degrees counter-clockwise etc.
    c1ColourThe colour with which to blend the top left area of the sprite.
    c2ColourThe colour with which to blend the top right area of the sprite.
    c3ColourThe colour with which to blend the bottom right area of the sprite.
    c4ColourThe colour with which to blend the bottom left area of the sprite.
    alphaRealThe alpha of the sprite (from 0 to 1 where 0 is transparent and 1 opaque).
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    draw_sprite_general(sprite_index, image_index, 8, 8, sprite_width-16, sprite_height-16, x, y, 2, 0.5, 180, c_white, c_white, c_black, c_black, 1);

    +

    This will draw the instances assigned sprite (sprite_index) and its current frame of animation (image_index), however it will shave an 8px margin off all four sides of the sprite. It will be stretched to double its usual width but half its usual height. It will be opaque, and upside down. The top area of the sprite will be blended white and hence normal, but the bottom area will be black, meaning the sprite will go from normal to a silhouette downwards in a smooth gradient.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_part.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_part.htm index 035928b8a..b4c77baba 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_part.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_part.htm @@ -1,96 +1,98 @@ - + - - - draw_sprite_part - - - - - - - - - - - -

    draw_sprite_part

    -

    With this function you can draw part of any sprite at a given position within the room. As with draw_sprite() you can specify a sprite and a sub-image for drawing, then you must give the relative coordinates within the sprite of the area to select for drawing. This means that a left position of 0 and a top position of 0 would be the top left corner of the sprite and all further coordinates should be taken from that position. The image below shows an example - of how this works:

    -

    draw_sprite_part exampleYou should note that if the texture page permits automatic cropping then this function may not work as expected, - since the extra "empty" space around the sprite will have been removed for creating the texture page. To resolve this issue, you will need to set the texture page settings (in the Texture Group Editor) - to disable the option Automatic Crop.

    -

    NOTE: When drawing with this function, the sprite x offset and y offset are ignored and the sprite part will be drawn with the top left corner at the specified x / y position in the room.

    -

    NOTE: This function is only useful for bitmap sprites and will not work with SWF or JSON (Spine) sprites.

    -

     

    -

    Syntax:

    -

    draw_sprite_part(sprite, subimg, left, top, width, height, x, y);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    spriteThe index of the sprite to draw.
    subimgThe subimg (frame) of the sprite to draw (image_index or -1 correlate to the current frame of animation in the object).
    leftThe x position on the sprite of the top left corner of the area to draw.
    topThe y position on the sprite of the top left corner of the area to draw.
    widthThe width of the area to draw.
    heightThe height of the area to draw.
    xThe x coordinate of where to draw the sprite.
    yThe y coordinate of where to draw the sprite.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    draw_sprite_part(sprite_index, image_index, 4, 0, sprite_width-16, sprite_height-16, x, y );

    -

    This will draw the instances assigned sprite (sprite_index) and its current frame of animation (image_index), however it will shave a 4px margin off the width on both sides, and an 8 pixel margin off the height from the bottom of the original 24x24 - pixel sprite.

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + draw_sprite_part + + + + + + + + + + +

    draw_sprite_part

    +

    With this function you can draw part of any sprite at a given position within the room. As with draw_sprite() you can specify a sprite and a sub-image for drawing, then you must give the relative coordinates within the sprite of the area to select for drawing. This means that a left position of 0 and a top position of 0 would be the top left corner of the sprite and all further coordinates should be taken from that position. The image below shows an example of how this works:

    +

    draw_sprite_part exampleYou should note that if the texture page permits automatic cropping then this function may not work as expected, since the extra "empty" space around the sprite will have been removed for creating the texture page. To resolve this issue, you will need to set the texture page settings (in the Texture Group Editor) to disable the option Automatic Crop.

    +

    NOTE: When drawing with this function, the sprite x offset and y offset are ignored and the sprite part will be drawn with the top left corner at the specified x / y position in the room.

    +

    NOTE: This function is only useful for bitmap sprites and will not work with SWF or JSON (Spine) sprites.

    +

    +

    Syntax:

    +

    draw_sprite_part(sprite, subimg, left, top, width, height, x, y);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    spriteThe sprite to draw.
    subimgThe subimg (frame) of the sprite to draw (image_index or -1 correlate to the current frame of animation in the object).
    leftThe x position on the sprite of the top left corner of the area to draw.
    topThe y position on the sprite of the top left corner of the area to draw.
    widthThe width of the area to draw.
    heightThe height of the area to draw.
    xThe x coordinate of where to draw the sprite.
    yThe y coordinate of where to draw the sprite.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    draw_sprite_part(sprite_index, image_index, 4, 0, sprite_width-16, sprite_height-16, x, y );

    +

    This will draw the instances assigned sprite (sprite_index) and its current frame of animation (image_index), however it will shave a 4px margin off the width on both sides, and an 8 pixel margin off the height from the bottom of the original 24x24 pixel sprite.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_part_ext.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_part_ext.htm index 6f12a216e..d456661d1 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_part_ext.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_part_ext.htm @@ -1,114 +1,118 @@ - + - - - draw_sprite_part_ext - - - - - - - - - - - -

    draw_sprite_part_ext

    -

    This function will draw a part of the chosen sprite at the given position following the same rules as per draw_sprite_part(), only now you can scale the part, blend a colour with it, or change its alpha when - drawing it to the screen (the same as when drawing a sprite with draw_sprite_ext()). You should note that if the texture page permits automatic cropping then this function may not work as expected, since - the extra "empty" space around the sprite will have been removed for creating the texture page. To resolve this issue, you will need to set the texture page settings (in the Texture Group Editor) - to disable the Automatic Crop.

    -

    NOTE When drawing with this function, the sprite x offset and y offset are ignored and the sprite part will be drawn with the top left corner at the specified x / y position in the room.

    -

    NOTE: This function is only useful for bitmap sprites and will not work with SWF or JSON (Spine) sprites.

    -

    NOTE: Colour blending is only recommended for the HTML5 target when WebGL is enabled, although you can still set the blending colour if it is not enabled and it will blend the sprite as normal. However all blending in this way creates a duplicate - sprite which is then stored in the cache and used when required. This is far from optimal and if you use multiple colour changes it will slow down your games performance unless you activate WebGL. if you do not wish to use WebGL, then you can set - the font cache size to try and limit this should it be necessary using the function sprite_set_cache_size().

    -

     

    -

    Syntax:

    -

    draw_sprite_part_ext(sprite, subimg, left, top, width, height, x, y, xscale, yscale, colour, alpha);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    spriteThe index of the sprite to draw.
    subimgThe subimg (frame) of the sprite to draw (image_index or -1 correlate to the current frame of animation in the object).
    leftThe x position on the sprite of the top left corner of the area to draw.
    topThe y position on the sprite of the top left corner of the area to draw.
    widthThe width of the area to draw.
    heightThe height of the area to draw.
    xThe x coordinate of where to draw the sprite.
    yThe y coordinate of where to draw the sprite.
    xscaleThe horizontal scaling of the sprite, as a multiplier: 1 = normal scaling, 0.5 is half etc...
    yscaleThe vertical scaling of the sprite, as a multiplier: 1 = normal scaling, 0.5 is half etc...
    colourThe colour with which to blend the sprite. c_white is to display it normally.
    alphaThe alpha of the sprite (from 0 to 1 where 0 is transparent and 1 opaque).
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    draw_sprite_part_ext(sprite_index, image_index, 8, 8, sprite_width-16, sprite_height-16, x, y, 2, 0.5, c_black, 1);

    -

    This will draw the instances assigned sprite (sprite_index) and its current frame of animation (image_index), however it will shave an 8px margin off all four sides of the sprite. It will then be stretched to double its usual width but half its usual - height, and although the alpha is still 1, it will be blended with black (turning it into a silhouette).

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + draw_sprite_part_ext + + + + + + + + + + +

    draw_sprite_part_ext

    +

    This function will draw a part of the chosen sprite at the given position following the same rules as per draw_sprite_part(), only now you can scale the part, blend a colour with it, or change its alpha when drawing it to the screen (the same as when drawing a sprite with draw_sprite_ext()). You should note that if the texture page permits automatic cropping then this function may not work as expected, since the extra "empty" space around the sprite will have been removed for creating the texture page. To resolve this issue, you will need to set the texture page settings (in the Texture Group Editor) to disable the Automatic Crop.

    +

    NOTE When drawing with this function, the sprite x offset and y offset are ignored and the sprite part will be drawn with the top left corner at the specified x / y position in the room.

    +

    NOTE: This function is only useful for bitmap sprites and will not work with SWF or JSON (Spine) sprites.

    +

    NOTE: Colour blending is only recommended for the HTML5 target when WebGL is enabled, although you can still set the blending colour if it is not enabled and it will blend the sprite as normal. However all blending in this way creates a duplicate sprite which is then stored in the cache and used when required. This is far from optimal and if you use multiple colour changes it will slow down your games performance unless you activate WebGL. if you do not wish to use WebGL, then you can set the font cache size to try and limit this should it be necessary using the function sprite_set_cache_size().

    +

    +

    Syntax:

    +

    draw_sprite_part_ext(sprite, subimg, left, top, width, height, x, y, xscale, yscale, colour, alpha);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    spriteThe sprite to draw.
    subimgThe subimg (frame) of the sprite to draw (image_index or -1 correlate to the current frame of animation in the object).
    leftThe x position on the sprite of the top left corner of the area to draw.
    topThe y position on the sprite of the top left corner of the area to draw.
    widthThe width of the area to draw.
    heightThe height of the area to draw.
    xThe x coordinate of where to draw the sprite.
    yThe y coordinate of where to draw the sprite.
    xscaleThe horizontal scaling of the sprite, as a multiplier: 1 = normal scaling, 0.5 is half etc...
    yscaleThe vertical scaling of the sprite, as a multiplier: 1 = normal scaling, 0.5 is half etc...
    colourThe colour with which to blend the sprite. c_white is to display it normally.
    alphaThe alpha of the sprite (from 0 to 1 where 0 is transparent and 1 opaque).
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    draw_sprite_part_ext(sprite_index, image_index, 8, 8, sprite_width-16, sprite_height-16, x, y, 2, 0.5, c_black, 1);

    +

    This will draw the instances assigned sprite (sprite_index) and its current frame of animation (image_index), however it will shave an 8px margin off all four sides of the sprite. It will then be stretched to double its usual width but half its usual height, and although the alpha is still 1, it will be blended with black (turning it into a silhouette).

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_pos.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_pos.htm index d1a98a817..d63a6323b 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_pos.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_pos.htm @@ -1,107 +1,114 @@ - + - - - draw_sprite_pos - - - - - - - - - - - -

    draw_sprite_pos

    -

    With this function you can draw a sprite distorted over the area defined by the four corner coordinates. The first two arguments are the sprite to draw and the sub-image of the sprite (the same as in the function draw_sprite()) - but the next ones are those that define the position of each of the four corners of the bounding box of the given sprite. These should be given in clockwise order, so the first coordinate is the top left, then the top right, then bottom - right and finally the bottom left. You can also set a value for the alpha of the sprite to draw it with transparency. The image below illustrates how this function works:

    -

    draw_sprite_pos example

    -

    WARNING! The image above is only for illustrative purposes, and if you use this function on a sprite, you will get different results and may experience texture "shearing" due to the way that a sprite is constructed from a quad of primitives.

    -

    NOTE: This function is only useful for bitmap sprites and will not work with SWF or JSON (Spine) sprites.

    -

    NOTE: When using this function, you should have the Automatically Crop setting disabled for texture pages.

    -

     

    -

    Syntax:

    -

    draw_sprite_pos(sprite, subimg, x1, y1, x2, y2, x3, y3, x4, y4, alpha);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    spriteThe index of the sprite to draw.
    subimgThe subimg (frame) of the sprite to draw (image_index or -1 correlate to the current frame of animation in the object).
    x1The first x coordinate.
    y1The first y coordinate.
    x2The second x coordinate.
    y2The second y coordinate.
    x3The third x coordinate.
    y3The third y coordinate.
    x4The fourth x coordinate.
    y4The fourth y coordinate.
    alphaThe alpha of the sprite (from 0 to 1 where 0 is transparent and 1 opaque).
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    draw_sprite_pos(sprite_index, image_index, x - 100, y - 50, x - 50, y +150, x + 100, y + 200, x + 100, y, 1);

    -

    The above code will draw the sprite associated with the instance running the code distorted around the x / y position of the instance and with a fully opaque alpha.

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + draw_sprite_pos + + + + + + + + + + +

    draw_sprite_pos

    +

    With this function you can draw a sprite distorted over the area defined by the four corner coordinates. The first two arguments are the sprite to draw and the sub-image of the sprite (the same as in the function draw_sprite()) but the next ones are those that define the position of each of the four corners of the bounding box of the given sprite. These should be given in clockwise order, so the first coordinate is the top left, then the top right, then bottom right and finally the bottom left. You can also set a value for the alpha of the sprite to draw it with transparency. The image below illustrates how this function works:

    +

    draw_sprite_pos example

    +

    WARNING! The image above is only for illustrative purposes, and if you use this function on a sprite, you will get different results and may experience texture "shearing" due to the way that a sprite is constructed from a quad of primitives.

    +

    NOTE: This function is only useful for bitmap sprites and will not work with SWF or JSON (Spine) sprites.

    +

    NOTE: When using this function, you should have the Automatically Crop setting disabled for texture pages.

    +

    +

    Syntax:

    +

    draw_sprite_pos(sprite, subimg, x1, y1, x2, y2, x3, y3, x4, y4, alpha);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    spriteThe sprite to draw.
    subimgThe subimg (frame) of the sprite to draw (image_index or -1 correlate to the current frame of animation in the object).
    x1The first x coordinate.
    y1The first y coordinate.
    x2The second x coordinate.
    y2The second y coordinate.
    x3The third x coordinate.
    y3The third y coordinate.
    x4The fourth x coordinate.
    y4The fourth y coordinate.
    alphaThe alpha of the sprite (from 0 to 1 where 0 is transparent and 1 opaque).
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    draw_sprite_pos(sprite_index, image_index, x - 100, y - 50, x - 50, y +150, x + 100, y + 200, x + 100, y, 1);

    +

    The above code will draw the sprite associated with the instance running the code distorted around the x / y position of the instance and with a fully opaque alpha.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_stretched.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_stretched.htm index 1b4d48684..76b6d4e7b 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_stretched.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_stretched.htm @@ -1,77 +1,88 @@ - + - - - draw_sprite_stretched - - - - - - - - - - - -

    draw_sprite_stretched

    -

    This function simply takes a sprite resource and stretches it over the given width and height so that it occupies that area. As with draw_sprite() you can specify a sprite and a sub-image for drawing, then the x / y position in the room for the sprite to be drawn at and finally a width and a height (which must be pixel values). The image below shows the result of this function with different sets of arguments:

    -

    draw_sprite_stretched example

    -

    NOTE When drawing with this function, the sprite x offset and y offset (or origins) are ignored and the sprite is drawn with the top-left corner at the specified x/y position in the room.

    -

    -

     

    -

    Syntax:

    -

    draw_sprite_stretched(sprite, subimg, x, y, w, h);

    - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentType Description
    sprite The index of the sprite to draw.
    subimg The subimg (frame) of the sprite to draw (image_index or -1 correlate to the current frame of animation in the object).
    x The x coordinate of where to draw the sprite.
    y The y coordinate of where to draw the sprite.
    w The width of the area the stretched sprite will occupy.
    h The height of the area the stretched sprite will occupy.
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    draw_sprite_stretched(sprite_index, image_index, x, y, sprite_width, sprite_height / 2);

    -

    This will draw the instance's assigned sprite and its sub-image with the left corner at the instance x/y position. Its width is set to the same as the sprite, and the height is the sprite height divided by two.

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + draw_sprite_stretched + + + + + + + + + + +

    draw_sprite_stretched

    +

    This function simply takes a sprite resource and stretches it over the given width and height so that it occupies that area. As with draw_sprite() you can specify a sprite and a sub-image for drawing, then the x / y position in the room for the sprite to be drawn at and finally a width and a height (which must be pixel values). The image below shows the result of this function with different sets of arguments:

    +

    draw_sprite_stretched example

    +

    NOTE When drawing with this function, the sprite x offset and y offset (or origins) are ignored and the sprite is drawn with the top-left corner at the specified x/y position in the room.

    +

    +

    +

    Syntax:

    +

    draw_sprite_stretched(sprite, subimg, x, y, w, h);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    spriteThe sprite to draw.
    subimgThe subimg (frame) of the sprite to draw (image_index or -1 correlate to the current frame of animation in the object).
    xThe x coordinate of where to draw the sprite.
    yThe y coordinate of where to draw the sprite.
    wThe width of the area the stretched sprite will occupy.
    hThe height of the area the stretched sprite will occupy.
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    draw_sprite_stretched(sprite_index, image_index, x, y, sprite_width, sprite_height / 2);

    +

    This will draw the instance's assigned sprite and its sub-image with the left corner at the instance x/y position. Its width is set to the same as the sprite, and the height is the sprite height divided by two.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_stretched_ext.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_stretched_ext.htm index 09fa8d029..804a58905 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_stretched_ext.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_stretched_ext.htm @@ -1,82 +1,97 @@ - + - - - draw_sprite_stretched_ext - - - - - - - - - - - -

    draw_sprite_stretched_ext

    -

    This function does exactly the same as the draw_sprite_stretched() function with the added ability to set the colour blending and alpha value for the sprite when it is drawn (similar to the function draw_sprite_ext()).

    -

    NOTE When drawing with this function, the sprite x offset and y offset (or origins) are ignored and the sprite is drawn with the top-left corner at the specified x/y position in the room.

    -

    NOTE Colour blending is only recommended for the HTML5 target when WebGL is enabled, although you can still set the blending colour if it is not enabled and it will blend the sprite as normal. However all blending in this way creates a duplicate sprite which is then stored in the cache and used when required. This is far from optimal and if you use multiple colour changes it will slow down your games performance unless you activate WebGL. if you do not wish to use WebGL, then you can set the font cache size to try and limit this should it be necessary using the function sprite_set_cache_sizee().

    -

     

    -

    Syntax:

    -

    draw_sprite_stretched_ext(sprite, subimg, x, y, w, h, colour, alpha);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentType Description
    sprite The index of the sprite to draw.
    subimg The subimg (frame) of the sprite to draw (image_index or -1 correlate to the current frame of animation in the object).
    x The x coordinate of where to draw the sprite.
    y The y coordinate of where to draw the sprite.
    w The width of the area the stretched sprite will occupy.
    h The height of the area the stretched sprite will occupy.
    colour The colour with which to blend the sprite. c_white is to display it normally.
    alpha The alpha of the sprite (from 0 to 1 where 0 is transparent and 1 opaque).
    -

     

    -

    Returns:

    -

    N/A

    -

     

    -

    Example:

    -

    draw_sprite_stretched_ext(sprite_index, image_index, x, y, sprite_width, sprite_height / 2, c_white, 0.5);

    -

    This will draw the instances assigned sprite and its sub-image with the left corner at the instance x /y position. Its width is set to the same as the sprite, and the height is the sprite height divided by two. It will also be blended normally but have a partially transparent alpha value.

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + draw_sprite_stretched_ext + + + + + + + + + + +

    draw_sprite_stretched_ext

    +

    This function does exactly the same as the draw_sprite_stretched() function with the added ability to set the colour blending and alpha value for the sprite when it is drawn (similar to the function draw_sprite_ext()).

    +

    NOTE When drawing with this function, the sprite x offset and y offset (or origins) are ignored and the sprite is drawn with the top-left corner at the specified x/y position in the room.

    +

    NOTE Colour blending is only recommended for the HTML5 target when WebGL is enabled, although you can still set the blending colour if it is not enabled and it will blend the sprite as normal. However all blending in this way creates a duplicate sprite which is then stored in the cache and used when required. This is far from optimal and if you use multiple colour changes it will slow down your games performance unless you activate WebGL. if you do not wish to use WebGL, then you can set the font cache size to try and limit this should it be necessary using the function sprite_set_cache_sizee().

    +

    +

    Syntax:

    +

    draw_sprite_stretched_ext(sprite, subimg, x, y, w, h, colour, alpha);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    spriteThe sprite to draw.
    subimgThe subimg (frame) of the sprite to draw (image_index or -1 correlate to the current frame of animation in the object).
    xThe x coordinate of where to draw the sprite.
    yThe y coordinate of where to draw the sprite.
    wThe width of the area the stretched sprite will occupy.
    hThe height of the area the stretched sprite will occupy.
    colourThe colour with which to blend the sprite. c_white is to display it normally.
    alphaThe alpha of the sprite (from 0 to 1 where 0 is transparent and 1 opaque).
    +

    +

    Returns:

    +

    N/A

    +

    +

    Example:

    +

    draw_sprite_stretched_ext(sprite_index, image_index, x, y, sprite_width, sprite_height / 2, c_white, 0.5);

    +

    This will draw the instances assigned sprite and its sub-image with the left corner at the instance x /y position. Its width is set to the same as the sprite, and the height is the sprite height divided by two. It will also be blended normally but have a partially transparent alpha value.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_tiled.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_tiled.htm index 9d9ff7f24..3dd881328 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_tiled.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_tiled.htm @@ -1,75 +1,75 @@ - + - - - draw_sprite_tiled - - - - - - - - - - - -

    draw_sprite_tiled

    -

    This function will take a sprite and then repeatedly tile it across the whole view (or room if no view is defined), starting from the coordinates that you give in the function. Tiling is based on the width and height of the sprite as defined by the - sprite variables of the instance running the code. This function is for 2D (orthographic) projections only, and will not work correctly when a 3D - camera projection is used.

    -

     

    -

    Syntax:

    -

    draw_sprite_tiled(sprite, subimg, x, y);

    - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    spriteThe index of the sprite to draw.
    subimgThe subimg (frame) of the sprite to draw (image_index or -1 correlate to the current frame of animation in the object).
    xThe x coordinate of where to draw the sprite.
    yThe y coordinate of where to draw the sprite.
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    draw_sprite_tiled(sprite_index, image_index, x, y);

    -

    This will draw the instances assigned sprite (sprite_index) and its current frame of animation (image_index) at the instances own x and y position, and tiled horizontally and vertically across the view.

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + draw_sprite_tiled + + + + + + + + + + +

    draw_sprite_tiled

    +

    This function will take a sprite and then repeatedly tile it across the whole view (or room if no view is defined), starting from the coordinates that you give in the function. Tiling is based on the width and height of the sprite as defined by the sprite variables of the instance running the code. This function is for 2D (orthographic) projections only, and will not work correctly when a 3D camera projection is used.

    +

    +

    Syntax:

    +

    draw_sprite_tiled(sprite, subimg, x, y);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    spriteThe sprite to draw.
    subimgThe subimg (frame) of the sprite to draw (image_index or -1 correlate to the current frame of animation in the object).
    xThe x coordinate of where to draw the sprite.
    yThe y coordinate of where to draw the sprite.
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    draw_sprite_tiled(sprite_index, image_index, x, y);

    +

    This will draw the instances assigned sprite (sprite_index) and its current frame of animation (image_index) at the instances own x and y position, and tiled horizontally and vertically across the view.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_tiled_ext.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_tiled_ext.htm index c2c92e8b5..37713eabb 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_tiled_ext.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_tiled_ext.htm @@ -1,94 +1,96 @@ - + - - - draw_sprite_tiled_ext - - - - - - - - - - - -

    draw_sprite_tiled_ext

    -

    This function will take a sprite and then repeatedly tile it across the whole view (or room if no view is defined), starting from the coordinates that you give in the function and with each tile scaled, colour blended and with the alpha that you define - (these properties are the same as those used in draw_sprite_ext()). This function is for 2D (orthographic) projections only, and will not work correctly when a 3D camera projection is used.

    -

    NOTE: Colour blending is only recommended for the HTML5 target when WebGL is enabled, although you can still set the blending colour if it is not enabled and it will blend the sprite as normal. However all blending in this way creates a duplicate - sprite which is then stored in the cache and used when required. This is far from optimal and if you use multiple colour changes it will slow down your games performance unless you activate WebGL. if you do not wish to use WebGL, then you can set - the font cache size to try and limit this should it be necessary using the function sprite_set_cache_size().

    -

     

    -

    Syntax:

    -

    draw_sprite_tiled_ext(sprite, subimg, x, y, xscale, yscale, colour, alpha);

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    spriteThe index of the sprite to draw.
    subimgThe subimg (frame) of the sprite to draw (image_index or -1 correlate to the current frame of animation in the object).
    xThe x coordinate of where to draw the sprite.
    yThe y coordinate of where to draw the sprite.
    xscaleThe horizontal scaling of the sprite. A multiplier ' 1 = normal scaling, 0.5 is half etc.
    yscaleThe vertical scaling of the sprite. A multiplier ' 1 = normal scaling, 0.5 is half etc.
    colourThe colour with which to blend the sprite. c_white is to display it normally.
    alphaThe alpha of the sprite (from 0 to 1 where 0 is transparent and 1 opaque).
    -

     

    -

    Returns:

    -

    -

     

    -

    Example:

    -

    draw_sprite_tiled_ext(sprite_index, image_index, x, y, 2, 2, c_red, 0.5);

    -

    This will draw the instances assigned sprite (sprite_index) and its current frame of animation (image_index) at the instances own x and y position, but scaled to twice the normal size, blended red and with half the normal alpha. The sprite will be tiled - horizontally and vertically across the view.

    -

     

    -

     

    -

     

    -
    -
    -
    - - + + + draw_sprite_tiled_ext + + + + + + + + + + +

    draw_sprite_tiled_ext

    +

    This function will take a sprite and then repeatedly tile it across the whole view (or room if no view is defined), starting from the coordinates that you give in the function and with each tile scaled, colour blended and with the alpha that you define (these properties are the same as those used in draw_sprite_ext()). This function is for 2D (orthographic) projections only, and will not work correctly when a 3D camera projection is used.

    +

    NOTE: Colour blending is only recommended for the HTML5 target when WebGL is enabled, although you can still set the blending colour if it is not enabled and it will blend the sprite as normal. However all blending in this way creates a duplicate sprite which is then stored in the cache and used when required. This is far from optimal and if you use multiple colour changes it will slow down your games performance unless you activate WebGL. if you do not wish to use WebGL, then you can set the font cache size to try and limit this should it be necessary using the function sprite_set_cache_size().

    +

    +

    Syntax:

    +

    draw_sprite_tiled_ext(sprite, subimg, x, y, xscale, yscale, colour, alpha);

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    spriteThe sprite to draw.
    subimgThe subimg (frame) of the sprite to draw (image_index or -1 correlate to the current frame of animation in the object).
    xThe x coordinate of where to draw the sprite.
    yThe y coordinate of where to draw the sprite.
    xscaleThe horizontal scaling of the sprite. A multiplier ' 1 = normal scaling, 0.5 is half etc.
    yscaleThe vertical scaling of the sprite. A multiplier ' 1 = normal scaling, 0.5 is half etc.
    colourThe colour with which to blend the sprite. c_white is to display it normally.
    alphaThe alpha of the sprite (from 0 to 1 where 0 is transparent and 1 opaque).
    +

    +

    Returns:

    +

    +

    +

    Example:

    +

    draw_sprite_tiled_ext(sprite_index, image_index, x, y, 2, 2, c_red, 0.5);

    +

    This will draw the instances assigned sprite (sprite_index) and its current frame of animation (image_index) at the instances own x and y position, but scaled to twice the normal size, blended red and with half the normal alpha. The sprite will be tiled horizontally and vertically across the view.

    +

    +

    +

    +
    +
    +
    + + +
    +
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    -
    - - - +--> \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_tile.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_tile.htm index 426cc2ddc..c733395b7 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_tile.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_tile.htm @@ -4,7 +4,7 @@ draw_tile - + @@ -15,7 +15,7 @@

    draw_tile

    -

    With this function you can draw any given tile from a tile set - compete with rotations, flips and mirrors - setting the frame (if animated) and the position within the room. The tile set ID value is the tile set index as set in the IDE and the tile data is the data "blob" that contains all the information about the tile index and the transformations that have been applied. You can use the function tilemap_get() to get the tile data which can then be manipulated using the Tile Functions, or you can construct it yourself using the following tile constants along with the index value of the tile to create:

    +

    With this function you can draw any given tile from a tile set - compete with rotations, flips and mirrors - setting the frame (if animated) and the position within the room. The tile set handle is the tile set as set in the IDE and the tile data is the data "blob" that contains all the information about the tile index and the transformations that have been applied. You can use the function tilemap_get() to get the tile data which can then be manipulated using the Tile Functions, or you can construct it yourself using the following tile constants along with the index value of the tile to create:

    @@ -56,34 +56,34 @@

    Syntax:

    - - + + - + - + - + - +
    tilesetTile Set AssetThe ID of the tile set to useTile Set AssetThe handle of the tile set to use
    tiledataTile DataTile Data The tile data to use
    frameRealReal The frame number for the animated tile to use (default 0 for non-animated tiles)
    xRealReal The x position within the room to draw at
    yRealReal The y position within the room to draw at

     

    Returns:

    -

    Real

    +

    Real

     

    Example:

    var lay_id = layer_get_id("Tiles_sky");
    @@ -102,7 +102,7 @@

    Example:

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

    draw_get_font

    -

    This function will get the font currently assigned for drawing text. The function will return -1 if no font is set, or the ID value (a positive integer) for the font asset assigned.

    +

    This function will get the font currently assigned for drawing text. The function will return -1 if no font is set, or the handle for the font asset assigned.

     

    Syntax:

    draw_get_font();

     

    Returns:

    -

    Font Asset or -1

    +

    Font Asset or -1

     

    Example:

    var _cur_font = draw_get_font();
    @@ -59,7 +59,7 @@

    Example:

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

    mp_potential_path

    -

    This function computes a path for the instance from its current position and orientation to the position specified by the xgoal,ygoal arguments. It uses the indicated step size while trying to avoid collision with either all instances or only - those flagged as solid. Like in the function mp_potential_step() it uses potential field steps to accomplish this and the manner in which it does this can be modified through the function mp_potential_settings(). - The indicated path must already exist and it will be overwritten by the new path. The function will return whether a path was found (true) or not (false).

    -

    To avoid the function continuing to compute forever you need to provide a factor of larger than 1 - the function will stop and report failure if it cannot find a path shorter than this factor times the distance between start and goal. A factor of 4 - is normally good enough but if you expect long detours you might make it longer. If it fails a path is still created that runs in the approximate direction of the goal but it will not reach it.

    +

    This function computes a path for the instance from its current position and orientation to the position specified by the xgoal,ygoal arguments. It uses the indicated step size while trying to avoid collision with either all instances or only those flagged as solid. Like in the function mp_potential_step() it uses potential field steps to accomplish this and the manner in which it does this can be modified through the function mp_potential_settings(). The indicated path must already exist and it will be overwritten by the new path. The function will return whether a path was found (true) or not (false).

    +

    To avoid the function continuing to compute forever you need to provide a factor of larger than 1 - the function will stop and report failure if it cannot find a path shorter than this factor times the distance between start and goal. A factor of 4 is normally good enough but if you expect long detours you might make it longer. If it fails a path is still created that runs in the approximate direction of the goal but it will not reach it.

    NOTE: This function does not move the instance. It sets a path only, and you must use the Path functions for movement.

     

    Syntax:

    @@ -28,43 +25,51 @@

    Syntax:

    - + + - + - - - + + + + - + + - + - + + - + - + + - + - + + - + - + + - +
    ArgumentTypeArgumentType Description
    pathindex of the path that is to be used by the function
    pathPath AssetThe path that is to be used by the function
    xgoalxgoalReal The target x position.
    ygoalygoalReal The target y position.
    stepsizestepsizeReal The speed the instance moves in pixels per step.
    factorfactorReal This number is used to prevent an infinite loop. It should be larger than 1. See the function description for more information.
    checkallcheckallBoolean Whether to check all instances (true) or just solid ones (false).

     

    Returns:

    -

    +

    Boolean

     

    Example:

    -

    path = path_add();
    mp_potential_path(path, obj_Player.x, obj_Player.y, 3, 4, 0);
    path_start(path, 3, 0, 0);

    -

    The above code creates a new path resource and stores its index in the variable "path". It then generates a path using mp_potential_path between the object with this code and the object "obj_Player", checking for collisions - with all instances in the room. Finally it starts the object along that path, even if the function has failed to return a complete route to the "obj_Player".

    +

    path = path_add();
    + mp_potential_path(path, obj_Player.x, obj_Player.y, 3, 4, 0);
    + path_start(path, 3, 0, 0);

    +

    The above code creates a new path resource and stores its index in the variable "path". It then generates a path using mp_potential_path between the object with this code and the object "obj_Player", checking for collisions with all instances in the room. Finally it starts the object along that path, even if the function has failed to return a complete route to the "obj_Player".

     

     

     

    @@ -75,7 +80,7 @@

    Example:

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

    mp_potential_path_object

    -

    This function computes a path for the instance from its current position and orientation to the position specified by the xgoal, ygoal arguments. It uses the indicated step size while trying to avoid collision with instances of the object specified - by the "obj" argument. Like in the function mp_potential_step() it uses potential field steps to accomplish this and the manner in which it does this can be modified through the function mp_potential_settings(). - The indicated path must already exist and it will be overwritten by the new path. The function will return whether a path was found (true) or not (false).

    -

    To avoid the function continuing to compute forever you need to provide a factor of larger than 1 - the function will stop and report failure if it cannot find a path shorter than this factor times the distance between start and goal. A factor of 4 - is normally good enough but if you expect long detours you might make it longer. If it fails a path is still created that runs in the approximate direction of the goal but it will not reach it.

    +

    This function computes a path for the instance from its current position and orientation to the position specified by the xgoal, ygoal arguments. It uses the indicated step size while trying to avoid collision with instances of the object specified by the "obj" argument. Like in the function mp_potential_step() it uses potential field steps to accomplish this and the manner in which it does this can be modified through the function mp_potential_settings(). The indicated path must already exist and it will be overwritten by the new path. The function will return whether a path was found (true) or not (false).

    +

    To avoid the function continuing to compute forever you need to provide a factor of larger than 1 - the function will stop and report failure if it cannot find a path shorter than this factor times the distance between start and goal. A factor of 4 is normally good enough but if you expect long detours you might make it longer. If it fails a path is still created that runs in the approximate direction of the goal but it will not reach it.

    NOTE: This function does not move the instance. It sets a path only, and you must use the Path functions for movement.

     

    Syntax:

    @@ -28,43 +25,51 @@

    Syntax:

    - + + - + - - - + + + + - + + - + - + + - + - + + - + - + + - + - + + - +
    ArgumentTypeArgumentType Description
    pathindex of the path that is to be used by the function
    pathPath AssetThe path that is to be used by the function
    xgoalxgoalReal The target x position.
    ygoalygoalReal The target y position.
    stepsizestepsizeReal The speed the instance moves in pixels per step.
    factorfactorReal This number is used to prevent an infinite loop. It should be larger than 1. See the function description for more information.
    objobjObject Asset The object that is to block the path. Can be an object index, an instance id or the special keyword ,all

     

    Returns:

    -

    +

    Boolean

     

    Example:

    -

    path = path_add();
    mp_potential_path_object(path, obj_Player.x, obj_Player.y, 3, 4, obj_Wall);
    path_start(path, 3, 0, 0);

    -

    The above code creates a new path resource and stores its index in the variable "path". It then generates a path using mp_potential_path between the object with this code and the object "obj_Player", checking for collisions - with the object "obj_Wall". Finally it starts the object along that path, even if the function has failed to return a complete route to the "obj_Player".

    +

    path = path_add();
    + mp_potential_path_object(path, obj_Player.x, obj_Player.y, 3, 4, obj_Wall);
    + path_start(path, 3, 0, 0);

    +

    The above code creates a new path resource and stores its index in the variable "path". It then generates a path using mp_potential_path between the object with this code and the object "obj_Player", checking for collisions with the object "obj_Wall". Finally it starts the object along that path, even if the function has failed to return a complete route to the "obj_Player".

     

     

     

    @@ -75,7 +80,7 @@

    Example:

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

    array_length

    -

    This function gets the length (number of entries) of an array dimension.

    -

    You supply the array index value and the function will return an integer value representing the number of entries the array contains. This function can also be used for multi-dimension arrays, as long as you specify which dimension you want to get the length of when you supply the array index, following this pattern:

    +

    This function gets the length (number of entries) of an array.

    +

    You supply the array and the function will return an integer value representing the number of entries the array contains. This function can also be used for multi-dimension arrays, as long as you specify which dimension you want to get the length of when you supply the array index, following this pattern:

    // Returns the first dimension of the array
    val = array_length(my_array);

    @@ -32,7 +32,7 @@

    array_length

     The function returns 0 in case a data type that's not an Array is passed to it.

     

    Syntax:

    -

    array_length(array_index);

    +

    array_length(array);

    @@ -41,7 +41,7 @@

    Syntax:

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

    Example:

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

    ds_list_copy

    -

    With this function you can copy the contents of one list into another. Both lists must have been created previously and if the list being copied to already has information within it, this list will be cleared first. The end result is two independent lists which contain the same information.

    -

    -

    Syntax:

    -

    ds_list_copy( id, source );

    -
    Description
    array_indexarray Array The array to check.
    - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idThe handle of the list being copied to.
    sourceThe handle of the list to be copied from.
    -

    -

    Returns:

    -

    -

    -

    Example:

    -

    if (!ds_list_empty(main_list)) -
    - { -
    - old_list = ds_list_create(); -
    - ds_list_copy(old_list, main_list); -
    - ds_list_clear(main_list); -
    - }

    -

    The above code will check a DS list to see if it is empty. If it is not empty it is copied into another DS list (which has been created previously) and then the original list is cleared.

    -

    -

    -

    -
    -
    -
    -
    Back: DS Lists
    - -
    + + + ds_list_copy + + + + + + + + + + +

    ds_list_copy

    +

    With this function you can copy the contents of one list (source) into another (destination). Both lists must have been created previously and if the destination list already has information within it, this list will be cleared first. The end result is two independent lists which contain the same information.

    +

     

    +

    Syntax:

    +

    ds_list_copy(destination, source);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    destinationDS ListThe handle of the list being copied to.
    sourceDS ListThe handle of the list to be copied from.
    +

     

    +

    Returns:

    +

    N/A

    +

     

    +

    Example:

    +

    if (!ds_list_empty(main_list))
    + {
    + old_list = ds_list_create();
    + ds_list_copy(old_list, main_list);
    + ds_list_clear(main_list);
    + }

    +

    The above code will check a DS list to see if it is empty. If it is not empty it is copied into another DS list (which has been created previously) and then the original list is cleared.

    +

     

    +

     

    +

     

    +
    +
    +
    +
    Back: DS Lists
    +
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    - + +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_copy.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_copy.htm index 09890d60f..66d3a64ee 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_copy.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/ds_map_copy.htm @@ -1,66 +1,68 @@ - + - - - ds_map_copy - - - - - - - - - -

    ds_map_copy

    -

    You can use this function to copy the contents of one map into another one that you have previously created using ds_map_create(). If the DS map that is being copied to is not empty, then this function will clear it first before copying. The original DS map remains unchanged by this process.

    -

    -

    Syntax:

    -

    ds_map_copy(id, source);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idThe handle of the map you are copying to
    sourceThe handle of the map you are copying from
    -

    -

    Returns:

    -

    -

    -

    Example:

    -

    inventory_2 = ds_map_create(); -
    - ds_map_copy(inventory_2, inventory_1);

    -

    The above code will create a new map and assign it to the variable "inventory_2". It will then copy the contents of the DS map indexed in the variable "inventory_1" to this new map.

    -

    -

    -

    -
    -
    -
    -
    Back: DS Maps
    - -
    + + + ds_map_copy + + + + + + + + + + +

    ds_map_copy

    +

    You can use this function to copy the contents of one map (source) into another one (destination) that you have previously created using ds_map_create(). If the destination map is not empty, then this function will clear it first before copying. The source DS map remains unchanged by this process.

    +

     

    +

    Syntax:

    +

    ds_map_copy(destination, source);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    destinationDS MapThe handle of the map you are copying to
    sourceDS MapThe handle of the map you are copying from
    +

     

    +

    Returns:

    +

    N/A

    +

     

    +

    Example:

    +

    inventory_2 = ds_map_create();
    + ds_map_copy(inventory_2, inventory_1);

    +

    The above code will create a new map and assign it to the variable "inventory_2". It will then copy the contents of the DS map indexed in the variable "inventory_1" to this new map.

    +

     

    +

     

    +

     

    +
    +
    +
    +
    Back: DS Maps
    +
    -
    © Copyright YoYo Games Ltd. 2021 All Rights Reserved
    - + +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_copy.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_copy.htm index 495600b9a..5609a26df 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_copy.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Priority_Queues/ds_priority_copy.htm @@ -1,72 +1,71 @@ - + - - - ds_priority_copy - - - - - - - - - -

    ds_priority_copy

    -

    This function can be used to copy the contents of one priority queue into another. Note that this does NOT remove the contents from the original priority queue, nor does it destroy the original priority queue. When using this function the priority queue being copied to must have been previously created and if it contained any items before the copy, then these will be cleared first (meaning this information will be lost).

    -

    -

    Syntax:

    -

    ds_priority_copy(id, source);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idThe handle of the priority queue to copy to.
    sourceThe handle of the priority queue to copy from.
    -

    -

    Returns:

    -

    -

    -

    Example:

    -

    with (instance_create_layer(x, y, "Enemies", obj_Enemy)) -
    - { -
    - p_queue = ds_priority_create(); -
    - ds_priority_copy(p_queue, other.p_queue); -
    - }

    -

    The above function creates a new instance and then in that instance it creates a new DS priority queue and copies the contents of the priority queue in the instance running the code block, into the newly created instance priority queue.

    -

    -

    -

    -
    -
    -
    - - -
    + + + ds_priority_copy + + + + + + + + + + +

    ds_priority_copy

    +

    This function can be used to copy the contents of one priority queue (source) into another (destination). Note that this does NOT remove the contents from the source priority queue, nor does it destroy the source priority queue. When using this function the priority queue being copied to must have been previously created and if it contained any items before the copy, then these will be cleared first (meaning this information will be lost).

    +

     

    +

    Syntax:

    +

    ds_priority_copy(destination, source);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    destinationDS PriorityThe handle of the priority queue to copy to.
    sourceDS PriorityThe handle of the priority queue to copy from.
    +

     

    +

    Returns:

    +

    N/A

    +

     

    +

    Example:

    +

    with (instance_create_layer(x, y, "Enemies", obj_Enemy))
    + {
    + p_queue = ds_priority_create();
    + ds_priority_copy(p_queue, other.p_queue);
    + }

    +

    The above function creates a new instance and then in that instance it creates a new DS priority queue and copies the contents of the priority queue in the instance running the code block, into the newly created instance priority queue.

    +

     

    +

     

    +

     

    +
    +
    +
    + +
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    - + +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_copy.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_copy.htm index 36458dc51..53c1c4ba5 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_copy.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Queues/ds_queue_copy.htm @@ -1,72 +1,71 @@ - + - - - ds_queue_copy - - - - - - - - - -

    ds_queue_copy

    -

    This function can be used to copy the contents of one queue into another. Note that this does NOT remove the contents from the original queue, nor does it destroy the original queue. When using this function the queue being copied to must have been previously created and if it contained any items before the copy, then these will be cleared first (meaning this information will be lost).

    -

    -

    Syntax:

    -

    ds_queue_copy(id, source);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Queue IDThe handle of the new queue.
    sourceDS Queue IDThe original queue to copy from.
    -

    -

    Returns:

    -

    N/A

    -

    -

    Example:

    -

    with (instance_create_layer(x, y, "Enemies", obj_Enemy)) -
    - { -
    - queue = ds_queue_create(); -
    - ds_queue_copy(queue, other.queue); -
    - }

    -

    The above function creates a new instance and then in that instance it creates a new DS queue and copies the contents of the queue in the instance running the code block, into the newly created instance queue.

    -

    -

    -

    -
    -
    -
    -
    Back: DS Queues
    - -
    + + + ds_queue_copy + + + + + + + + + + +

    ds_queue_copy

    +

    This function can be used to copy the contents of one queue (source) into another (destination). Note that this does NOT remove the contents from the source queue, nor does it destroy the source queue. When using this function the queue being copied to must have been previously created and if it contained any items before the copy, then these will be cleared first (meaning this information will be lost).

    +

     

    +

    Syntax:

    +

    ds_queue_copy(destination, source);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    destinationDS QueueThe handle of the new queue.
    sourceDS QueueThe original queue to copy from.
    +

     

    +

    Returns:

    +

    N/A

    +

     

    +

    Example:

    +

    with (instance_create_layer(x, y, "Enemies", obj_Enemy))
    + {
    + queue = ds_queue_create();
    + ds_queue_copy(queue, other.queue);
    + }

    +

    The above function creates a new instance and then in that instance it creates a new DS queue and copies the contents of the queue in the instance running the code block, into the newly created instance queue.

    +

     

    +

     

    +

     

    +
    +
    +
    +
    Back: DS Queues
    +
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    - + +--> + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_copy.htm b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_copy.htm index f725dd377..a6458239f 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_copy.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Data_Structures/DS_Stacks/ds_stack_copy.htm @@ -1,72 +1,71 @@ - + - - - ds_stack_copy - - - - - - - - - -

    ds_stack_copy

    -

    This function can be used to copy the contents of one stack into another. Note that this does NOT remove the contents from the original stack, nor does it destroy the original stack. When using this function the stack being copied to must have been previously created and if it contained any items before the copy, then these will be cleared first (meaning this information will be lost).

    -

    -

    Syntax:

    -

    ds_stack_copy(id, source);

    - - - - - - - - - - - - - - - - - - -
    ArgumentTypeDescription
    idDS Stack IDThe handle of the new stack.
    sourceDS Stack IDThe original stack to copy from.
    -

    -

    Returns:

    -

    N/A

    -

    -

    Example:

    -

    with (instance_create_layer(x, y, "Enemies", obj_Enemy)) -
    - { -
    - stack = ds_stack_create(); -
    - ds_stack_copy(stack, other.stack); -
    - }

    -

    The above function creates a new instance and then in that instance it creates a new DS stack and copies the contents of the stack in the instance running the code block, into the newly created instance stack.

    -

    -

    -

    -
    -
    -
    -
    Back: DS Stacks
    - -
    + + + ds_stack_copy + + + + + + + + + + +

    ds_stack_copy

    +

    This function can be used to copy the contents of one stack (source) into another (destination). Note that this does NOT remove the contents from the source stack, nor does it destroy the source stack. When using this function the stack being copied to must have been previously created and if it contained any items before the copy, then these will be cleared first (meaning this information will be lost).

    +

     

    +

    Syntax:

    +

    ds_stack_copy(destination, source);

    + + + + + + + + + + + + + + + + + + +
    ArgumentTypeDescription
    destinationDS StackThe handle of the new stack.
    sourceDS StackThe original stack to copy from.
    +

     

    +

    Returns:

    +

    N/A

    +

     

    +

    Example:

    +

    with (instance_create_layer(x, y, "Enemies", obj_Enemy))
    + {
    + stack = ds_stack_create();
    + ds_stack_copy(stack, other.stack);
    + }

    +

    The above function creates a new instance and then in that instance it creates a new DS stack and copies the contents of the stack in the instance running the code block, into the newly created instance stack.

    +

     

    +

     

    +

     

    +
    +
    +
    +
    Back: DS Stacks
    +
    -
    © Copyright YoYo Games Ltd. 2023 All Rights Reserved
    - + +--> + \ No newline at end of file From 96a6d73bd8d1012d6603e59dcc3173dae05b04de Mon Sep 17 00:00:00 2001 From: gurpreetsinghmatharoo Date: Thu, 12 Sep 2024 11:59:30 +0530 Subject: [PATCH 12/13] docs(general): Video playback - note on audio restrictions https://github.com/GameMakerEnterprise/GMS2-Runner-Xbox/issues/2 --- .../GameMaker_Language/GML_Reference/Drawing/Videos/Videos.htm | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Videos/Videos.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Videos/Videos.htm index 7689523c7..d2baa7da6 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Videos/Videos.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Videos/Videos.htm @@ -47,6 +47,8 @@

    Video Codecs & Licensing

    Making use of certain formats may require you to pay licensing fees depending on the related codec's licence and your game's revenue, and in such a case, the developer will be legally liable for any fees that is to be paid to the codec owners. Codecs are also licensed differently on each platform and so care must be taken for games that are distributed on multiple platforms.

    Note that video formats (such as .mp4, .avi, .mkv, etc.) are simply containers that wrap video and audio streams, both of which may be encoded separately and may require separate licences.

    For distribution on console platforms, check with your account representative to find out what formats you are allowed to use without having to pay extra licencing fees.

    +

    Audio Limitations

    +

    On some platforms (especially consoles), the video playback implementation is not associated with the audio engine used for that platform. This means the audio playback from your video may be subject to the limitations of the audio engine on that platform, such as it requiring the audio to be encoded in a specific format and sample rate (e.g. requiring 48kHz audio). When facing issues with audio playback, please check the SDK for the platform to ensure your audio is encoded according to the requirements for that platform.

    Formats

    The video formats that you are able to load and play in your game will depend on your target platform, and the codecs that are supported on that platform.

    From 7458eb94efc20f8745441da0a956ee2aaeb9214f Mon Sep 17 00:00:00 2001 From: gurpreetsinghmatharoo Date: Thu, 12 Sep 2024 16:08:15 +0530 Subject: [PATCH 13/13] docs(general): Video playback page fix --- .../GameMaker_Language/GML_Reference/Drawing/Videos/Videos.htm | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Videos/Videos.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Videos/Videos.htm index d2baa7da6..b9017c786 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Videos/Videos.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Videos/Videos.htm @@ -48,7 +48,7 @@

    Video Codecs & Licensing

    Note that video formats (such as .mp4, .avi, .mkv, etc.) are simply containers that wrap video and audio streams, both of which may be encoded separately and may require separate licences.

    For distribution on console platforms, check with your account representative to find out what formats you are allowed to use without having to pay extra licencing fees.

    Audio Limitations

    -

    On some platforms (especially consoles), the video playback implementation is not associated with the audio engine used for that platform. This means the audio playback from your video may be subject to the limitations of the audio engine on that platform, such as it requiring the audio to be encoded in a specific format and sample rate (e.g. requiring 48kHz audio). When facing issues with audio playback, please check the SDK for the platform to ensure your audio is encoded according to the requirements for that platform.

    +

    On some platforms, the video playback implementation is not associated with the audio engine used for that platform. This means the audio playback from your video may be subject to the limitations of the audio engine on that platform, such as it requiring the audio to be encoded in a specific format and sample rate (e.g. requiring 48kHz audio). When facing issues with audio playback, please check the SDK for the platform to ensure your audio is encoded according to the requirements for that platform.

    Formats

    The video formats that you are able to load and play in your game will depend on your target platform, and the codecs that are supported on that platform.