gdq

README

🎮 GDQ 🏃

A Go library and CLI for Games Done Quick

Games Done Quick (GDQ) is a regular speedrunning event that collects money for charity. The event is incredibly fun, especially if you enjoy seeing your favourite games torn to shreds by amazing runners and supported with great commentary and prizes to win.

This repo contains a Go library and CLI for working with the GDQ schedule. It uses the Tracker API to retrieve the data.

There is also a companion Matrix bot over at GDQBot.

Installation

CLI

There are prebuilt binaries available for every release from v1.0.0 onwards. You can find them over here.

Platform	Architecture	Binary
Windows	amd64	✅
macOS	amd64	✅
macOS	arm64 (Apple Silicon)	✅
Linux	amd64	✅
Linux	arm64	✅

Library

$ go get github.com/daenney/gdq/v3

Building

You can go get the library, or git clone and then run a go build followed by a go test ./... to ensure everything is OK.

You can build the CLI using go build -trimpath -o gdqcli cmd/gdqcli/*.go or install it directly using go install github.com/daenney/gdq/v3/cmd/gdqcli. See go help install for where the binaries will end up.

Contributing

PRs welcome! Fork+clone the repo and send me a patch. Please ensure that:

• Make small commits that encapsulate one functional change at a time (implementation change, the associated tests and any doc changes)
• Every commit explains what it's trying to achieve and why
• The tests pass

Documentation

Index

• Variables
• type Client
  • func New(client *http.Client) *Client
  • func (c *Client) Event(ctx context.Context, ev uint) (*Event, error)
  • func (c *Client) Events(ctx context.Context) ([]*Event, error)
  • func (c *Client) Runs(ctx context.Context, ev uint) ([]*Run, error)
  • func (c *Client) Schedule(ctx context.Context, ev uint) (*Schedule, error)
• type Donation
• type Duration
  • func (d Duration) Add(nd Duration) Duration
  • func (d Duration) MarshalJSON() (b []byte, err error)
  • func (d Duration) String() string
  • func (d *Duration) UnmarshalJSON(b []byte) error
• type Event
  • func GetEventByID(id uint) (ev *Event, found bool)
  • func GetEventByName(input string) (ev *Event, found bool)
  • func (e Event) String() string
• type Run
• type Schedule
  • func NewSchedule() *Schedule
  • func NewScheduleFrom(runs []*Run) *Schedule
  • func (s *Schedule) ForHost(name string) *Schedule
  • func (s *Schedule) ForRunner(name string) *Schedule
  • func (s *Schedule) ForTitle(title string) *Schedule
  • func (s *Schedule) NextRun(t time.Time) *Run
• type Talent

Variables

var (
	SGDQ2012         = Event{ID: 1, Short: "SGDQ2012", Name: "Summer Games Done Quick", Year: 2012}
	AGDQ2012         = Event{ID: 2, Short: "AGDQ2012", Name: "Awesome Games Done Quick", Year: 2012}
	SGDQ2011         = Event{ID: 3, Short: "SGDQ2011", Name: "Summer Games Done Quick", Year: 2011}
	JRDQ             = Event{ID: 4, Short: "JRDQ", Name: "Japan Relief Done Quick", Year: 2011}
	AGDQ2011         = Event{ID: 5, Short: "AGDQ2011", Name: "Awesome Games Done Quick", Year: 2011}
	CGDQ             = Event{ID: 6, Short: "CGDQ", Name: "Classic Games Done Quick", Year: 2010}
	AGDQ2013         = Event{ID: 7, Short: "AGDQ2013", Name: "Awesome Games Done Quick", Year: 2013}
	SGDQ2013         = Event{ID: 8, Short: "SGDQ2013", Name: "Summer Games Done Quick", Year: 2013}
	AGDQ2014         = Event{ID: 9, Short: "AGDQ2014", Name: "Awesome Games Done Quick", Year: 2014}
	SGDQ2014         = Event{ID: 10, Short: "SGDQ2014", Name: "Summer Games Done Quick", Year: 2014}
	AGDQ2015         = Event{ID: 12, Short: "AGDQ2015", Name: "Awesome Games Done Quick", Year: 2015}
	Spook            = Event{ID: 13, Short: "Spook", Name: "Speedrun Spooktacular", Year: 2012}
	SGDQ2015         = Event{ID: 16, Short: "SGDQ2015", Name: "Summer Games Done Quick", Year: 2015}
	AGDQ2016         = Event{ID: 17, Short: "AGDQ2016", Name: "Awesome Games Done Quick", Year: 2016}
	SGDQ2016         = Event{ID: 18, Short: "SGDQ2016", Name: "Summer Games Done Quick", Year: 2016}
	AGDQ2017         = Event{ID: 19, Short: "AGDQ2017", Name: "Awesome Games Done Quick", Year: 2017}
	SGDQ2017         = Event{ID: 20, Short: "SGDQ2017", Name: "Summer Games Done Quick", Year: 2017}
	HRDQ             = Event{ID: 21, Short: "HRDQ", Name: "Harvey Relief Done Quick", Year: 2017}
	AGDQ2018         = Event{ID: 22, Short: "AGDQ2018", Name: "Awesome Games Done Quick", Year: 2018}
	SGDQ2018         = Event{ID: 23, Short: "SGDQ2018", Name: "Summer Games Done Quick", Year: 2018}
	GDQX2018         = Event{ID: 24, Short: "GDQX2018", Name: "Games Done Quick Express", Year: 2018}
	AGDQ2019         = Event{ID: 25, Short: "AGDQ2019", Name: "Awesome Games Done Quick", Year: 2019}
	SGDQ2019         = Event{ID: 26, Short: "SGDQ2019", Name: "Summer Games Done Quick", Year: 2019}
	GDQX2019         = Event{ID: 27, Short: "GDQX2019", Name: "Games Done Quick Express", Year: 2019}
	AGDQ2020         = Event{ID: 28, Short: "AGDQ2020", Name: "Awesome Games Done Quick", Year: 2020}
	FrostFatales2020 = Event{ID: 29, Short: "FrostFatales2020", Name: "Frost Fatales", Year: 2020}
	SGDQ2020         = Event{ID: 30, Short: "SGDQ2020", Name: "Summer Games Done Quick", Year: 2020}
	CRDQ             = Event{ID: 31, Short: "CRDQ", Name: "Corona Relief Done Quick", Year: 2020}
	THPSLaunch       = Event{ID: 32, Short: "THPSLaunch", Name: "Tony Hawk's Pro Skater 1 + 2 Launch Celebration", Year: 2020}
	FleetFatales2020 = Event{ID: 33, Short: "FleetFatales2020", Name: "Fleet Fatales", Year: 2020}
	AGDQ2021         = Event{ID: 34, Short: "AGDQ2021", Name: "Awesome Games Done Quick 2021 Online", Year: 2021}
	SGDQ2021         = Event{ID: 35, Short: "SGDQ2021", Name: "Summer Games Done Quick 2021 Online", Year: 2021}
	FlameFatales2021 = Event{ID: 36, Short: "FlameFatales2021", Name: "Flame Fatales", Year: 2021}
	AGDQ2022         = Event{ID: 37, Short: "AGDQ2022", Name: "Awesome Games Done Quick 2022 Online", Year: 2022}
	FrostFatales2022 = Event{ID: 38, Short: "FrostFatales2022", Name: "Frost Fatales", Year: 2022}
	SGDQ2022         = Event{ID: 39, Short: "SGDQ2022", Name: "Summer Games Done Quick", Year: 2022}
	FlameFatales2022 = Event{ID: 40, Short: "FlameFatales2022", Name: "Flame Fatales", Year: 2022}
	AGDQ2023         = Event{ID: 41, Short: "AGDQ2023", Name: "Awesome Games Done Quick", Year: 2023}
	FrostFatales2023 = Event{ID: 42, Short: "FrostFatales2023", Name: "Frost Fatales", Year: 2023}
	SGDQ2023         = Event{ID: 43, Short: "SGDQ2023", Name: "Summer Games Done Quick", Year: 2023}
	FlameFatales2023 = Event{ID: 44, Short: "FlameFatales2023", Name: "Flame Fatales", Year: 2023}
	GDQX2023         = Event{ID: 45, Short: "GDQX2023", Name: "Games Done Quick Express", Year: 2023}
	AGDQ2024         = Event{ID: 46, Short: "AGDQ2024", Name: "Awesome Games Done Quick", Year: 2024}
	FrostFatales2024 = Event{ID: 47, Short: "FrostFatales2024", Name: "Frost Fatales", Year: 2024}
	SGDQ2024         = Event{ID: 48, Short: "SGDQ2024", Name: "Summer Games Done Quick", Year: 2024}
	FlameFatales2024 = Event{ID: 49, Short: "FlameFatales2024", Name: "Flame Fatales", Year: 2024}
	SSAtPAXWest      = Event{ID: 50, Short: "SSAtPAXWest", Name: "Speedrun Stage @ PAX West", Year: 2024}
	GDQX2024         = Event{ID: 51, Short: "GDQX2024", Name: "Games Done Quick Express", Year: 2024}
	AGDQ2025         = Event{ID: 52, Short: "AGDQ2025", Name: "Awesome Games Done Quick", Year: 2025}
	DRDQ2024         = Event{ID: 53, Short: "DRDQ2024", Name: "Disaster Relief Done Quick", Year: 2024}
	BTB2025          = Event{ID: 54, Short: "BTB2025", Name: "Back to Black", Year: 2025}
)

All the GDQ events, sorted by Event.ID

Types

type Client

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

Client is a GDQ API client.

func New

func New(client *http.Client) *Client

New creates a new GDQ API client.

func (*Client) Event

func (c *Client) Event(ctx context.Context, ev uint) (*Event, error)

Event retrieves event information for the event ID.

Contrary to Client.Events, this includes donation information.

func (*Client) Events

func (c *Client) Events(ctx context.Context) ([]*Event, error)

Events returns all events, sorted by start date.

func (*Client) Runs

func (c *Client) Runs(ctx context.Context, ev uint) ([]*Run, error)

Runs returns all runs for an Event.

func (*Client) Schedule

func (c *Client) Schedule(ctx context.Context, ev uint) (*Schedule, error)

Schedule returns the Schedule for a GDQ event.

This schedule only contains runs, not interviews.

type Donation

type Donation struct {
	Count  uint64  `json:"count"`
	Amount float64 `json:"amount"`
}

type Duration

type Duration struct {
	time.Duration
}

Duration represents a interval of time

func (Duration) Add

func (d Duration) Add(nd Duration) Duration

func (Duration) MarshalJSON

func (d Duration) MarshalJSON() (b []byte, err error)

MarshalJSON marshals a Duration to JSON

func (Duration) String

func (d Duration) String() string

func (*Duration) UnmarshalJSON

func (d *Duration) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals a duration like thing from JSON

type Event

type Event struct {
	ID    uint   `json:"id"`
	Short string `json:"short"`
	Name  string `json:"name"`
	Year  int    `json:"year"`

	Donations Donation `json:"donations"`
}

Event is the schedule ID of a GDQ event

func GetEventByID

func GetEventByID(id uint) (ev *Event, found bool)

GetEventByID fetches the event by ID

func GetEventByName

func GetEventByName(input string) (ev *Event, found bool)

GetEventByName tries to find an event matching the input

func (Event) String

func (e Event) String() string

type Run

type Run struct {
	Title        string    `json:"title"`
	Start        time.Time `json:"start"`
	Estimate     Duration  `json:"estimate"`
	Runners      []Talent  `json:"runners"`
	Hosts        []Talent  `json:"hosts"`
	Commentators []Talent  `json:"commentators"`
	Category     string    `json:"category"`
	Platform     string    `json:"platform"`
}

Run represents a single event at a GDQ

type Schedule

type Schedule struct {
	Runs []*Run
	// contains filtered or unexported fields
}

Schedule represents the runs occurring at a GDQ event.

func NewSchedule

func NewSchedule() *Schedule

NewSchedule returns an empty Schedule.

func NewScheduleFrom

func NewScheduleFrom(runs []*Run) *Schedule

NewScheduleFrom returns a scheduled filled with the runs.

func (*Schedule) ForHost

func (s *Schedule) ForHost(name string) *Schedule

ForHost returns a new schedule with runs only matching this host.

The host's name is matched using a substring match. This means that if you call somtething like schedule.ForHost("b") you can get a schedule with runs for multiple hosts.

You'll get a nil schedule if no run matched the host.

The match is case insensitive.

func (*Schedule) ForRunner

func (s *Schedule) ForRunner(name string) *Schedule

ForRunner returns a new schedule with runs only matching this runner.

The runner's name is matched using a substring match. This means that if you call somtething like schedule.ForRunner("b") you can get a schedule with runs for multiple runners.

You'll get a nil schedule if no run matched the runner.

The match is case insensitive.

func (*Schedule) ForTitle

func (s *Schedule) ForTitle(title string) *Schedule

ForTitle returns a new schedule with runs only matching the title.

The title is matched using a substring match. This means that if you call somtething like schedule.ForTitle("b") you can get a schedule with multiple runs.

You'll get a nil schedule if no run matched the title.

The match is case insensitive.

func (*Schedule) NextRun

func (s *Schedule) NextRun(t time.Time) *Run

NextRun returns the next run in the Schedule.

It returns the first run after t.

type Talent

type Talent struct {
	Name string `json:"name"`
}