Modding:Area - Revision history

Game Hunter: format fixes

2012-01-23T19:21:45Z

format fixes

Game Hunter: fixed some explanation errors

2012-01-23T19:19:34Z

fixed some explanation errors

Game Hunter: area.new fix (thanks Simon-v)

2012-01-16T23:52:55Z

area.new fix (thanks Simon-v)

Game Hunter: quick definition fix

2012-01-15T02:46:02Z

quick definition fix

Game Hunter: quick format fixes

2012-01-15T02:16:28Z

quick format fixes

Show changes

Game Hunter: area doc added

2012-01-15T02:11:12Z

area doc added

New page

Areas describe a box of [[Modding:Coord|coords]], effectively representing a part of the potential map positions. They are mostly used as a superior alternative to a table of coords, and many of its API functions can be used to obtain coords from a given area.

== Properties ==
Although areas are technically userdata, they can be indexed like normal tables.

{|class="wikitable" style="border: 2px solid darkred; border-spacing: 0; font-size: 90%; margin: 0.25em 0.5em;"
! colspan="3" style="background: darkred; color: yellow; font-size: 120%; text-align: center"|'''Area'''
{{Table3Col
|es=background: #333;
|c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 3px;
|c2=vertical-align:top; padding:0px 2px;
|c3=padding:0px 2px;
|'''[[Modding:Coord|Coord]]'''|a|This is the upper-leftmost coord of the area.
|'''[[Modding:Coord|Coord]]'''|b|This is the bottom-rightmost coord of the area
|}}
|}

== API ==

{|class="wikitable" style="border: 2px solid darkred; border-spacing: 0; font-size: 90%; margin: 0.25em 0.5em;"
! colspan="2" style="background: darkred; color: yellow; font-size: 120%; text-align: center"|'''Area Interface'''
{{Table2Col
|es=background: #333;
|c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px;
|c2=padding:0px 2px;
|[[Modding:Area|Area]] |area.[[#area_new_coords|new]]([[Modding:Coord|Coord]] a, [[Modding:Coord|Coord]] b)
|[[Modding:Area|Area]] |area.[[#area_new_ints|new]]('''integer''' x, '''integer''' y, '''integer''' w, '''integer''' h)
|'''boolean''' |area.[[#area_eq|eq]]([[Modding:Area|Area]] lhs, [[Modding:Area|Area]], rhs)
|'''boolean''' |[[Modding:Area|Area]]:[[#area_contains_coord|contains]]( [[Modding:Coord|Coord]] c )
|'''boolean''' |[[Modding:Area|Area]]:[[#area_contains_area|contains]]( [[Modding:Area|Area]] a )
|'''boolean''' |[[Modding:Area|Area]]:[[#area_is_edge|is_edge]]( [[Modding:Coord|Coord]] c )
|[[Modding:Coord|Coord]] |[[Modding:Area|Area]]:[[#area_get|get]]()
|[[Modding:Coord|Coord]] |[[Modding:Area|Area]]:[[#area_dim|dim]]()
|'''integer''' |[[Modding:Area|Area]]:[[#area_size|size]]()
|[[Modding:Area|Area]] |[[Modding:Area|Area]]:[[#area_clone|clone]]()
|[[Modding:Area|Area]] |area.[[#area_around|around]]( [[Modding:Coord|Coord]] c, '''integer''' value )
|'''string''' |[[Modding:Area|Area]]:[[#area_tostring|tostring]]()
|[[Modding:Area|Area]] |[[Modding:Area|Area]]:[[#area_random_subarea|random_subarea]]( [[Modding:Coord|Coord]] dim )
|[[Modding:Coord|Coord]] |[[Modding:Area|Area]]:[[#area_random_coord|random_coord]]()
|[[Modding:Coord|Coord]] |[[Modding:Area|Area]]:[[#area_random_coord|random_edge_coord]]()
|[[Modding:Coord|Coord]] |[[Modding:Area|Area]]:[[#area_random_coord|random_inner_edge_coord]]()
|'''Void''' |[[Modding:Area|Area]]:[[#area_shrink|shrink]]( '''integer''' value )
|[[Modding:Area|Area]] |[[Modding:Area|Area]]:[[#area_shrinked|shrinked]]( '''integer''' value )
|'''Void''' |[[Modding:Area|Area]]:[[#area_expand|expand]]( '''integer''' value )
|[[Modding:Area|Area]] |[[Modding:Area|Area]]:[[#area_expanded|expanded]]( '''integer''' value )
|'''Void''' |[[Modding:Area|Area]]:[[#area_clamp|clamp]]( [[Modding:Area|Area]] a )
|[[Modding:Area|Area]] |[[Modding:Area|Area]]:[[#area_clamped|clamped]]( [[Modding:Area|Area]] a )
|'''void''' |[[Modding:Area|Area]]:[[#area_clamp_coord|clamp_coord]]( [[Modding:Coord|Coord]] c )
|'''Void''' |[[Modding:Area|Area]]:[[#area_fix|fix]]()
|'''boolean''' |[[Modding:Area|Area]]:[[#area_proper|proper]]()
|[[Modding:Coord|CoordIterator]]|[[Modding:Area|Area]]:[[#area_coords|coords]]()
|[[Modding:Coord|CoordIterator]]|[[Modding:Area|Area]]:[[#area_edges|edges]]()
|[[Modding:Coord|CoordIterator]]|[[Modding:Area|Area]]:[[#area_corners|corners]]()
|}}
|}

{{Anchor|area_new_coords}}
;area.new( [[Modding:Coord|Coord]] a, [[Modding:Coord|Coord]] b) → [[Modding:Area|Area]]
:This creates a new area, using a and b as the upper-left and bottom-right coords as the extent of the area.

{{Anchor|area_new_ints}}
;area.new( '''integer''' x1, '''integer''' y1, '''integer''' x2, '''integer''' y2) → [[Modding:Area|Area]]
:This creates a new area, using x1 and y1 as the upper-left position and x2 and y2 as the bottom-right position.
----
{{Anchor|area_eq}}
;coord.eq( [[Modding:Area|Area]] lhs, [[Modding:Area|Area]], rhs) → '''boolean'''
;[[Modding:Area|Area]] lhs == [[Modding:Area|Area]] rhs → '''boolean'''
:This determines if the given areas are coordinate-wise equal. (They might still be different objects! Beware using areas as table keys.)
----
{{Anchor|area_contains_coord}}
;[[Modding:Area|Area]]:contains( [[Modding:Coord|Coord]] c ) → '''boolean'''
This determines if '''c''' is contained in the given area.

{{Anchor|area_contains_area}}
;[[Modding:Area|Area]]:contains( [[Modding:Area|Area]] c ) → '''boolean'''
This determines if '''a''' is contained in the given area. '''a''' must be completely within the given area for this function to return a true value.
----
{{Anchor|area_is_edge}}
;[[Modding:Area|Area]]:is_edge( [[Modding:Coord|Coord]] c ) → '''boolean'''
This determines if '''c''' is an edge coord of the given area.
----
{{Anchor|area_get}}
;[[Modding:Area|Area]]:get() → '''[[Modding:Coord|Coord]]''', '''[[Modding:Coord|Coord]]'''
:Returns the upper-left and bottom-right coords of the area (in order).
----
{{Anchor|area_dim}}
;[[Modding:Area|Area]]:dim() → [[Modding:Coord|Coord]]
:Returns a coord representing the area's width in its x-coordinate and the area's height in its y-coordinate.
----
{{Anchor|area_size}}
;[[Modding:Area|Area]]:size() → '''integer'''
:Returns an integer equal to the produce of the area's height and width.
----
{{Anchor|area_clone}}
;[[Modding:Area|Area]]:clone() → [[Modding:Area|Area]]
:Returns a copy of the area.
----
{{Anchor|area_around}}
;area.around( [[Modding:Coord|Coord]] c, '''integer''' value) → [[Modding:Area|Area]]
:This creates an area around '''c''' whose edges extend by '''value''' from '''c'''. '''value''' is optional: it defaults to 1.
----
{{Anchor|area_tostring}}
;[[Modding:Area|Area]]:tostring() → '''string'''
:Returns a string containing the x1, y1, x2, and y2 positions separated by a comma. (x1 and y1 refer to the upper-left coordinate, while x2 and y2 refer to the bottom-right coordinate.)
----
{{Anchor|area_random_subarea}}
;[[Modding:Area|Area]]:random_subarea( [[Modding:Coord|Coord]] dim ) → [[Modding:Area|Area]]
Returns an random area in the given area of dimensions '''dim'''. (The new area will never lie on the bottom or right edges of the original area.)
----
{{Anchor|area_random_coord}}
;[[Modding:Area|Area]]:random_coord() → [[Modding:Coord|Coord]]
:Returns a random coord within the area.
----
{{Anchor|area_random_edge_coord}}
;[[Modding:Area|Area]]:random_edge_coord() → [[Modding:Coord|Coord]]
:Returns a random edge coord within the area.
----
{{Anchor|area_random_inner_edge_coord}}
;[[Modding:Area|Area]]:random_inner_edge_coord() → [[Modding:Coord|Coord]]
:Returns a random inner edge coord within the area. An inner edge coord is one that is also not a corner coord.
----
{{Anchor|area_shrink}}
;[[Modding:Area|Area]]:shrink( '''integer''' value )
:Shrinks each edge of the area by ''value''. ''value'' is optional: it defaults to 1. (''Warning'': this can cause the area to become invalid, such that the top-left coord is great than the bottom-right one).
----
{{Anchor|area_shrinked}}
;[[Modding:Area|Area]]:shrinked( '''integer''' value ) → [[Modding:Area|Area]]
:As shrink, except instead of changing the existing area, a new area is created.
----
{{Anchor|area_expand}}
;[[Modding:Area|Area]]:expand( '''integer''' value )
:Expands each edge of the area by ''value''. ''value'' is optional: it defaults to 1. (''Warning'': this can cause the area to become invalid, such that the top-left or bottom-right coords area beyond the scope of the map.
----
{{Anchor|area_shrinked}}
;[[Modding:Area|Area]]:expanded( '''integer''' value ) → [[Modding:Area|Area]]
:As expand, except instead of changing the existing area, a new area is created.
----
{{Anchor|area_clamp}}
;[[Modding:Area|Area]]:clamp( [[Modding:Area|Area]] a )
:Forces the area within the boundaries of '''a'''. Thus, if the original a has a top-left coordinate less than '''a''''s or a bottom-right coordinate greater than '''a''''s, that value will instead be set equal to '''a''''s. This can be used to validate an area changed by the :expand() function.
----
{{Anchor|area_clamped}}
;[[Modding:Area|Area]]:clamped( [[Modding:Area|Area]] a ) → [[Modding:Area|Area]]
:As clamp, except instead of changing the existing area, a new area is created.
----
{{Anchor|area_clamp_coord}}
;[[Modding:Area|Area]]:clamp_coord( [[Modding:Coord|Coord]] c ) → '''void'''
:Forces '''c''' within the boundaries of the given area. See [[#area_clamp|Area:clamp()]] for explanation.
----
{{Anchor|area_fix}}
;[[Modding:Area|Area]]:fix()
:Forces the area such that the top and left coordinates are at least equal to the bottom and right coordinates, respectively. This can be used to validate an area changed by the :shrink() function.
----
{{Anchor|area_proper}}
;[[Modding:Area|Area]]:proper() → '''boolean'''
:This determines if the top and left coordinates of the area are less than or equal to the bottom and right coordinates, respectively.
----
{{Anchor|area_coords}}
;[[Modding:Area|Area]]:coords() → [[Modding:Coord|Coord]] '''iterator'''
:Gives an iterator over all coords within the area. The iterator process begins in the upper-left coord and travels along each row from left to right, top to bottom.
----
{{Anchor|area_edges}}
;[[Modding:Area|Area]]:edges() → [[Modding:Coord|Coord]] '''iterator'''
:Gives an iterator over all edge coords within the area. An edge coord is determined as a coord that shares an x- or y-coordinate with the upper-left or bottom-right coords.
----
{{Anchor|area_corners}}
;[[Modding:Area|Area]]:corners() → [[Modding:Coord|Coord]] '''iterator'''
:Gives an iterator over all corner coords within the area. A corner coord is determine as a coord that is shares an x- and y-coordinate with the upper-left or bottom-right coords.

=== Constants ===
{|style="border: 2px solid darkred; border-spacing: 0; font-size: 90%; margin: 0.25em 0.5em;"
|colspan=3 style="background: darkred; color: yellow; font-size: 120%; text-align: center"|'''Constant Coords'''
|-
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|null
|style="vertical-align:top; padding-right: 2ex;"|area.FULL
|This is an area equal to the full extent of the map. It is equivalent to area.new(1,1,78,20).
|-style="background: #333;"
|style="text-align: right; vertical-align:top; padding-right: 2ex;"|null
|style="vertical-align:top; padding-right: 2ex;"|area.FULL_SHRINKED
|This is an area equal to the full extend of the map, excluding its boundaries. It is equivalent to area.new(2,2,77,19).
|}

@@ Line 57: / Line 57: @@
 {{Anchor|area_new_coords}}
 ;area.new('''[[Modding:Coord|Coord]]''' a, '''[[Modding:Coord|Coord]]''' b) &rarr; [[Modding:Area|Area]]
-:This creates a new area, using a and b as the upper-left and bottom-right coords as the extent of the area.
+:This creates a new area, using ''a'' and ''b'' as the upper-left and bottom-right coords as the extent of the area.
 {{Anchor|area_new_ints}}
 ;area.new('''integer''' x1, '''integer''' y1, '''integer''' x2, '''integer''' y2) &rarr; [[Modding:Area|Area]]
-:This creates a new area, using x1 and y1 as the upper-left position and x2 and y2 as the bottom-right position.
+:This creates a new area, using ''x1'' and ''y1'' as the upper-left position and ''x2'' and ''y2'' as the bottom-right position. Using this definition is the same as area.new( coord.new(''x1'',''y1''), coord.new(''x2'',''y2'') ).
 ----
 {{Anchor|area_eq}}
@@ Line 146: / Line 146: @@
 {{Anchor|area_clamp_coord}}
 ;[[Modding:Area|Area]]&#058;clamp_coord('''[[Modding:Coord|Coord]]''' c) &rarr; '''void'''
-:Forces ''c'' within the boundaries of the given area. See [[#area_clamp|Area:clamp()]] for explanation.
+:Forces ''c'' within the boundaries of the given area. See [[#area_clamp|:clamp()]] for explanation.
 ----
 {{Anchor|area_fix}}

@@ Line 70: / Line 70: @@
 {{Anchor|area_contains_coord}}
 ;[[Modding:Area|Area]]&#058;contains('''[[Modding:Coord|Coord]]''' c) &rarr; '''boolean'''
-This determines if '''c''' is contained in the given area.
+This determines if ''c''' is contained in the given area.
 {{Anchor|area_contains_area}}
 ;[[Modding:Area|Area]]&#058;contains([[Modding:Area|Area]] c) &rarr; '''boolean'''
-This determines if '''a''' is contained in the given area. '''a''' must be completely within the given area for this function to return a true value.
+This determines if ''a'' is contained in the given area. ''a''' must be completely within the given area for this function to return a true value.
 ----
 {{Anchor|area_is_edge}}
@@ Line 82: / Line 82: @@
 {{Anchor|area_get}}
 ;[[Modding:Area|Area]]&#058;get() &rarr; '''[[Modding:Coord|Coord]]''', '''[[Modding:Coord|Coord]]'''
-:Returns the upper-left and bottom-right coords of the area (in order).
+:Returns the upper-left and bottom-right coords of the area (in that order).
 ----
 {{Anchor|area_dim}}
@@ Line 90: / Line 90: @@
 {{Anchor|area_size}}
 ;[[Modding:Area|Area]]&#058;size() &rarr; '''integer'''
-:Returns an integer equal to the produce of the area's height and width.
+:Returns an integer equal to the product of the area's height and width.
 ----
 {{Anchor|area_clone}}
 ;[[Modding:Area|Area]]&#058;clone() &rarr; [[Modding:Area|Area]]
-:Returns a copy of the area.
+:Returns a copy of the area. This is important if you are, for example, using a coordinate iterator to select particular coordinates and store them in a table.
 ----
 {{Anchor|area_around}}
 ;area.around('''[[Modding:Coord|Coord]]''' c, '''integer''' value) &rarr; [[Modding:Area|Area]]
-:This creates an area around '''c''' whose edges extend by '''value''' from '''c'''. '''value''' is optional: it defaults to 1.
+:This creates an area around ''c''' whose edges extend by ''value'' from ''c'''. '''value''' is optional: it defaults to 1.
 ----
 {{Anchor|area_tostring}}
@@ Line 106: / Line 106: @@
 {{Anchor|area_random_subarea}}
 ;[[Modding:Area|Area]]&#058;random_subarea('''[[Modding:Coord|Coord]]''' dim) &rarr; [[Modding:Area|Area]]
-Returns an random area in the given area of dimensions '''dim'''. (The new area will never lie on the bottom or right edges of the original area.)
+Returns an random area in the given area of dimensions ''dim''' = coord.new(''width'',''height''). (The new area will never lie on the bottom or right edges of the original area.)
 ----
 {{Anchor|area_random_coord}}
@@ Line 122: / Line 122: @@
 {{Anchor|area_shrink}}
 ;[[Modding:Area|Area]]&#058;shrink('''integer''' value)
-:Shrinks each edge of the area by ''value''. ''value'' is optional: it defaults to 1. (''Warning'': this can cause the area to become invalid, such that the top-left coord is great than the bottom-right one).
+:Shrinks each edge of the area by ''value''. ''value'' is optional: it defaults to 1. (''Warning'': this can cause the area to become invalid, such that the top-left coord is greater than the bottom-right one).
 ----
 {{Anchor|area_shrinked}}
@@ Line 138: / Line 138: @@
 {{Anchor|area_clamp}}
 ;[[Modding:Area|Area]]&#058;clamp([[Modding:Area|Area]] a)
-:Forces the area within the boundaries of '''a'''. Thus, if the original a has a top-left coordinate less than '''a''''s or a bottom-right coordinate greater than '''a''''s, that value will instead be set equal to '''a''''s. This can be used to validate an area changed by the :expand() function.
+:Forces the area within the boundaries of ''a''. Thus, if the original a has a top-left coordinate less than ''a'''s or a bottom-right coordinate greater than <i>a</i>'s, that value will instead be set equal to <i>a</i>'s. This can be used to validate an area changed by the :expand() function.
 ----
 {{Anchor|area_clamped}}
@@ Line 146: / Line 146: @@
 {{Anchor|area_clamp_coord}}
 ;[[Modding:Area|Area]]&#058;clamp_coord('''[[Modding:Coord|Coord]]''' c) &rarr; '''void'''
-:Forces '''c''' within the boundaries of the given area. See [[#area_clamp|Area:clamp()]] for explanation.
+:Forces ''c'' within the boundaries of the given area. See [[#area_clamp|Area:clamp()]] for explanation.
 ----
 {{Anchor|area_fix}}

@@ Line 25: / Line 25: @@
    |c2=padding:0px 2px;
    |[[Modding:Area|Area]]          |area.[[#area_new_coords|new]]([[Modding:Coord|Coord]] a, [[Modding:Coord|Coord]] b)
-   |[[Modding:Area|Area]]          |area.[[#area_new_ints|new]]('''integer''' x, '''integer''' y, '''integer''' w, '''integer''' h)
+   |[[Modding:Area|Area]]          |area.[[#area_new_ints|new]]('''integer''' x1, '''integer''' y1, '''integer''' x2, '''integer''' y2)
    |'''boolean'''                  |area.[[#area_eq|eq]]([[Modding:Area|Area]] lhs, [[Modding:Area|Area]], rhs)
    |'''boolean'''                  |[[Modding:Area|Area]]&#058;[[#area_contains_coord|contains]]([[Modding:Coord|Coord]] c)

@@ Line 78: / Line 78: @@
 {{Anchor|area_is_edge}}
 ;[[Modding:Area|Area]]&#058;is_edge('''[[Modding:Coord|Coord]]''' c) &rarr; '''boolean'''
-This determines if '''c''' is an edge coord of the given area.
+This determines if '''c''' is an edge coord of the given area. An edge coord is determined as a coord that shares an x- or y-coordinate with the upper-left or bottom-right coords.
 ----
 {{Anchor|area_get}}
@@ Line 162: / Line 162: @@
 {{Anchor|area_edges}}
 ;[[Modding:Area|Area]]&#058;edges() &rarr; '''[[Modding:Coord|Coord]] iterator'''
-:Gives an iterator over all edge coords within the area. An edge coord is determined as a coord that shares an x- or y-coordinate with the upper-left or bottom-right coords.
+:Gives an iterator over all edge coords within the area.
 ----
 {{Anchor|area_corners}}