Differences

This shows you the differences between two versions of the page.

--- legacy:grid:api [2025/01/13 16:14] – removed - external edit (Unknown date) 127.0.0.1
+++ legacy:grid:api [2025/01/13 16:14] (current) – ↷ Links adapted because of a move operation superadmin
@@ Line 1: / Line 1: @@
+====== Grid API ======
+This section explains the basic grid interaction and the building block of function you can use.
+===== Battler Position =====
+Battler position is represented as an index in a __one-dimension__ [[https://ruby-doc.org/core-1.9.2/Array.html|array]] (Yes, even though the grid actually has two dimensions of X and Y). For technical reasons, this was to simplify the implementation.
+{{https://i.imgur.com/5TS4NCw.jpg}}
+==== Grid dimension ====
+To determine the dimension the grid, set it in the API section of then script.
+<code ruby>
+MaxRow = 3  # Determine the maximum row
+MaxCol = 8  # Determine the maximum column
+</code>
+When you decide the dimension of the grid, the maximum index is changed accordingly. i.e, if you put the dimension as ''8x3'' for width and height respectively, the maximum index is ''23'' resulted from 8 multiplied by 3 minus 1 (Because array started from index 0). And the script will automatically recognize the index 0 to 7 as the first row, 8 to 15 as the second row, and 16 to 23 as the last row.
+Because the position is stored in a one-dimension array, so does the battler position. To determine the position, you have to make a nested array that represents the screen position of that said index. For example, this is the position setting in the 640x360 screen in [[legacy:grid:sample_game|the sample game]].
+<code ruby>
+Position =
+[
+[134,158],[182,158],[240,158],[292,158],[346,158],[400,158],[454,158],[508,158],
+[124,180],[180,180],[236,180],[292,180],[348,180],[404,180],[460,180],[516,180],
+[105,200],[164,200],[226,200],[288,200],[350,200],[412,200],[474,200],[536,200],
+]
+</code>
+The first index represents 134 for the x-axis position and 158 as the y-axis position. Do note that __the script will NOT care about how you actually put the screen position__. Make sure that the grid position correctly represents the position. You can always the ''ShowIndex = true'' to enable the index display in [[Grid - Display Grid Index]] section, so that you could see the index position like in the screenshot provided above.
+Remember when setting the position, the script will always treat the first index (which is index 0) to be always on the top left of the screen. You can not change this behavior unless you internally change how the module works. Fortunately, the end-user will not know this behavior, this is just how the back-end system works.
+===== Getting Position =====
+Getting the position is largely used in the [[legacy:grid:targeting|targeting system]] __and you're expected to know how to code ruby__. Here are the list of important functions to be used (in the script call).
+==== Neighbor direction ====
+<code ruby>Grid.neighbor(index, direction, {times})</code>
+This function gets the neighbor/adjacent position of the current grid.
+  * Index = Represents which index you want to get its neighbor position
+  * Direction = Represents which direction you want to check in a [[https://en.wikipedia.org/wiki/Numeric_keypad|Numeric Keypad]]. Which 2 represent for down, 4 for left, 6 for right, etc. You can use the diagonal as well.
+  * Times = Optional parameter that can be omitted. The parameter function as to how far you want to check into that direction (The default value is 1).
+Here is a list of examples. The orange cell represents the center grid you want to check its neighbor
+<code ruby>
+Grid.neighbor(13, 4)  # Return value = 12
+</code>
+| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
+| 8 | 9 | 10 | 11 | @lightgreen:12 | @orange:13 | 14 | 15 |
+| 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 |
+<code ruby>
+  Grid.neighbor(13, 4, 2)  # Return value = 11
+</code>
+| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
+| 8 | 9 | 10 | @lightgreen:11 | 12 | @orange:13 | 14 | 15 |
+| 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 |
+<code ruby>
+Grid.neighbor(5, 8)  # Return value = nil
+</code>
+| 0 | 1 | 2 | 3 | 4 | @orange:5 | 6 | 7 |
+| 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 |
+| 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 |
+Because the direction up does not have a grid position, it will return ''nil''
+==== Linear direction ====
+<code ruby>
+Grid.linear(index, direction, {times})
+</code>
+This function is to get an array that represents a linear direction.
+  * Index = Represents which index you want to get its neighbor position
+  * Direction = Represents which direction you want to check in a Numeric keypad. Unlike checking the neighbor position, the direction parameter here must be inputted as an array. i.e, it looks like this ''[2,4,6,8]'' so you can get multiple directions at the same time.
+  * Times = Optional parameter, it checks how far you want it to be. If omitted, it will have the default value is 1. But why would you omit it?
+Here is a list of examples. The orange cell represents the center grid you want to check its linear path.
+<code ruby>Grid.linear(13, [4], 4)  # Return value = [12, 11, 10, 9]</code>
+| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
+| 8 | @lightgreen:9 | @lightgreen:10 | @lightgreen:11 | @lightgreen:12 | @orange:13 | 14 | 15 |
+| 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 |
+<code ruby>
+  Grid.linear(22, [4,6,8], 3)  # Return value = [6, 14, 19, 20, 23]
+</code>
+| 0 | 1 | 2 | 3 | 4 | 5 | @lightgreen:6 | 7 |
+| 8 | 9 | 10 | 11 | 12 | 13 | @lightgreen:14 | 15 |
+| 16 | 17 | 18 | @lightgreen:19 | @lightgreen:20 | @lightgreen:21 | @orange:22 | @lightgreen:23 |
+<code ruby>
+  Grid.linear(22, [4,7,8], 3)  # Return value = [4, 6, 13, 14, 19, 20]
+</code>
+| 0 | 1 | 2 | 3 | @lightgreen:4 | 5 | @lightgreen:6 | 7 |
+| 8 | 9 | 10 | 11 | 12 | @lightgreen:13 | @lightgreen:14 | 15 |
+| 16 | 17 | 18 | @lightgreen:19 | @lightgreen:20 | @lightgreen:21 | @orange:22 | 23 |
+==== Surrounding direction ====
+<code ruby>Grid.surrounding(index, direction)</code>
+This function is to get an array that represents the adjacent grid. This is basically like the ''Grid.linear'' function but with the ''times'' parameter omitted. Here are the examples
+<code ruby>Grid.surrounding(13, [1,2,3,4,6,7,8,9])  # Return [4, 5, 6, 12, 14, 20, 21, 22]</code>
+| 0 | 1 | 2 | 3 | @lightgreen:4 | @lightgreen:5 | @lightgreen:6 | 7 |
+| 8 | 9 | 10 | 11 | @lightgreen:12 | @orange:13 | @lightgreen:14 | 15 |
+| 16 | 17 | 18 | 19 | @lightgreen:20 | @lightgreen:21 | @lightgreen:22 | 23 |
+<code ruby>
+  Grid.surrounding(13, [2,4,6,8])  # Return [5, 12, 14, 21]
+</code>
+| 0 | 1 | 2 | 3 | 4 | @lightgreen:5 | 6 | 7 |
+| 8 | 9 | 10 | 11 | @lightgreen:12 | @orange:13 | @lightgreen:14 | 15 |
+| 16 | 17 | 18 | 19 | 20 | @lightgreen:21 | 22 | 23 |
+<code ruby>
+  Grid.surrounding(7, [1,2,3,4,6,7,8,9])  # Return [6, 14, 15]
+</code>
+| 0 | 1 | 2 | 3 | 4 | 5 | @lightgreen:6 | @orange:7 |
+| 8 | 9 | 10 | 11 | 12 | 13 | @lightgreen:14 | @lightgreen:15 |
+| 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 |
+==== Combining the direction ====
+Combining the functions is an essential part of the system. The targeting and area of effect are largely depending on how creative you're to combine these functions.
+{{https://i.imgur.com/3KEdN2Q.gif}}
+Supposed that we're going to replicate this. With red being the initial index, orange being the epicenter, then light green as the area of effect (plus the epicenter).
+| 0 | @lightgreen:1 | @lightgreen:2 | @lightgreen:3 | 4 | 5 | 6 | 7 |
+| @lightgreen:8 | @lightgreen:9 | @orange:10 | @lightgreen:11 | @lightgreen:12 | 13 | @#ff7777:14 | 15 |
+| 16 | @lightgreen:17 | @lightgreen:18 | @lightgreen:19 | 20 | 21 | 22 | 23 |
+The code can go like this.
+<code ruby>
+  epicenter = Grid.neighbor(14, 4, 4)
+  result = [epicenter] + Grid.linear(epicenter, [2,4,6,8], 2)
+  result += Grid.surrounding(epicenter, [1,3,7,9])
+  return result
+</code>
+It will yield an array with the value as ''[1, 2, 3, 8, 9, 10, 11, 12, 17, 18, 19]''. Note that in this particular example, the source index is hardcoded to 14. However, it can also be replaced with many things like the user position or the ''@center_grid'' as explained in the [[legacy:grid:targeting|targeting system]]
+===== Other Functions =====
+  This section is under construction and may be completed later
+  once the system is released
+{{tag>system mechanics grid}}