From f42198ce278270c843983f58302f73097eb6b9e0 Mon Sep 17 00:00:00 2001 From: Matthias Richter Date: Thu, 12 Aug 2010 17:43:47 +0200 Subject: [PATCH] Ported half of the documentation --- index.html | 469 ++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 406 insertions(+), 63 deletions(-) diff --git a/index.html b/index.html index 01fd565..fea305c 100644 --- a/index.html +++ b/index.html @@ -1,78 +1,421 @@ +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + + hump - LÖVE Helper Utilities for More Productivity + - + ul.nav { display:inline; margin-left: 0; padding-left: 0; } + ul.nav li { display:inline; margin-right: 1em; } + + a.top { font-size: .2em; margin-left: 1em; float: right; } + + .doc { padding-left: 1em; margin-bottom: 1em; border-left: 1px dotted #aaa; } + .function { display:block; font-weight:bold; font-family: fixed; background: #f9f9f9; border:1px solid #ddd; margin-left: -1em; } + + .functionlist { border-left: 1px dotted #aaa; margin: -.6em 0 0 2em; } + .functionlist a { text-decoration: none; font-weight:bold; color: #506060; } + .functionlist a:hover { color: black; } + + .doc table { margin-top: 5px; } + th { text-align: left; font-weight: normal; font-style: italic; text-decoration: underline; } + td { padding-left: 1em; } + .doc td em { font-size: .8em; font-weight:bold; font-style:normal; padding-right: .6em;} + + .doc pre, code { color: black; padding: 0; font-family: fixed; border: 1px solid #ddd; background: #e7ecec; } + + - Fork me on GitHub + Fork me on GitHub -
+ +
+ +

hump + Helper Utilities for More Productivity

+ + + + +

Introduction^ top

+

Helper Utilities for a Multitude of Problems is a set of lightweight helpers + for the excellent LÖVE Engine.

+ +

It currently features +

    +
  • vector.lua: a mature vector type,
    • +
  • class.lua: a simple and easy class system with function inheritance,
    • +
  • camera.lua: a translate-, zoom- and rotatable camera and
    • +
  • gamestate.lua: a gamestate system.
    • +

+ +

hump differs from other libraries in that every component is independent of the + remaining ones (apart from camera.lua, which depends on the vector type). + hump's footprint is very small and thus should fit nicely into your projects.

+ + +

Documentation^ top

+ + Below is the documentation of the various modules. You can directly jump to a + module by clicking these: + + +
+ +

vector.lua^ top

+

A vector class implementing everything you want to do with vectors, and some more.

+

Overview (click item for more details): + + + + + + + + + + + + + + +
vector(x,y)constructor
isvector(v)type check
Vector:clone()deep copy
Vector:unpack()element unfolding
OperatorsArithmetics and ordering
vector:permul(other)per-element multiplication
vector:len()vector length
vector:len2()squared vector length
vector:dist(other)distance to vector
vector:normalized()normalize vector
vector:normalize_inplace()normalize vector in-place
Vector:rotated(phi)rotate vector
Vector:rotate_inplace(phi)rotate vector in-place

+ + +
function vector(x,y)^ top + Creates a new vector. Element access with v.x and v.y. + + + + +
Parameters:[number]x:x coordinate
[number]y:y coordinate
Returns:the vector
+
+ + +
function isvector(v)^ top + Tests for vector type. + + + +
Parameters:vvariable to test
Returns:true if v is a vector
+
+ + +
function vector:clone()^ top + Clones a vector. Use when you do not want to create references. + + +
Returns:New vector with the same coordinates.
+
+ + +
function vector:unpack()^ top + Unpacks the vector. + + + + +
Returns:the coordinate tuple x, y
Example:
v = vector(1,2)
+print(v:unpack()) -- prints "1     2"
+
+ + +
Operators^ top +

Arithmetic (+, -, *, /) and + comparative operators (==, <=, <) are defined:

+ +
    +
  • + and - only work on vectors. - is also + the unary minus (e.g. print(-vector(1,2)) -- prints (-1,-2))
    • +
  • a * b works on vectors and numbers:
      +
    • If a is a number and b is a vector (or vice versa), + the result the scalar multiplication.
      • +
    • If a and b both are vectors, then the result is the + dot product.
    • +
  • a / b is only defined for a being a vector and b + being a number. Same as a * 1/b.
    • +
+ +

<= and < sort lexically, i.e. a < b + is true if it holds: a.x < b.x or a.y < b.y if + a.x == b.x

+
+ + +
function vector:permul(other)^ top + Perform element-wise multiplication. +
+ + +
function vector:len()^ top + Get length of vector. +
+ + +
function vector:len2()^ top + Get squared length. +
+ + +
function vector:dist(other)^ top + Get distance to other vector. + + + +
Example:
a,b = vector(0,1), vector(1,0)
+print(a:dist(b)) -- prints 1.4142135623731
+
+ + +
function vector:normalized()^ top + Get normalized vector. The original vector remains unchanged. +
+ + +
function vector:normalize_inplace()^ top + Normalize vector and return it. +

Warning: This will change the state of all references to this vector.

+
+ + +
function vector:rotated(phi)^ top + Get rotated vector. The original vector remains unchanged. + + +
Parameters:[number]phi:Rotation angle in radians.
+
+ + +
function vector:rotate_inplace(phi)^ top + Rotate the vector and return it. +

Warning: This will change the state of all references to this vector.

+
+
+ + +
+ +

class.lua^ top

+

class.lua provides a simple and easy to use class system. Albeit it's + limitations, class.lua offers multiple inheritance and minimal + reflection capabilities. Note that only methods will be inherited + and runtime changes of a superclass won't affect subclasses.

+

The module only consists of three functions: + + + + + +
Class(constructor)define class
Class{name = name, constructor}define named class
Interface(name)define interface
Inherit(class, super, ...)subclassing

+

For an example, see below. Also be sure to read the + warning regarding metamethods.

+ + +
function Class(constructor)^ top + Creates a new unnamed class. + + + + + + +
Parameters:[optional function]constructorA function used to construct the class. The first parameter of this function + is the object, the others are parameters given upon construction.
Returns:the new class
Example
Feline = Class(function(self, size, weight)
+    self.size = size self.weight = weight
+end)
+
+function Feline:stats()
+    return string.format("size: %.02f, weight %.02f", self.size, self.weight) 
+end
+
+garfield = Feline(.7, 45)
+felix = Feline(.8, 12)
+
+print("Garfield: " .. garfield:stats(), "Felix: " .. felix:stats())
+
+ + +
function Class{name = name, constructor}^ top + Create a named class, i.e. define a __tostring metamethod. Parameters are the same as above. + Great for debugging. Both name and constructor can be omitted (but why would you want to?) + + + +
Example:
Feline = Class{name = "Feline", function(self, size, weight)
+    self.size = size self.weight = weight
+end}
+
+print(Feline) -- prints 'Feline'
+
+ + +
function Interface(name)^ top + Shortcut to Class{name = name}, i.e. a possibly named class without constructor. +
+ + +
function Inherit(class, super, ...)^ top + Add functions of super to class. Multiple interfaces can be defined. +

super's constructor can be accessed via super.construct(self). See example below.

+
+ + +

Example usage

+
Everybody loves cats!^ top +
Feline = Class{name = "Feline", function(self, size, weight)
+    self.size = size self.weight = weight
+end}
+
+function Feline:stats()
+    return string.format("size: %.02f, weight %.02f", self.size, self.weight) 
+end
+
+function Feline:speak() print("meow") end
+
+
+Cat = Class{name = "Cat", function(self, name, size, weight)
+    Feline.construct(self, size, weight)
+    self.name = name
+end}
+Inherit(Cat, Feline)
+
+function Cat:stats()
+    return string.format("name: %s, %s", self.name, Feline.stats(self))
+end
+
+
+Tiger = Class{name = "tiger", function(self, size, weight)
+    Feline.construct(self, size, weight)
+end}
+Inherit(Tiger, Feline)
+
+function Tiger:speak() print("ROAR!") end
+
+felix = Cat("Felix", .8, 12)
+hobbes = Tiger(2.2, 68)
+
+print(felix:stats(), hobbes:stats())
+felix:speak()
+hobbes:speak()
+
+ + +

Warning

+
Nothing is perfect^ top +

Be careful when using metamethods like __add or __mul: + When subclass inherits those methods from a superclass, but does not overwrite + them, the result of the operation may be of the type superclass. Consider the following:

+
A = Class(function(self, x) self.x = x end)
+function A:__add(other) return A(self.x + other.x) end
+function A:print() print("A:", self.x) end
+
+B = Class(function(self, x, y) A.construct(self, x) self.y = y end)
+Inherit(B, A)
+function B:print() print("B:", self.x, self.y) end
+function B:foo() print("foo") end
+
+one, two = B(1,2), B(3,4)
+result = one + two
+result:print()  -- prints "A:    4"
+result:foo()    -- error: method does not exist
+
+
+ +
+ +

camera.lua^ top

+ Depends on vector.lua +

Camera object to display only a partial region of the game world. The region + can be zoomed and rotated. You can transform camera coordinates to world coordinated + (e.g. get the location of the mouse in the game world). It is possible to have + more than one camera per game.

+
+ +
+ +

gamestate.lua^ top

+
+ + + +

License^ top

+ +

Yay, free software:

+ +

Copyright (c) 2010 Matthias Richter

+

Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions:

+ +

The above copyright notice and this permission notice shall be included in + all copies or substantial portions of the Software.

+ +

Except as contained in this notice, the name(s) of the above copyright holders + shall not be used in advertising or otherwise to promote the sale, use or + other dealings in this Software without prior written authorization.

+ +

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + THE SOFTWARE.

+ + +

Download^ top

+ +

You can download this project in either + zip or + tar formats.

+

You can also clone the project with Git by running: + 

$ git clone git://github.com/vrld/hump

+ +
+ get the source code on GitHub : vrld/hump +
-
- - - -
-

hump - by vrld

-
- LÖVE Helper Utilities for Massive Progression -
- -

Authors

-

vrld

- - -

Download

-

- You can download this project in either - zip or - tar formats. -

-

You can also clone the project with Git - by running: - 

$ git clone git://github.com/vrld/hump
-

- -
- get the source code on GitHub : vrld/hump -
- -
- -