gma

Documentation

Overview

Package gma is the main port of the GMA Core API into the Go language. Parts of the API which don't necessarily belong in their own individual packages (e.g., dice, mapper, etc.) will go here. Currently, the game calendar is implemented here.

Game Calendar

Call NewCalendar(calSystem) to create a new game calendar which is set up for the particular calendaring system applicable for your world. Then you can set the time and date, advance the time as needed, etc. by calling the various methods described below.

Index

• type Calendar
  • func NewCalendar(calSystem string, options ...CalendarOption) (Calendar, error)
  • func (c *Calendar) Advance(delta int64, unitName string) (int64, error)
  • func (c *Calendar) AdvanceToNext(unitName string) error
  • func (c Calendar) Delta(other Calendar) int64
  • func (c Calendar) DeltaString(delta int64, strict bool) string
  • func (c Calendar) Image() ([][][]int, error)
  • func (c *Calendar) IsLeapYear() bool
  • func (c *Calendar) Scan(timeString string) (int64, error)
  • func (c *Calendar) ScanInterval(intSpec string) (int64, error)
  • func (c *Calendar) ScanRelative(timeString string, relativeTo Calendar) (int64, error)
  • func (c *Calendar) SetTime(year, month, date, hour, min, sec, ticks int) error
  • func (c *Calendar) SetTimeNamed(year int, month string, date, hour, min, sec, ticks int) error
  • func (c *Calendar) SetTimeValue(n int64)
  • func (c Calendar) String() string
  • func (c *Calendar) TicksToInterval(unitName string) (int64, error)
  • func (c Calendar) ToString(style int) string
• type CalendarOption
  • func WithTime(timeValue int64) CalendarOption
• type MonthInfo

Types

type Calendar

type Calendar struct {
	// The name of the calendering system in use.
	System string

	// Calendar-specific names and other details about the months,
	// seasons and weekday names.
	Months         []MonthInfo
	Seasons        []string
	Days           []string
	MoonPhaseNames []string

	// The current time, broken out into parts
	Year, Month, Date, Hour, Minute, Second, Tick int
	FHour, FMinute, FSecond                       float64

	// The day of the week (0-origin)
	Dow int

	// The phase of the moon index (0-origin)
	Pom int

	// The season index (0-origin)
	Season int

	// Time units in terms of ticks
	SecondUnits, RoundUnits, MinuteUnits, HourUnits int
	DayUnits, WeekUnits, PomUnits, SeasonUnits      int

	// Unit ranges
	TickMod, SecondMod, MinuteMod, HourMod int
	DowMod, PomMod, SeasonMod              int

	// Unit definitions
	UnitMultiplier map[string]int64

	// Epoch basis
	EpochYear, EpochDow, EpochPom, EpochSeason int

	// Current time
	Now int64
	// contains filtered or unexported fields
}

Calendar describes the calendar system in play and the current date and time.

Since a given game calendar will be in play for the entire GMA system at any given point in time, in terms of type design it's more important that Calendar be the data type rather than the calendar type in play. Thus, we specify the calendar system when constructing a new Calendar with NewCalendar, which sets up all the parameters for managing a calendar of that type.

func NewCalendar

func NewCalendar(calSystem string, options ...CalendarOption) (Calendar, error)

NewCalendar creates a new Calendar object which is set up for the specified calendaring system.

Currently supports the following calendar systems:

"donuttus"   The game world created by the author and his friends.
"golarion"   The game world for Paizo's Pathfinder system.
"gregorian"  The calendar used in most of Earth.

func (*Calendar) Advance

func (c *Calendar) Advance(delta int64, unitName string) (int64, error)

Advance adds delta to the current time tracked by the Calendar receiver. If unitName is empty, the default is to interpret delta in units of ticks.

Returns the interval in ticks that the clock advanced.

func (*Calendar) AdvanceToNext

func (c *Calendar) AdvanceToNext(unitName string) error

AdvanceToNext increments the clock to the next even interval unit. Defaults to ticks if unitName is empty.

func (Calendar) Delta

func (c Calendar) Delta(other Calendar) int64

Delta returns the difference between the receiver and the given Calendar value, in ticks.

func (Calendar) DeltaString

func (c Calendar) DeltaString(delta int64, strict bool) string

DeltaString returns a formatted string showing a time delta. If strict is true, then the output is strictly conforming to what ScanInterval would accept; otherwise, a more general format is used which is more human-friendly.

func (Calendar) Image

func (c Calendar) Image() ([][][]int, error)

Image generates and returns an image of the current calendar year, suitable for printing out in traditional calendar layout. The output is a slice of months, each of which is a slice of weeks, with zeroes or the date in each element of the week sub-slices.

func (*Calendar) IsLeapYear

func (c *Calendar) IsLeapYear() bool

IsLeapYear returns true if the year tracked by the receiver is a leap year.

func (*Calendar) Scan

func (c *Calendar) Scan(timeString string) (int64, error)

Scan reads the provided string of the format

[[[yyyy-]mmm-]dd] hh:mm[:ss[.t]]

where mmm may be numeric or the month's name.

Optional values are defaulted from the current date and time in the receiver.

func (*Calendar) ScanInterval

func (c *Calendar) ScanInterval(intSpec string) (int64, error)

ScanInterval reads the provided relative time in one of the following formats:

nil
<n> [<unit>]
<unit>
[<d>:[<hh>:]]<mm>:<ss>[.<t>]

Returns the number of ticks represented by that interval of time. Square brackets above indicate optional components.

If literal square brackets are input (e.g., "[2d6+1] rounds"), then the text inside the brackets is processed as a random die roll, the result of which will be used for the time interval.

func (*Calendar) ScanRelative

func (c *Calendar) ScanRelative(timeString string, relativeTo Calendar) (int64, error)

ScanRelative is like Scan but rather than pulling defaults from the receiver it uses the provided Calendar value.

func (*Calendar) SetTime

func (c *Calendar) SetTime(year, month, date, hour, min, sec, ticks int) error

SetTime sets the current time and date by discrete values.

func (*Calendar) SetTimeNamed

func (c *Calendar) SetTimeNamed(year int, month string, date, hour, min, sec, ticks int) error

SetTimeNamed is like SetTime but uses month names instead of numeric values.

func (*Calendar) SetTimeValue

func (c *Calendar) SetTimeValue(n int64)

SetTimeValue sets the underlying time value (the Now attribute) of the Calendar receiver.

func (Calendar) String

func (c Calendar) String() string

String renders the Calendar value as a string, in the format

<day> <date> <month> <year> <hh>:<mm>:<ss>.<tick> <season> <phase>

This is equivalent to calling the ToString(1) method.

func (*Calendar) TicksToInterval

func (c *Calendar) TicksToInterval(unitName string) (int64, error)

TicksToInterval returns the number of ticks between the current time in the Calendar receiver and the start of the next specified interval.

func (Calendar) ToString

func (c Calendar) ToString(style int) string

ToString renders the Calendar value as a string, in the specified format. Supported formats include:

0: <date> <month> <year> <hh>:<mm>:<ss>.<tick>
1: <day> <date> <month> <year> <hh>:<mm>:<ss>.<tick> <season> <phase>
2: <date>-<month>-<year> <hh>:<mm>:<ss>.<tick>
3: <year>-<month>-<date> <hh>:<mm>:<ss>.<tick>
4: <hh>:<mm>:<ss>.<tick>

type CalendarOption

type CalendarOption func(*Calendar)

func WithTime

func WithTime(timeValue int64) CalendarOption

WithTime specifies an option to the NewCalendar constructor to set the current time (i.e. the value of the Now attribute) for the newly-created Calendar object.

type MonthInfo

type MonthInfo struct {
	// Month's full and abbreviated names
	FullName, Abbrev string

	// How many days are in the month, in regular and leap years
	Days, LYDays int
}

MonthInfo describes a month in a given calendar system.