Difference between revisions of "Modding:Area"

From DoomRL Wiki

Jump to: navigation, search
(area doc added)
 
m (quick format fixes)
Line 27: Line 27:
 
   |[[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''' x, '''integer''' y, '''integer''' w, '''integer''' h)  
 
   |'''boolean'''                  |area.[[#area_eq|eq]]([[Modding:Area|Area]] lhs, [[Modding:Area|Area]], rhs)  
 
   |'''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_coord|contains]]([[Modding:Coord|Coord]] c)
   |'''boolean'''                  |[[Modding:Area|Area]]:[[#area_contains_area|contains]]( [[Modding:Area|Area]] a )
+
   |'''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 )
+
   |'''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_get|get]]()  
 
   |[[Modding:Coord|Coord]]        |[[Modding:Area|Area]]:[[#area_dim|dim]]()
 
   |[[Modding:Coord|Coord]]        |[[Modding:Area|Area]]:[[#area_dim|dim]]()
 
   |'''integer'''                  |[[Modding:Area|Area]]:[[#area_size|size]]()
 
   |'''integer'''                  |[[Modding:Area|Area]]:[[#area_size|size]]()
 
   |[[Modding:Area|Area]]          |[[Modding:Area|Area]]:[[#area_clone|clone]]()  
 
   |[[Modding:Area|Area]]          |[[Modding:Area|Area]]:[[#area_clone|clone]]()  
   |[[Modding:Area|Area]]          |area.[[#area_around|around]]( [[Modding:Coord|Coord]] c, '''integer''' value )
+
   |[[Modding:Area|Area]]          |area.[[#area_around|around]]( [[Modding:Coord|Coord]] c, '''integer''' value)
 
   |'''string'''                  |[[Modding:Area|Area]]:[[#area_tostring|tostring]]()  
 
   |'''string'''                  |[[Modding:Area|Area]]:[[#area_tostring|tostring]]()  
   |[[Modding:Area|Area]]          |[[Modding:Area|Area]]:[[#area_random_subarea|random_subarea]]( [[Modding:Coord|Coord]] dim )
+
   |[[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_coord]]()
 
   |[[Modding:Coord|Coord]]        |[[Modding:Area|Area]]:[[#area_random_coord|random_edge_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]]()
 
   |[[Modding:Coord|Coord]]        |[[Modding:Area|Area]]:[[#area_random_coord|random_inner_edge_coord]]()
   |'''Void'''                    |[[Modding:Area|Area]]:[[#area_shrink|shrink]]( '''integer''' value )
+
   |'''Void'''                    |[[Modding:Area|Area]]:[[#area_shrink|shrink]]('''integer''' value)
   |[[Modding:Area|Area]]          |[[Modding:Area|Area]]:[[#area_shrinked|shrinked]]( '''integer''' value )
+
   |[[Modding:Area|Area]]          |[[Modding:Area|Area]]:[[#area_shrinked|shrinked]]('''integer''' value)
   |'''Void'''                    |[[Modding:Area|Area]]:[[#area_expand|expand]]( '''integer''' value )
+
   |'''Void'''                    |[[Modding:Area|Area]]:[[#area_expand|expand]]('''integer''' value)
   |[[Modding:Area|Area]]          |[[Modding:Area|Area]]:[[#area_expanded|expanded]]( '''integer''' value )
+
   |[[Modding:Area|Area]]          |[[Modding:Area|Area]]:[[#area_expanded|expanded]]('''integer''' value)
   |'''Void'''                    |[[Modding:Area|Area]]:[[#area_clamp|clamp]]( [[Modding:Area|Area]] a )
+
   |'''Void'''                    |[[Modding:Area|Area]]:[[#area_clamp|clamp]]([[Modding:Area|Area]] a)
   |[[Modding:Area|Area]]          |[[Modding:Area|Area]]:[[#area_clamped|clamped]]( [[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_clamp_coord|clamp_coord]]([[Modding:Coord|Coord]] c)
 
   |'''Void'''                    |[[Modding:Area|Area]]:[[#area_fix|fix]]()
 
   |'''Void'''                    |[[Modding:Area|Area]]:[[#area_fix|fix]]()
 
   |'''boolean'''                  |[[Modding:Area|Area]]:[[#area_proper|proper]]()
 
   |'''boolean'''                  |[[Modding:Area|Area]]:[[#area_proper|proper]]()
Line 56: Line 56:
  
 
{{Anchor|area_new_coords}}
 
{{Anchor|area_new_coords}}
;area.new( [[Modding:Coord|Coord]] a, [[Modding:Coord|Coord]] b) → [[Modding:Area|Area]]
+
;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.
 
: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}}
 
{{Anchor|area_new_ints}}
;area.new( '''integer''' x1, '''integer''' y1, '''integer''' x2, '''integer''' y2) → [[Modding:Area|Area]]
+
;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.
 
:This creates a new area, using x1 and y1 as the upper-left position and x2 and y2 as the bottom-right position.
 
----
 
----
Line 69: Line 69:
 
----
 
----
 
{{Anchor|area_contains_coord}}
 
{{Anchor|area_contains_coord}}
;[[Modding:Area|Area]]:contains( [[Modding:Coord|Coord]] c ) → '''boolean'''
+
;[[Modding:Area|Area]]:contains('''[[Modding:Coord|Coord]]''' c) → '''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}}
 
{{Anchor|area_contains_area}}
;[[Modding:Area|Area]]:contains( [[Modding:Area|Area]] c ) → '''boolean'''
+
;[[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.
 
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}}
 
{{Anchor|area_is_edge}}
;[[Modding:Area|Area]]:is_edge( [[Modding:Coord|Coord]] c ) → '''boolean'''
+
;[[Modding:Area|Area]]:is_edge('''[[Modding:Coord|Coord]]''' c) → '''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.
 
----
 
----
Line 85: Line 85:
 
----
 
----
 
{{Anchor|area_dim}}
 
{{Anchor|area_dim}}
;[[Modding:Area|Area]]:dim() → [[Modding:Coord|Coord]]
+
;[[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.
 
:Returns a coord representing the area's width in its x-coordinate and the area's height in its y-coordinate.
 
----
 
----
Line 97: Line 97:
 
----
 
----
 
{{Anchor|area_around}}
 
{{Anchor|area_around}}
;area.around( [[Modding:Coord|Coord]] c, '''integer''' value) → [[Modding:Area|Area]]
+
;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.
 
:This creates an area around '''c''' whose edges extend by '''value''' from '''c'''. '''value''' is optional: it defaults to 1.
 
----
 
----
Line 105: Line 105:
 
----
 
----
 
{{Anchor|area_random_subarea}}
 
{{Anchor|area_random_subarea}}
;[[Modding:Area|Area]]:random_subarea( [[Modding:Coord|Coord]] dim ) → [[Modding:Area|Area]]
+
;[[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.)
 
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}}
 
{{Anchor|area_random_coord}}
;[[Modding:Area|Area]]:random_coord() → [[Modding:Coord|Coord]]
+
;[[Modding:Area|Area]]:random_coord() → '''[[Modding:Coord|Coord]]'''
 
:Returns a random coord within the area.
 
:Returns a random coord within the area.
 
----
 
----
 
{{Anchor|area_random_edge_coord}}
 
{{Anchor|area_random_edge_coord}}
;[[Modding:Area|Area]]:random_edge_coord() → [[Modding:Coord|Coord]]
+
;[[Modding:Area|Area]]:random_edge_coord() → '''[[Modding:Coord|Coord]]'''
 
:Returns a random edge coord within the area.
 
:Returns a random edge coord within the area.
 
----
 
----
 
{{Anchor|area_random_inner_edge_coord}}
 
{{Anchor|area_random_inner_edge_coord}}
;[[Modding:Area|Area]]:random_inner_edge_coord() → [[Modding:Coord|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.
 
: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}}
 
{{Anchor|area_shrink}}
;[[Modding:Area|Area]]:shrink( '''integer''' value )
+
;[[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).
 
: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}}
 
{{Anchor|area_shrinked}}
;[[Modding:Area|Area]]:shrinked( '''integer''' value ) → [[Modding:Area|Area]]
+
;[[Modding:Area|Area]]:shrinked('''integer''' value) → [[Modding:Area|Area]]
 
:As shrink, except instead of changing the existing area, a new area is created.
 
:As shrink, except instead of changing the existing area, a new area is created.
 
----
 
----
 
{{Anchor|area_expand}}
 
{{Anchor|area_expand}}
;[[Modding:Area|Area]]:expand( '''integer''' value )
+
;[[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.
 
: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}}
 
{{Anchor|area_shrinked}}
;[[Modding:Area|Area]]:expanded( '''integer''' value ) → [[Modding:Area|Area]]
+
;[[Modding:Area|Area]]:expanded('''integer''' value) → [[Modding:Area|Area]]
 
:As expand, except instead of changing the existing area, a new area is created.
 
:As expand, except instead of changing the existing area, a new area is created.
 
----
 
----
 
{{Anchor|area_clamp}}
 
{{Anchor|area_clamp}}
;[[Modding:Area|Area]]:clamp( [[Modding:Area|Area]] a )
+
;[[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.
 
: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}}
 
{{Anchor|area_clamped}}
;[[Modding:Area|Area]]:clamped( [[Modding:Area|Area]] a ) → [[Modding:Area|Area]]
+
;[[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.
 
:As clamp, except instead of changing the existing area, a new area is created.
 
----
 
----
 
{{Anchor|area_clamp_coord}}
 
{{Anchor|area_clamp_coord}}
;[[Modding:Area|Area]]:clamp_coord( [[Modding:Coord|Coord]] c ) → '''void'''
+
;[[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.
 
:Forces '''c''' within the boundaries of the given area. See [[#area_clamp|Area:clamp()]] for explanation.
 
----
 
----
Line 157: Line 157:
 
----
 
----
 
{{Anchor|area_coords}}
 
{{Anchor|area_coords}}
;[[Modding:Area|Area]]:coords() → [[Modding:Coord|Coord]] '''iterator'''
+
;[[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.
 
: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}}
 
{{Anchor|area_edges}}
;[[Modding:Area|Area]]:edges() → [[Modding:Coord|Coord]] '''iterator'''
+
;[[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.
 
: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}}
 
{{Anchor|area_corners}}
;[[Modding:Area|Area]]:corners() → [[Modding:Coord|Coord]] '''iterator'''
+
;[[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.
 
: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.
  

Revision as of 02:16, 15 January 2012

Areas describe a box of 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.

Area
Coord a This is the upper-leftmost coord of the area.
Coord b This is the bottom-rightmost coord of the area

API

Area Interface
Area area.new(Coord a, Coord b)
Area area.new(integer x, integer y, integer w, integer h)
boolean area.eq(Area lhs, Area, rhs)
boolean Area:contains(Coord c)
boolean Area:contains(Area a)
boolean Area:is_edge(Coord c)
Coord Area:get()
Coord Area:dim()
integer Area:size()
Area Area:clone()
Area area.around( Coord c, integer value)
string Area:tostring()
Area Area:random_subarea(Coord dim)
Coord Area:random_coord()
Coord Area:random_edge_coord()
Coord Area:random_inner_edge_coord()
Void Area:shrink(integer value)
Area Area:shrinked(integer value)
Void Area:expand(integer value)
Area Area:expanded(integer value)
Void Area:clamp(Area a)
Area Area:clamped(Area a)
void Area:clamp_coord(Coord c)
Void Area:fix()
boolean Area:proper()
CoordIterator Area:coords()
CoordIterator Area:edges()
CoordIterator Area:corners()

area.new(Coord a, Coord b) → Area
This creates a new area, using a and b as the upper-left and bottom-right coords as the extent of the area.

area.new(integer x1, integer y1, integer x2, integer y2) → Area
This creates a new area, using x1 and y1 as the upper-left position and x2 and y2 as the bottom-right position.

coord.eq( Area lhs, Area, rhs) → boolean
Area lhs == 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.)

Area:contains(Coord c) → boolean

This determines if c is contained in the given area.

Area:contains(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.


Area:is_edge(Coord c) → boolean

This determines if c is an edge coord of the given area.


Area:get() → Coord, Coord
Returns the upper-left and bottom-right coords of the area (in order).

Area:dim() → Coord
Returns a coord representing the area's width in its x-coordinate and the area's height in its y-coordinate.

Area:size() → integer
Returns an integer equal to the produce of the area's height and width.

Area:clone() → Area
Returns a copy of the area.

area.around(Coord c, integer value) → Area
This creates an area around c whose edges extend by value from c. value is optional: it defaults to 1.

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.)

Area:random_subarea(Coord dim) → 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.)


Area:random_coord() → Coord
Returns a random coord within the area.

Area:random_edge_coord() → Coord
Returns a random edge coord within the area.

Area:random_inner_edge_coord() → Coord
Returns a random inner edge coord within the area. An inner edge coord is one that is also not a corner coord.

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).

Area:shrinked(integer value) → Area
As shrink, except instead of changing the existing area, a new area is created.

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.

Area:expanded(integer value) → Area
As expand, except instead of changing the existing area, a new area is created.

Area:clamp(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.

Area:clamped(Area a) → Area
As clamp, except instead of changing the existing area, a new area is created.

Area:clamp_coord(Coord c) → void
Forces c within the boundaries of the given area. See Area:clamp() for explanation.

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.

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.

Area:coords() → 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.

Area:edges() → 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.

Area:corners() → 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

Constant Coords
null area.FULL This is an area equal to the full extent of the map. It is equivalent to area.new(1,1,78,20).
null 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).
Personal tools