world

package
v0.0.0-...-a3e6692 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 14, 2024 License: CC0-1.0 Imports: 31 Imported by: 3

Documentation

Overview

Package world helps developers implement a Mechane world.

Index

Constants

View Source 
const (
	DefaultIconStyle      = mech.RoundStyle
	DefaultOffIconColour  = "darkGray" // Used for button types with off states.
	DefaultOriginPosition = mechtree.TopLeft
	DefaultTheme          = MechaneOrange
)
View Source 
const (
	Fast   = LoopsPerSec(60)
	Medium = LoopsPerSec(30)
	Slow   = LoopsPerSec(5)
)

Typical frequencies of a world's loop.

View Source 
const HelixStandAnimationFPS = 60
View Source 
const (
	MechaneOrange = Theme("mechane-orange")
)

Variables

View Source 
var (

	// DefaultPerspectiveLens for a camera.
	DefaultPerspectiveLens = defaultPerspLens.Matrix

	// DefaultPerspectiveLensInverse inverts the default perspective lens.
	DefaultPerspectiveLensInverse = defaultPerspLens.Inverse

	// DefaultVeneerLens for a camera that displays a veneer over the world view.
	DefaultVeneerLens = defaultVeneerLens.Matrix

	// DefaultVeneerLensInverse inverts the default veneer lens.
	DefaultVeneerLensInverse = defaultVeneerLens.Inverse
)
View Source 
var DefaultBackgroundColour = rgb.Whitesmoke.Colour()

DefaultBackgroundColour for the Cameras' pixels.

View Source 
var HexStr32 = mech.NewRandHexStr(32)

HexStr32 is a generator of fixed length strings which consist of 32 pseudorandom hexadecimal digits with lowercase letters.

Not suitable for security oriented applications requiring true randomness.

Functions

func NewLaunchResources 

func NewLaunchResources[M any](
	spec LaunchResourcesSpec[M],
) func() (LaunchResources, error)

NewLaunchResources makes a function which returns a world's launch resources.

Shall be called only once, as shall the returned function.

func NewStandardRunFunc 

func NewStandardRunFunc[M any](
	initWorld func(wld Standard) M,
	update func(
		wld Standard,
		t watchable.ChronoShift,
		arrhythmic bool,
		mdl M,
	) bool,
	pulse LoopsPerSec,
) func(server mechserver.Server)

NewStandardRunFunc which accepts a Mechane server and uses it to run a Mechane world.

func RunStandard 

func RunStandard(wld Standard)

RunStandard runs the given standard world.

Types

type Asciidoc 

type Asciidoc struct {
	// ElementName is unique on a tree.
	ElementName string

	// MaxHeight of the element in units of 'ch'.
	//
	// If used, Mechane constrains this value to be within a reasonable range.
	MaxHeight int
	// Width of the element in units of 'ch'.
	//
	// If used, Mechane constrains this value to be within a reasonable range.
	Width int

	// AsciiDocHTML is AsciiDoc in HTML format.
	//
	// This should be known safe or purified HTML as it is inserted verbatim
	// into the document.
	AsciiDocHTML string
	// AsciidoctorDefaultStyle enables the official Asciidoctor default style
	// sheet if true.
	AsciidoctorDefaultStyle bool
	// On-screen orientation of the element relative to its in-world
	// orientation.
	Orientation mechtree.OverlayOrientation
	// Position of the node origin on the asciidoc.
	//
	// Decides which part of the asciidoc will overlap the onscreen position of
	// its mechtree node's origin.
	OriginPosition mechtree.OverlayOrigin
	// Theme to use. Leave blank to use the default theme.
	Theme string
	// Title is the hover text that appears over the asciidoc.
	Title string
}

func (Asciidoc) Overlay 

func (ovl Asciidoc) Overlay(node *mechtree.Node) error

Overlay the node with a mechane-asciidoc element.

type Button 

type Button struct {
	// EffectName determines the side effect of clicking the button.
	//
	// The name doesn't need to be unique among buttons, that is, multiple
	// buttons with the same button name should cause the same side effect.
	EffectName string
	// ElementName is unique on a Mechane tree.
	ElementName string

	// Icon shown on the button.
	Icon mech.Icon
	// The colour of the icon shown on the button.
	IconColour string
	// On-screen orientation of the element relative to its in-world
	// orientation.
	Orientation mechtree.OverlayOrientation
	// Position of the node origin on the button.
	//
	// Decides which part of the button will overlap the onscreen position of
	// its mechtree node's origin.
	OriginPosition mechtree.OverlayOrigin
	// Text shown on the button.
	Text string
	// Theme to use. Leave blank to use the default theme.
	Theme string
	// Title is the hover text that appears over the button.
	Title string

	Cloggable
}

func (*Button) Overlay 

func (btn *Button) Overlay(node *mechtree.Node) error

Overlay the node with a mechane-button element.

type Camera 

type Camera struct {
	mechtree.Camera
	Dolly            dolly.DollyMaker
	Veneer           mechtree.Camera // The veneer is the view from this camera.
	BackgroundColour mech.Colour     // The background colour.
	BackgroundAlpha  float64         // The background colour opacity.
}

A Camera to view a Mechane world.

type CameraAdjustments 

type CameraAdjustments struct {
	// contains filtered or unexported fields
}

CameraAdjustments is a queue to which you can add requests for a Mechane world to create, update, and delete cameras.

The Mechane world will process the camera requests when the world loop is not busy.

func NewCameraAdjustments 

func NewCameraAdjustments() CameraAdjustments

NewCameraAdjustments constructs a new CameraAdjustments.

func (CameraAdjustments) Create 

func (adj CameraAdjustments) Create(cam Camera)

Create appends a create camera request.

func (CameraAdjustments) Delete 

func (adj CameraAdjustments) Delete(name string)

Delete appends a delete camera request.

func (CameraAdjustments) Update 

func (adj CameraAdjustments) Update(cam Camera)

Update appends an update camera request.

type Cloggable 

type Cloggable struct {
	// ClogDuration after cloggage until the cloggable can be declogged.
	ClogDuration time.Duration
	// contains filtered or unexported fields
}

A Cloggable can be clogged and then eventually declogged when it becomes decloggable.

func (*Cloggable) Clog 

func (c *Cloggable) Clog(now time.Time)

Clog the cloggable.

The cloggable shall not still be clogged.

func (*Cloggable) Clogged 

func (c *Cloggable) Clogged() bool

Clogged reports whether the cloggable is clogged and not yet declogged.

func (*Cloggable) Declog 

func (c *Cloggable) Declog()

Declog the cloggable.

func (*Cloggable) Decloggable 

func (c *Cloggable) Decloggable(now time.Time) bool

Decloggable reports whether the cloggable is able to be declogged as yet.

Reports false if the cloggable is not currently clogged.

type HelixStand 

type HelixStand[T any] struct {
	Node *mechtree.Node
	// contains filtered or unexported fields
}

HelixStand organises items by placing them along the path of a helix curve.

The helix curves around the positive Z-axis. The first stand position, which can be adjusted with the phase, is always in the Z=0 XY-plane.

func NewHelixStand 

func NewHelixStand[T any](spec HelixStandSpec) *HelixStand[T]

NewHelixStand constructs a new HelixStand.

func (*HelixStand[T]) Add 

func (stand *HelixStand[T]) Add(item T) *mechtree.Node

Add an item to the stand by occupying the first stand position in the Z=0 plane and move the other items along the helix by one position.

func (*HelixStand[T]) Delete 

func (stand *HelixStand[T]) Delete(node *mechtree.Node)

Delete the given node and therefore its stand position from the helix stand.

The stand position of the given node can be any stand position on the helix stand.

Stand positions that come after the deleted position are moved down by one place to fill the gap.

func (*HelixStand[T]) ElementName 

func (stand *HelixStand[T]) ElementName() string

ElementName assigned to the HelixStand at creation.

func (*HelixStand[T]) Len 

func (stand *HelixStand[T]) Len() int

Len is the number of items on the helix stand.

func (*HelixStand[T]) ShiftByOne 

func (stand *HelixStand[T]) ShiftByOne(downward bool)

ShiftByOne position the items on the helix stand.

A true value moves the items towards the base and fills the rear gap from the base position. A false value operates in reverse, pushing the items away from the base and filling the base gap from the rear position.

If the helix stand is empty or contains only a single item this is a no-op.

type HelixStandSpec 

type HelixStandSpec struct {
	// A unique name.
	ElementName string

	// Angle in radians between consecutive spokes as seen in the XY-plane.
	A float64
	// Pitch of the helix.
	P float64
	// Phase angle is the anticlockwise angle in radians between the positive
	// X-axis and the spoke of the first stand position in the Z=0 XY-plane.
	Phase float64
	// Radius of the helix and the length of the spokes extending
	// perpendicularly from the axis to a stand position.
	R float64
	// Time taken to move the other items on the stand into their new position
	// when another item is added or removed.
	T time.Duration
	// contains filtered or unexported fields
}

HelixStandSpec specifies the characteristics of a HelixStand.

type LaunchResources 

type LaunchResources struct {
	AboutWorld func() (about.World, error)
	// Run accepts a new Mechane server and uses it to run the Mechane world.
	Run func(server mechserver.Server)
	// WorldWeb provides the static resources made available by the Mechane
	// world.
	WorldWeb http.FileSystem
}

LaunchResources for a Mechane world launch.

type LaunchResourcesSpec 

type LaunchResourcesSpec[M any] struct {
	// About this world.
	About about.World
	// Init the model of the world.
	Init func(wld Standard) M
	// PulseRate is the number of game loop iterations per second. The model
	// update function is called once per game loop iteration.
	PulseRate LoopsPerSec
	// Update the model of the world on each pulse.
	Update func(
		wld Standard,
		t watchable.ChronoShift,
		arrhythmic bool,
		mdl M,
	) bool
	// WorldWeb provides static HTTP resources for the world.
	WorldWeb embed.FS
}

LaunchResourcesSpec collects the resources needed when launching a Mechane world.

type LoopSpec 

type LoopSpec struct {
	// The target number of world loops per second.
	PulseRate LoopsPerSec

	// The point in a world loop to start drawing views from cameras.
	RasteriseOclock uint

	// The point in a world loop to process low level UI events from clients.
	UIEventsOclock uint
}

LoopSpec specifies the desired game loop characteristics of a new standard kind of Mechane world.

type LoopsPerSec 

type LoopsPerSec uint

LoopsPerSec is the target number of times a world should complete a world loop in one second.

type Pre 

type Pre struct {
	// ElementName is unique on a tree.
	ElementName string

	// MaxHeight of the element in units of 'ch'.
	//
	// If used, Mechane constrains this value to be within a reasonable range.
	MaxHeight int
	// Width of the element in units of 'ch'.
	//
	// If used, Mechane constrains this value to be within a reasonable range.
	Width int

	// Buttons placed horizontally at the top of the element.
	Buttons []Button
	// For the case of multiple buttons, this is the number of characters
	// between the leftmost point of successive buttons.
	//
	// Clamped to a minimum value of characters which is just above the physical
	// dimensions of a button including spacing.
	ButtonChars int
	// Preformatted text which is set as the content of a pre element.
	PreText string
	// On-screen orientation of the element relative to its in-world
	// orientation.
	Orientation mechtree.OverlayOrientation
	// Position of the node origin on the pre text.
	//
	// Decides which part of the pre text will overlap the onscreen position of
	// its mechtree node's origin.
	OriginPosition mechtree.OverlayOrigin
	// Theme to use. Leave blank to use the default theme.
	Theme string
	// Title is the hover text that appears over the pre text.
	Title string
}

Pre formatted text overlay element.

func (Pre) Overlay 

func (ovl Pre) Overlay(node *mechtree.Node) error

Overlay the node with a mechane-pre element.

type RadioButtonGroup 

type RadioButtonGroup map[string]*ToggleButton

A RadioButtonGroup with no more than one button activated at a time.

func NewRadioButtonGroup 

func NewRadioButtonGroup(spec RadioButtonGroupSpec) RadioButtonGroup

NewRadioButtonGroup constructs a new RadioButtonGroup.

func (RadioButtonGroup) Click 

func (rg RadioButtonGroup) Click(name string, now time.Time)

Click the button in the group with the given name and clog the group.

The radio button group shall not still be clogged.

func (RadioButtonGroup) Clogged 

func (rg RadioButtonGroup) Clogged() bool

Clogged reports whether the group is still clogged after a click.

func (RadioButtonGroup) Declog 

func (rg RadioButtonGroup) Declog()

Declog the button group.

func (RadioButtonGroup) Decloggable 

func (rg RadioButtonGroup) Decloggable(now time.Time) bool

Decloggable reports whether the group is decloggable.

Reports false if the cloggable is not currently clogged.

func (RadioButtonGroup) Overlay 

func (rg RadioButtonGroup) Overlay(nodes map[string]*mechtree.Node)

Overlay each of the nodes in the argument map with a mechane-button element representing the radio group button whose button name is given by the map key.

func (RadioButtonGroup) SelectedName 

func (rg RadioButtonGroup) SelectedName() (string, bool)

SelectedName and a true value or, for the no selection case, an empty string and a false value.

type RadioButtonGroupSpec 

type RadioButtonGroupSpec struct {
	// Buttons accessible by button name.
	Buttons map[string]RadioButtonSpec

	// ClogDuration before any of the buttons can be clicked again.
	ClogDuration time.Duration
}

type RadioButtonSpec 

type RadioButtonSpec struct {
	// ElementName is unique on a tree.
	ElementName string
	// Icon shown on the button when selected. Leave blank to use the default
	// icon.
	Icon mech.Icon
	// Place the button relative to the node origin.
	OriginPosition mechtree.OverlayOrigin
	// Text shown on the button.
	Text string
	// Theme to use. Leave blank to use the default theme.
	Theme string
	// Title is the hover text that appears over the radio button when selected.
	Title string

	// Icon shown on the button when not selected. Leave blank to use the
	// default icon.
	OffIcon mech.Icon
	// Fill colour of the icon shown on the button when not selected. Leave
	// blank to use the default colour.
	OffIconColour string
	// Title is the hover text that appears over the radio button when not
	// selected.
	OffTitle string
}

RadioButtonSpec specifies the properties of a radio button.

type Standard 

type Standard struct {
	LoopLog *log.Logger

	ButtonClicks  mechuievent.ButtonClicks
	TextfieldKeys mechuievent.TextfieldKeys
	WheelMoves    mechuievent.WheelMoves

	CameraAdjustments CameraAdjustments
	ChronoDial        watchable.ChronoDial
	Stitcher          *wiregl.CPUStitcher
	mechserver.Server
	// contains filtered or unexported fields
}

A Standard kind of Mechane world.

func NewStandard 

func NewStandard(loopSpec LoopSpec, server mechserver.Server) Standard

NewStandard constructs a new Standard world.

The world has 12 positions on its chronodial.

func (Standard) WatchOclock 

func (sw Standard) WatchOclock(
	oclock uint,
	f func(watchable.ChronoShift, bool) bool,
)

WatchOclock on the chronodial.

For each chronoshift placed at that position supply it as an argument to the given callback function.

To avoid skipping chronoshifts the callback needs to complete before the next chronoshift. The callback receives a bool value reporting whether the previous callback completed in time; if the bool value is false at least one previous callback event was skipped and the chronoshifts for those events were missed.

To stop any further callbacks the callback should return a false value.

type Textfield 

type Textfield struct {
	// EffectName determines the meaning of the text.
	//
	// The name doesn't need to be unique among textfields, that is, multiple
	// textfields with the same textfield name should cause the same side effect
	// if any among them were to be given a particular text input.
	EffectName string
	// ElementName is unique on a Mechane tree.
	ElementName string

	// Icon1 is placed to the left of the textfield input.
	Icon1 mech.Icon
	// The colour of the icon.
	Icon1Colour string

	// Icon2 is placed to the right of the textfield input.
	Icon2 mech.Icon
	// The colour of the icon.
	Icon2Colour string

	// A button placed at the far right-hand side of the textfield.
	Button Button

	// The value of the textfield input.
	InputValue string
	// The uneditable text after the first icon, if any, and before the
	// textfield input.
	Label string
	// Mask the input if true.
	Mask bool
	// On-screen orientation of the element relative to its in-world
	// orientation.
	Orientation mechtree.OverlayOrientation
	// Position of the node origin on the textfield.
	//
	// Decides which part of the textfield will overlap the onscreen position of
	// its mechtree node's origin.
	OriginPosition mechtree.OverlayOrigin
	// Placeholder text.
	Placeholder string
	// The number of visible characters that the textfield input can show at
	// once.
	//
	// Special cases:
	//   - to use the browser's default leave the size uninitialised (0);
	//   - to actually specify a size of zero, use any negative number.
	Size int
	// Whether to enable the browser's spellcheck squiggle on the input.
	Spellcheck bool
	// Theme to use. Leave blank to use the default theme.
	Theme string
	// Title is the hover text that appears over the textfield.
	Title string

	Cloggable
}

func (*Textfield) Overlay 

func (ovl *Textfield) Overlay(node *mechtree.Node) error

Overlay the node with a mechane-textfield element.

type Theme 

type Theme = string

type ToggleButton 

type ToggleButton struct {
	Button

	Off           bool
	OffIcon       mech.Icon
	OffIconColour string
	OffTitle      string
}

func (*ToggleButton) Overlay 

func (btn *ToggleButton) Overlay(node *mechtree.Node)

Overlay the node with a mechane-button element representing the toggle button.

func (*ToggleButton) Toggle 

func (btn *ToggleButton) Toggle(now time.Time)

Toggle and clog the toggle button.

The toggle button shall not still be clogged.

Source Files

View all Source files

Directories

Path Synopsis
Package dolly maps user input to camera movements.
 Package dolly maps user input to camera movements.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.