utils

README

2D-UTILS

A low-alloc, low time complexity, generics based utilities library for 2D games.

• Movement (lerping, normalization, drag...)
• Math (vectors, clamping, lerping...)
• Slices (remove, filter in place...)
• Tile (1D, 2D, conversions, slicing, safe indexing...)
• Timer (linear, delta, async...)
• Ammo container

BENCHMARKS for slice operations

cpu: Intel(R) Core(TM) i7-10510U CPU @ 1.80GHz

BenchmarkRemove-8        1000000000     1.137 ns/op    0 B/op    0 allocs/op
BenchmarkRemoveMany-8     872314512     1.554 ns/op    0 B/op    0 allocs/op
BenchmarkFilter-8            114692    101617 ns/op    0 B/op    0 allocs/op
BenchmarkInlinedFilter-8     334354    107903 ns/op    0 B/op    0 allocs/op

HOW TO TEST

$ go test ./...

HOW TO BENCHMARK

$ go test ./... -bench=.

Documentation

Index

• func Abs[T Number](n T) T
• func After(lock *bool, seconds float64, f func())
• func Clamp[T Number](n, low, high T) T
• func ClampIndexToMap[T Integer](index, mapWidth, mapHeight T) T
• func ClampXYToMap[T Integer](x, y, mapWidth, mapHeight T) (T, T)
• func Distance(x1, y1, x2, y2 float64) float64
• func DistanceManhattan[T Number](x1, y1, x2, y2 T) T
• func Every(seconds float64, f func()) context.CancelFunc
• func Filter[T any](s []T, f func(T) bool) []T
• func IndexToXY[T Integer](idx, mapWidth T) (x, y T)
• func IsIndexInRange[T Integer](index, mapWidth, mapHeight T) bool
• func IsXYInRange[T Integer](x, y, mapWidth, mapHeight T) bool
• func Lerp[T Number](start, end, t T) T
• func LerpEaseIn[T Number](start, end, t T) T
• func LerpEaseOut[T Number](start, end, t T) T
• func Magnitude[T Number](x, y T) T
• func Map[T any](s []T, f func(T) T) []T
• func MapTo[T, E any](s []T, f func(T) E) []E
• func MinOrZero[T Number](v, min T) T
• func Normalize[T Float](x, y T) (T, T)
• func Remove[T any](s []T, i int) []T
• func RemoveMany[T any](s []T, ii ...int) []T
• func Sqr[T Number](t T) T
• func TilesetRect[T Integer](sprite, tileSize, tilesetWidth T) (x1, y1, x2, y2 T)
• func XYRange[T Number](x1, y1, x2, y2 T) (T, T, T, T)
• func XYToIndex[T Integer](x, y, mapWidth T) T
• type AmmoContainer
  • func (a AmmoContainer[T]) CurrentAmmo(t T) uint
  • func (a AmmoContainer[T]) Take(t T, hasAlready, capacity uint) uint
• type Float
• type Integer
• type Mover
  • func NewMover[T Float](x, y, minimumVel, acc, drag T) (*Mover[T], error)
  • func (m *Mover[T]) AddMovement(x, y T)
  • func (m *Mover[T]) Update()
  • func (m *Mover[T]) UpdateDelta(delta T)
• type Number
• type Timer
  • func NewTimer[T Number](duration T) (*Timer[T], error)
  • func (t *Timer[T]) Finished() bool
  • func (t *Timer[T]) IsRunning() bool
  • func (t *Timer[T]) SetCurrentTime(time T)
  • func (t *Timer[T]) Start()
  • func (t *Timer[T]) Tick()
  • func (t *Timer[T]) TickDelta(delta T) error

Functions

func Abs

func Abs[T Number](n T) T

func After

func After(lock *bool, seconds float64, f func())

Runs f after seconds.

func Clamp

func Clamp[T Number](n, low, high T) T

func ClampIndexToMap

func ClampIndexToMap[T Integer](index, mapWidth, mapHeight T) T

Removes under/overflow.

func ClampXYToMap

func ClampXYToMap[T Integer](x, y, mapWidth, mapHeight T) (T, T)

Removes under/overflow.

func Distance

func Distance(x1, y1, x2, y2 float64) float64

func DistanceManhattan

func DistanceManhattan[T Number](x1, y1, x2, y2 T) T

func Every

func Every(seconds float64, f func()) context.CancelFunc

Runs f every seconds.

func Filter

func Filter[T any](s []T, f func(T) bool) []T

Mutates in place, no allocations.

func IndexToXY

func IndexToXY[T Integer](idx, mapWidth T) (x, y T)

1D to 2D coordinate conversion.

func IsIndexInRange

func IsIndexInRange[T Integer](index, mapWidth, mapHeight T) bool

func IsXYInRange

func IsXYInRange[T Integer](x, y, mapWidth, mapHeight T) bool

func Lerp

func Lerp[T Number](start, end, t T) T

func LerpEaseIn

func LerpEaseIn[T Number](start, end, t T) T

func LerpEaseOut

func LerpEaseOut[T Number](start, end, t T) T

func Magnitude

func Magnitude[T Number](x, y T) T

func Map

func Map[T any](s []T, f func(T) T) []T

Mutates in place, no allocations.

func MapTo

func MapTo[T, E any](s []T, f func(T) E) []E

Allocs new slice of type E the size of s.

func MinOrZero

func MinOrZero[T Number](v, min T) T

Minimum absolute value or zero.

func Normalize

func Normalize[T Float](x, y T) (T, T)

func Remove

func Remove[T any](s []T, i int) []T

Mutates in place, no allocations. Does not keep order.

func RemoveMany

func RemoveMany[T any](s []T, ii ...int) []T

Mutates in place, no allocations. Does not keep order.

func Sqr

func Sqr[T Number](t T) T

func TilesetRect

func TilesetRect[T Integer](sprite, tileSize, tilesetWidth T) (x1, y1, x2, y2 T)

1D index (sprite) to tileset rectangle. Assumes a square tileset.

sprite = 3, tileSize = N, tilesetWidth = 4
. . x x .
. . x x .
. . . . .
. . . . .

func XYRange

func XYRange[T Number](x1, y1, x2, y2 T) (T, T, T, T)

Returns range through min/max for XY.

func XYToIndex

func XYToIndex[T Integer](x, y, mapWidth T) T

2D to 1D coordinate conversion.

Types

type AmmoContainer

type AmmoContainer[T comparable] map[T]uint

func (AmmoContainer[T]) CurrentAmmo

func (a AmmoContainer[T]) CurrentAmmo(t T) uint

func (AmmoContainer[T]) Take

func (a AmmoContainer[T]) Take(t T, hasAlready, capacity uint) uint

type Float

type Float interface {
	constraints.Float
}

type Integer

type Integer interface {
	constraints.Signed | constraints.Unsigned
}

type Mover

type Mover[T Float] struct {
	PosX T
	PosY T

	DeltaX T
	DeltaY T

	MinimumVelocity T

	Acceleration T
	Drag         T
}

Normalized, lerped movement with drag.

func NewMover

func NewMover[T Float](x, y, minimumVel, acc, drag T) (*Mover[T], error)

func (*Mover[T]) AddMovement

func (m *Mover[T]) AddMovement(x, y T)

func (*Mover[T]) Update

func (m *Mover[T]) Update()

func (*Mover[T]) UpdateDelta

func (m *Mover[T]) UpdateDelta(delta T)

type Number

type Number interface {
	constraints.Integer | constraints.Float
}

type Timer

type Timer[T Number] struct {
	Duration    T
	CurrentTime T
}

Generic timer. Tick, TickDelta.

func NewTimer

func NewTimer[T Number](duration T) (*Timer[T], error)

Duration must be positive.

func (*Timer[T]) Finished

func (t *Timer[T]) Finished() bool

Resets timer on true.

func (*Timer[T]) IsRunning

func (t *Timer[T]) IsRunning() bool

func (*Timer[T]) SetCurrentTime

func (t *Timer[T]) SetCurrentTime(time T)

func (*Timer[T]) Start

func (t *Timer[T]) Start()

func (*Timer[T]) Tick

func (t *Timer[T]) Tick()

Increments by one.

func (*Timer[T]) TickDelta

func (t *Timer[T]) TickDelta(delta T) error

Increments by delta, which must be positive.