kamera

README

Kamera

Camera package for Ebitengine.

import "github.com/setanarut/kamera/v2"

Features

• Camera shake effect with fastnoise library noise types.
• Smooth camera movement with three interpolation modes:
  • None: Direct camera movement without smoothing
  • Lerp: Linear interpolation for smooth transitions
  • SmoothDamp: Spring-like motion with acceleration and deceleration and maximum speed.
• Rotate/Zoom

Usage

A pseudo code:

func (g *Game) Update() error {
  g.MainCamera.LookAt(player.X, player.Y)
  // Apply all world-space `playerDrawImageOptions.GeoM{}` transform here
 }
func (g *Game) Draw(screen *ebiten.Image) {
  g.MainCamera.Draw(playerImage, playerDrawImageOptions, screen)
 }

Examples

Platformer

Run platformer example on your local machine

go run github.com/setanarut/kamera/v2/examples/platformer@latest

Director

Run director example on your local machine

go run github.com/setanarut/kamera/v2/examples/director@latest

Documentation

Overview

Package kamera provides a camera object for Ebitengine v2.

Index

• type Camera
  • func NewCamera(lookAtX, lookAtY, w, h float64) *Camera
  • func (cam *Camera) ActualAngle() (angle float64)
  • func (cam *Camera) AddTrauma(factor float64)
  • func (cam *Camera) Angle() (angle float64)
  • func (cam *Camera) ApplyCameraTransform(geoM *ebiten.GeoM)
  • func (cam *Camera) ApplyCameraTransformToPoint(x, y float64) (float64, float64)
  • func (cam *Camera) Bottom() float64
  • func (cam *Camera) Center() (X float64, Y float64)
  • func (cam *Camera) Draw(worldObject *ebiten.Image, worldObjectOps *ebiten.DrawImageOptions, ...)
  • func (cam *Camera) DrawWithColorM(worldObject *ebiten.Image, cm colorm.ColorM, ...)
  • func (cam *Camera) Height() float64
  • func (cam *Camera) LookAt(targetX, targetY float64)
  • func (cam *Camera) Reset()
  • func (cam *Camera) Right() float64
  • func (cam *Camera) ScreenToWorld(screenX, screenY int) (worldX float64, worldY float64)
  • func (cam *Camera) SetAngle(angle float64)
  • func (cam *Camera) SetSize(w, h float64)
  • func (cam *Camera) SetTopLeft(x, y float64)
  • func (cam *Camera) String() string
  • func (cam *Camera) TopLeft() (X float64, Y float64)
  • func (cam *Camera) Width() float64
• type ShakeOptions
  • func DefaultCameraShakeOptions() *ShakeOptions
• type SmoothOptions
  • func DefaultSmoothOptions() *SmoothOptions
• type SmoothType

Types

type Camera

type Camera struct {
	// Top-left X position of camera
	TopLeftX float64
	// Top-left Y position of camera
	TopLeftY float64
	// ZoomFactor is the camera zoom (scaling) factor. Default is 1.
	ZoomFactor float64

	// SmoothType is the camera movement smoothing type.
	SmoothType SmoothType

	// SmoothOptions holds the camera movement smoothing settings
	SmoothOptions *SmoothOptions

	// If ShakeEnabled is false, AddTrauma() has no effect and shake is always 0.
	//
	// The default value is false
	ShakeEnabled           bool
	XAxisSmoothingDisabled bool
	YAxisSmoothingDisabled bool
	// ShakeOptions holds the camera shake options.
	ShakeOptions *ShakeOptions
	// contains filtered or unexported fields
}

Camera object.

Use the `Camera.LookAt()` to align the center of the camera to the target.

func NewCamera

func NewCamera(lookAtX, lookAtY, w, h float64) *Camera

NewCamera returns new Camera

func (*Camera) ActualAngle

func (cam *Camera) ActualAngle() (angle float64)

ActualAngle returns camera rotation angle (including the angle of trauma shaking.).

The unit is radian.

func (*Camera) AddTrauma

func (cam *Camera) AddTrauma(factor float64)

AddTrauma adds trauma. Factor is in the range [0-1]

func (*Camera) Angle

func (cam *Camera) Angle() (angle float64)

Angle returns camera rotation angle (The angle of trauma shake is not included.).

The unit is radian.

func (*Camera) ApplyCameraTransform

func (cam *Camera) ApplyCameraTransform(geoM *ebiten.GeoM)

ApplyCameraTransform applies geometric transformation to given geoM

func (*Camera) ApplyCameraTransformToPoint

func (cam *Camera) ApplyCameraTransformToPoint(x, y float64) (float64, float64)

ApplyCameraTransformToPoint applies camera transformation to given point

func (*Camera) Bottom

func (cam *Camera) Bottom() float64

Bottom returns the bottom edge position of the camera in world-space.

func (*Camera) Center

func (cam *Camera) Center() (X float64, Y float64)

Center returns center point of the camera in world-space

func (*Camera) Draw

func (cam *Camera) Draw(worldObject *ebiten.Image, worldObjectOps *ebiten.DrawImageOptions, screen *ebiten.Image)

Draw applies the Camera's geometric transformation then draws the object on the screen with drawing options.

func (*Camera) DrawWithColorM

func (cam *Camera) DrawWithColorM(worldObject *ebiten.Image, cm colorm.ColorM, worldObjectOps *colorm.DrawImageOptions, screen *ebiten.Image)

DrawWithColorM applies the Camera's geometric transformation then draws the object on the screen with colorm package drawing options.

func (*Camera) Height

func (cam *Camera) Height() float64

Height returns height of the camera

func (*Camera) LookAt

func (cam *Camera) LookAt(targetX, targetY float64)

LookAt aligns the midpoint of the camera viewport to the target.

Camera motion smoothing is only applied with this method. Use this function only once in Update() and change only the (targetX, targetY)

func (*Camera) Reset

func (cam *Camera) Reset()

Reset resets rotation and zoom factor to zero

func (*Camera) Right

func (cam *Camera) Right() float64

Right returns the right edge position of the camera in world-space.

func (*Camera) ScreenToWorld

func (cam *Camera) ScreenToWorld(screenX, screenY int) (worldX float64, worldY float64)

ScreenToWorld converts screen-space coordinates to world-space

func (*Camera) SetAngle

func (cam *Camera) SetAngle(angle float64)

SetAngle sets rotation. The unit is radian.

func (*Camera) SetSize

func (cam *Camera) SetSize(w, h float64)

SetSize sets camera rectangle size from center.

func (*Camera) SetTopLeft

func (cam *Camera) SetTopLeft(x, y float64)

SetTopLeft sets top-left position of the camera in world-space.

Unlike the LookAt() method, the position is set directly without any smoothing.

Useful for static cameras.

func (*Camera) String

func (cam *Camera) String() string

String returns camera values as string

func (*Camera) TopLeft

func (cam *Camera) TopLeft() (X float64, Y float64)

TopLeft returns top-left position of the camera in world-space

func (*Camera) Width

func (cam *Camera) Width() float64

Width returns width of the camera

type ShakeOptions

type ShakeOptions struct {
	// Noise generator for noise types and settings.
	Noise         *fastnoise.State[float64]
	MaxX          float64 // Maximum X-axis shake. 0 means disabled
	MaxY          float64 // Maximum Y-axis shake. 0 means disabled
	MaxAngle      float64 // Max shake angle (radians). 0 means disabled
	MaxZoomFactor float64 // Zoom factor strength [1-0]. 0 means disabled
	TimeScale     float64 // Noise time domain speed
	Decay         float64 // Decay for trauma
}

func DefaultCameraShakeOptions

func DefaultCameraShakeOptions() *ShakeOptions

type SmoothOptions

type SmoothOptions struct {
	// LerpSpeedX is the  X-axis linear interpolation speed every frame.
	// Value is in the range [0-1]. Default value is 0.09
	//
	// A smaller value will reach the target slower.
	LerpSpeedX float64
	// LerpSpeedY is the Y-axis linear interpolation speed every frame. Value is in the range [0-1].
	//
	// A smaller value will reach the target slower.
	LerpSpeedY float64

	// SmoothDampTimeX is the X-Axis approximate time it will take to reach the target.
	//
	// A smaller value will reach the target faster. Default value is 0.2
	SmoothDampTimeX float64
	// SmoothDampTimeY is the Y-Axis approximate time it will take to reach the target.
	//
	// A smaller value will reach the target faster. Default value is 0.2
	SmoothDampTimeY float64

	// SmoothDampMaxSpeedX is the maximum speed the camera can move while smooth damping in X-Axis
	//
	// Default value is 1000
	SmoothDampMaxSpeedX float64
	// SmoothDampMaxSpeedY is the maximum speed the camera can move while smooth damping in Y-Axis
	//
	// Default value is 1000
	SmoothDampMaxSpeedY float64
}

SmoothOptions is the camera movement smoothing options.

func DefaultSmoothOptions

func DefaultSmoothOptions() *SmoothOptions

type SmoothType

type SmoothType int

SmoothType is the camera movement smoothing type.

const (
	// None is instant movement to the target. No smoothing.
	None SmoothType = iota
	// Lerp is Lerp() function.
	Lerp
	// SmoothDamp is SmoothDamp() function.
	SmoothDamp
)