Documentation
¶
Index ¶
- Constants
- func Slugify(s string) string
- type Block
- type CheckIn
- type CompletionType
- type CreditAdjustments
- type CreditPurchase
- type FacilitatorToken
- type GameContext
- func (gc *GameContext) Color() string
- func (gc *GameContext) CompletionType() CompletionType
- func (gc *GameContext) GetAllLocationIDs() []string
- func (gc *GameContext) GetNextGroup(completedGroups map[string]bool) *GameContext
- func (gc *GameContext) GetNextItemType(completedLocationIDs map[string]bool, completedGroupIDs map[string]bool) interface{}
- func (gc *GameContext) GetNextLocation(completedLocationIDs map[string]bool, teamID string) string
- func (gc *GameContext) GetSubGroupContext(groupID string) *GameContext
- func (gc *GameContext) GetSubGroupContexts() []*GameContext
- func (gc *GameContext) ID() string
- func (gc *GameContext) IsCompleted(completedCount int) bool
- func (gc *GameContext) IsRoot() bool
- func (gc *GameContext) Locations() []*Location
- func (gc *GameContext) MinimumRequired() int
- func (gc *GameContext) Name() string
- func (gc *GameContext) Navigation() NavigationMode
- func (gc *GameContext) Routing() RouteStrategy
- func (gc *GameContext) SubGroups() []GameStructure
- type GameStatus
- type GameStatuses
- type GameStructure
- type GameStructureServiceInterface
- type ImageSize
- type Instance
- type InstanceSettings
- type Location
- type Marker
- type MediaType
- type NavigationMode
- type NavigationModes
- type Notification
- type Provider
- type RouteStrategies
- type RouteStrategy
- type ShareLink
- type StrArray
- type Team
- type TeamBlockState
- type TeamStartLog
- type Upload
- type User
Constants ¶
const ( CreditAdjustmentReasonPrefixMigration = "Migration" //nolint:gosec // String is not sensitive CreditAdjustmentReasonPrefixMonthlyTopup = "Monthly free credit top-up" CreditAdjustmentReasonPrefixPurchase = "Purchase" CreditAdjustmentReasonPrefixAdmin = "Admin" CreditAdjustmentReasonPrefixGift = "Gift" )
Credit adjustment reason prefixes.
const ( CreditPurchaseStatusPending = "pending" CreditPurchaseStatusCompleted = "completed" CreditPurchaseStatusFailed = "failed" CreditPurchaseStatusCancelled = "cancelled" )
Credit purchase status constants.
const ( CompletionAll = game.CompletionAll CompletionMinimum = game.CompletionMinimum )
const ( RouteStrategyRandomised = game.RouteStrategyRandomised RouteStrategyFreeRoam = game.RouteStrategyFreeRoam RouteStrategyOrdered = game.RouteStrategyOrdered RouteStrategySecret = game.RouteStrategySecret )
const ( )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Block ¶
type Block struct {
ID string `bun:"id,pk,notnull"`
OwnerID string `bun:"owner_id,notnull"`
Type string `bun:"type,type:int"`
Context game.BlockContext `bun:"context,type:string"`
Data json.RawMessage `bun:"data,type:jsonb"`
Ordering int `bun:"ordering,type:int"`
Points int `bun:"points,type:int"`
ValidationRequired bool `bun:"validation_required,type:bool"`
}
type CheckIn ¶
type CheckIn struct {
InstanceID string `bun:"instance_id,notnull"`
TeamID string `bun:"team_code,pk,type:string"`
LocationID string `bun:"location_id,pk,type:string"`
TimeIn time.Time `bun:"time_in,type:datetime"`
TimeOut time.Time `bun:"time_out,type:datetime"`
MustCheckOut bool `bun:"must_check_out"`
Points int `bun:"points,"`
BlocksCompleted bool `bun:"blocks_completed,type:int"`
Location Location `bun:"rel:has-one,join:location_id=id"`
// contains filtered or unexported fields
}
type CompletionType ¶
type CompletionType = game.CompletionType
Type alias — CompletionType is defined in game/ and re-exported here.
type CreditAdjustments ¶
type CreditAdjustments struct {
CreatedAt time.Time `bun:"created_at,nullzero,notnull,default:current_timestamp"`
ID string `bun:"id,unique,pk,type:varchar(36)"`
UserID string `bun:"user_id,notnull,type:varchar(36)"`
Credits int `bun:"credits,type:int,notnull"`
Reason string `bun:"reason,type:varchar(255),notnull"`
CreditPurchaseID sql.NullString `bun:"credit_purchase_id,type:varchar(36),nullzero"`
CreditPurchase *CreditPurchase `bun:"rel:belongs-to,join:credit_purchase_id=id"`
}
type CreditPurchase ¶
type CreditPurchase struct {
CreatedAt time.Time `bun:"created_at,nullzero,notnull,default:current_timestamp"`
UpdatedAt time.Time `bun:"updated_at,nullzero,notnull,default:current_timestamp"`
ID string `bun:"id,unique,pk,type:varchar(36)"`
UserID string `bun:"user_id,notnull,type:varchar(36)"`
Credits int `bun:"credits,type:int,notnull"`
AmountPaid int `bun:"amount_paid,type:int,notnull"` // Amount in cents
StripePaymentID sql.NullString `bun:"stripe_payment_id,type:varchar(255),nullzero"`
StripeSessionID string `bun:"stripe_session_id,type:varchar(255),notnull,unique"`
StripeCustomerID sql.NullString `bun:"stripe_customer_id,type:varchar(255),nullzero"`
ReceiptURL sql.NullString `bun:"receipt_url,type:varchar(500),nullzero"`
Status string `bun:"status,type:varchar(20),notnull,default:'pending'"`
User User `bun:"rel:belongs-to,join:user_id=id"`
}
CreditPurchase represents a record of credit purchases via Stripe.
type FacilitatorToken ¶
type GameContext ¶
type GameContext struct {
Structure *GameStructure
// contains filtered or unexported fields
}
GameContext wraps a GameStructure with its service for easy template usage This allows passing a single object that has both data and behavior.
func NewGameContext ¶
func NewGameContext(structure *GameStructure, service GameStructureServiceInterface) *GameContext
NewGameContext creates a new GameContext with structure and service.
func (*GameContext) Color ¶
func (gc *GameContext) Color() string
Color returns the structure's color.
func (*GameContext) CompletionType ¶
func (gc *GameContext) CompletionType() CompletionType
CompletionType returns the structure's completion type.
func (*GameContext) GetAllLocationIDs ¶
func (gc *GameContext) GetAllLocationIDs() []string
GetAllLocationIDs returns all location IDs recursively for this context's structure.
func (*GameContext) GetNextGroup ¶
func (gc *GameContext) GetNextGroup(completedGroups map[string]bool) *GameContext
GetNextGroup returns the next group for this context's structure.
func (*GameContext) GetNextItemType ¶
func (gc *GameContext) GetNextItemType( completedLocationIDs map[string]bool, completedGroupIDs map[string]bool, ) interface{}
GetNextItemType returns what type of item should be next.
func (*GameContext) GetNextLocation ¶
func (gc *GameContext) GetNextLocation(completedLocationIDs map[string]bool, teamID string) string
GetNextLocation returns the next location for this context's structure.
func (*GameContext) GetSubGroupContext ¶
func (gc *GameContext) GetSubGroupContext(groupID string) *GameContext
GetSubGroupContext returns a GameContext for a specific subgroup by ID.
func (*GameContext) GetSubGroupContexts ¶
func (gc *GameContext) GetSubGroupContexts() []*GameContext
GetSubGroupContexts returns GameContexts for all direct subgroups.
func (*GameContext) IsCompleted ¶
func (gc *GameContext) IsCompleted(completedCount int) bool
IsCompleted checks if this context's structure is completed.
func (*GameContext) IsRoot ¶
func (gc *GameContext) IsRoot() bool
IsRoot returns whether this is the root group.
func (*GameContext) Locations ¶
func (gc *GameContext) Locations() []*Location
Locations returns the loaded locations.
func (*GameContext) MinimumRequired ¶
func (gc *GameContext) MinimumRequired() int
MinimumRequired returns the minimum required count.
func (*GameContext) Navigation ¶
func (gc *GameContext) Navigation() NavigationMode
Navigation returns the structure's navigation method.
func (*GameContext) Routing ¶
func (gc *GameContext) Routing() RouteStrategy
Routing returns the structure's routing mode.
func (*GameContext) SubGroups ¶
func (gc *GameContext) SubGroups() []GameStructure
SubGroups returns the direct subgroups (use GetSubGroupContexts for contexts).
type GameStatus ¶
type GameStatus int
const ( Scheduled GameStatus = iota Active Closed )
func ParseGameStatus ¶
func ParseGameStatus(s string) (GameStatus, error)
ParseGameStatus returns a GameStatus from a string.
func (GameStatus) Description ¶
func (g GameStatus) Description() string
Description returns the description of the GameStatus.
func (GameStatus) String ¶
func (g GameStatus) String() string
String returns the string representation of the GameStatus.
type GameStatuses ¶
type GameStatuses []GameStatus
func GetGameStatuses ¶
func GetGameStatuses() GameStatuses
GetGameStatuses returns a list of game statuses.
type GameStructure ¶
type GameStructure struct {
ID string `json:"id"`
Name string `json:"name"` // Empty for root group, required for visible groups
Color string `json:"color"` // Empty for root, required for visible groups (e.g., "primary", "secondary")
Routing RouteStrategy `json:"routing"` // ordered, randomised, free_roam, secret
CompletionType CompletionType `json:"completion_type"` // all, minimum
MinimumRequired int `json:"minimum_required,omitempty"` // For minimum completion type
MaxNext int `json:"max_next,omitempty"` // Max locations to show for random routing (0 = unlimited)
AutoAdvance bool `json:"auto_advance"` // If true, auto-move to next group when CompletionType met
IsRoot bool `json:"is_root"` // true ONLY for the invisible root container
// Storage: locations first, then subgroups - order preserved in arrays
LocationIDs []string `json:"location_ids"` // Ordered list of location IDs
SubGroups []GameStructure `json:"sub_groups"` // Ordered list of nested groups
// Runtime fields - populated by GameStructureService
Locations []*Location `json:"-"` // Loaded location pointers
// contains filtered or unexported fields
}
GameStructure represents the hierarchical game state structure
IMPORTANT ARCHITECTURE NOTES:
Order Invariant:
- LocationIDs are ALWAYS stored before SubGroups
- Array order is preserved on save/load
- No explicit ordering fields needed - position in array = order
Root Group Behavior:
- Every instance has exactly ONE root group (IsRoot: true)
- The root group is NEVER rendered in the UI
- The root group acts as an invisible container for:
- Visible subgroups (rendered as group cards)
- Ungrouped locations (rendered directly in the root locations area)
- Root group Name is always empty ("")
- Root group Color is always empty ("")
Visible Groups:
- All visible groups in the UI are SubGroups of the root
- Visible groups have IsRoot: false
- Visible groups always have a Name and Color
- Visible groups are rendered as collapsible group cards
Example Structure:
Root (IsRoot: true, Name: "")
├── LocationIDs: ["loc1", "loc2"] // Rendered in root locations-area
└── SubGroups:
├── Group "Museum Tour" (visible group card)
│ └── LocationIDs: ["loc3", "loc4"]
└── Group "Historical Sites" (visible group card)
└── LocationIDs: ["loc5", "loc6"]
func (*GameStructure) IsPopulated ¶
func (gs *GameStructure) IsPopulated() bool
IsPopulated returns whether this group has been populated with location data.
func (*GameStructure) Scan ¶
func (gs *GameStructure) Scan(value any) error
Scan implements the sql.Scanner interface for database unmarshalling.
func (*GameStructure) SetPopulated ¶
func (gs *GameStructure) SetPopulated(populated bool)
SetPopulated marks this group as populated with location data.
type GameStructureServiceInterface ¶
type GameStructureServiceInterface interface {
// Loading methods
Load(ctx context.Context, instanceID string, group *GameStructure, recursive bool) error
LoadByLocationID(ctx context.Context, instanceID string, locationID string) (*GameStructure, error)
// Validation and persistence
Validate(group *GameStructure, instanceID string) error
Save(ctx context.Context, instanceID string, group *GameStructure) error
// Navigation methods
FindGroupByID(gameStructure *GameStructure, groupID string) *GameStructure
GetAllLocationIDs(group *GameStructure) []string
GetNextItemType(
group *GameStructure,
completedLocationIDs map[string]bool,
completedGroupIDs map[string]bool,
) interface{}
GetNextLocation(group *GameStructure, completedLocationIDs map[string]bool, teamID string) string
GetNextGroup(group *GameStructure, completedGroups map[string]bool) *GameStructure
IsCompleted(group *GameStructure, completedCount int) bool
}
GameStructureServiceInterface defines the methods needed by GameContext.
type ImageSize ¶
type ImageSize struct {
Breakpoint int `json:"breakpoint"` // px width for media queries
URL string `json:"url"` // URL to the image
}
ImageSize represents an image variant with a specific breakpoint.
type Instance ¶
type Instance struct {
CreatedAt time.Time `bun:"created_at,nullzero,notnull,default:current_timestamp"`
UpdatedAt time.Time `bun:"updated_at,nullzero,notnull,default:current_timestamp"`
ID string `bun:"id,pk,type:varchar(36)"`
Name string `bun:"name,type:varchar(255)"`
UserID string `bun:"user_id,type:varchar(36)"`
IsTemplate bool `bun:"is_template,type:bool"`
TemplateID string `bun:"template_id,type:varchar(36),nullzero"`
StartTime bun.NullTime `bun:"start_time,nullzero"`
EndTime bun.NullTime `bun:"end_time,nullzero"`
Status GameStatus `bun:"-"`
IsQuickStartDismissed bool `bun:"is_quick_start_dismissed,type:bool"`
GameStructure GameStructure `bun:"game_structure,type:string"`
Teams []Team `bun:"rel:has-many,join:id=instance_id"`
Locations []Location `bun:"rel:has-many,join:id=instance_id"`
Settings InstanceSettings `bun:"rel:has-one,join:id=instance_id"`
}
Instance represents an entire game state.
func (*Instance) GetStatus ¶
func (i *Instance) GetStatus() GameStatus
GetStatus returns the status of the instance.
type InstanceSettings ¶
type InstanceSettings struct {
InstanceID string `bun:"instance_id,pk,type:varchar(36)"`
MustCheckOut bool `bun:"must_check_out,type:bool"`
ShowTeamCount bool `bun:"show_team_count,type:bool"`
EnablePoints bool `bun:"enable_points,type:bool"`
EnableBonusPoints bool `bun:"enable_bonus_points,type:bool"`
ShowLeaderboard bool `bun:"show_leaderboard,type:bool"`
// contains filtered or unexported fields
}
type Location ¶
type Location struct {
ID string `bun:"id,pk,notnull"`
Name string `bun:"name,type:varchar(255)"`
Slug string `bun:"slug,type:varchar(255)"`
InstanceID string `bun:"instance_id,notnull"`
MarkerID string `bun:"marker_id,notnull"`
Criteria string `bun:"criteria,type:varchar(255)"`
Order int `bun:"order,type:int"`
TotalVisits int `bun:"total_visits,type:int"`
CurrentCount int `bun:"current_count,type:int"`
AvgDuration float64 `bun:"avg_duration,type:float"`
Points int `bun:"points,"`
Instance Instance `bun:"rel:has-one,join:instance_id=id"`
Marker Marker `bun:"rel:has-one,join:marker_id=code"`
Blocks []Block `bun:"rel:has-many,join:id=owner_id"`
// contains filtered or unexported fields
}
func (*Location) HasCluesContext ¶
HasCluesContext returns true if the location has any blocks with clues context.
func (*Location) HasCoordinates ¶
HasCoordinates returns true if the location's marker has coordinates.
func (*Location) HasTaskContext ¶
HasTaskContext returns true if the location has any blocks with task context.
type Marker ¶
type Marker struct {
Code string `bun:"code,unique,pk"`
Lat float64 `bun:"lat,type:float"`
Lng float64 `bun:"lng,type:float"`
Name string `bun:"name,type:varchar(255)"`
TotalVisits int `bun:"total_visits,type:int"`
CurrentCount int `bun:"current_count,type:int"`
AvgDuration float64 `bun:"avg_duration,type:float"`
Locations []Location `bun:"rel:has-many,join:code=marker_id"`
// contains filtered or unexported fields
}
type NavigationMode ¶
type NavigationMode = game.NavigationMode
func ParseNavigationMode ¶
func ParseNavigationMode(s string) (NavigationMode, error)
ParseNavigationMode returns a NavigationMode from a string.
type NavigationModes ¶
type NavigationModes []NavigationMode
func GetNavigationModes ¶
func GetNavigationModes() NavigationModes
GetNavigationModes returns a list of navigation modes.
type Notification ¶
type RouteStrategies ¶
type RouteStrategies []RouteStrategy
func GetRouteStrategies ¶
func GetRouteStrategies() RouteStrategies
GetRouteStrategies returns a list of route strategies.
type RouteStrategy ¶
type RouteStrategy = game.RouteStrategy
Type aliases — models re-exports game/ vocabulary so existing callers don't need to update imports. Methods (String, Description) are automatically available via the alias.
func ParseRouteStrategy ¶
func ParseRouteStrategy(s string) (RouteStrategy, error)
ParseRouteStrategy returns a RouteStrategy from a string.
type ShareLink ¶
type ShareLink struct {
}
ShareLink represents a link that can be shared to access a template.
type StrArray ¶
type StrArray []string
type Team ¶
type Team struct {
ID string `bun:"id,pk"`
Code string `bun:"code,unique"`
Name string `bun:"name,"`
InstanceID string `bun:"instance_id,notnull"`
HasStarted bool `bun:"has_started,default:false"`
MustCheckOut string `bun:"must_scan_out"`
Points int `bun:"points,"`
SkippedGroupIDs []string `bun:"skipped_group_ids,type:text[],array"`
Instance Instance `bun:"rel:has-one,join:instance_id=id"`
CheckIns []CheckIn `bun:"rel:has-many,join:code=team_code"`
BlockingLocation Location `bun:"rel:has-one,join:must_scan_out=marker_id,join:instance_id=instance_id"`
Messages []Notification `bun:"rel:has-many,join:code=team_code"`
Blocks []TeamBlockState `bun:"rel:has-many,join:code=team_code"`
// contains filtered or unexported fields
}
type TeamBlockState ¶
type TeamBlockState struct {
TeamCode string `bun:"team_code,pk,notnull"`
BlockID string `bun:"block_id,pk,notnull"`
IsComplete bool `bun:"is_complete,type:bool"`
PointsAwarded int `bun:"points_awarded,type:int"`
PlayerData json.RawMessage `bun:"player_data,type:jsonb"`
// contains filtered or unexported fields
}
type TeamStartLog ¶
type TeamStartLog struct {
ID string `bun:"id,unique,pk,type:varchar(36)"`
CreatedAt time.Time `bun:"created_at,nullzero,notnull,default:current_timestamp"`
UserID string `bun:"user_id,notnull,type:varchar(36)"`
InstanceID string `bun:"instance_id,notnull,type:varchar(36)"`
TeamID string `bun:"team_id,notnull,type:varchar(36)"`
}
type Upload ¶
type Upload struct {
bun.BaseModel `bun:"table:uploads,alias:u"`
ID string `bun:"id,pk,notnull"`
OriginalURL string `bun:"original_url,notnull"` // Original file link
Timestamp time.Time `bun:"timestamp"`
LocationID string `bun:"location_id,nullzero"`
InstanceID string `bun:"instance_id,nullzero"`
TeamCode string `bun:"team_code,nullzero"`
BlockID string `bun:"block_id,nullzero"`
Storage string `bun:"storage,notnull"`
DeleteData string `bun:"delete_data"`
Type MediaType `bun:"type"`
// contains filtered or unexported fields
}
Upload represents a file that has been uploaded to the system.
type User ¶
type User struct {
ID string `bun:"id,unique,pk,type:varchar(36)"`
Name string `bun:"name,type:varchar(255)"`
DisplayName sql.NullString `bun:"display_name,type:varchar(255),nullzero"`
Email string `bun:"email,unique,pk"`
EmailVerified bool `bun:"email_verified,type:boolean"`
EmailToken string `bun:"email_token,type:varchar(36)"`
EmailTokenExpiry sql.NullTime `bun:"email_token_expiry,nullzero"`
Password string `bun:"password,type:varchar(255)"`
Provider Provider `bun:"provider,type:varchar(255)"`
WorkType sql.NullString `bun:"work_type,type:varchar(100),nullzero"`
FreeCredits int `bun:"free_credits,type:int,default:10"` // Current free credits balance
PaidCredits int `bun:"paid_credits,type:int,default:0"` // Purchased credits
MonthlyCreditLimit int `bun:"monthly_credit_limit,type:int,default:10"` // Monthly free credit allocation
StripeCustomerID sql.NullString `bun:"stripe_customer_id,type:varchar(255),nullzero"`
Instances []Instance `bun:"rel:has-many,join:id=user_id"`
CurrentInstanceID string `bun:"-"`
CurrentInstance Instance `bun:"-"`
CreditPurchases []CreditPurchase `bun:"rel:has-many,join:id=user_id"`
// contains filtered or unexported fields
}