nook

README

Nook

Nook exports basic information for characters that appear in the video game series Animal Crossing.

Introduction

This package centers on the organisation and classification of residents versus villagers, as well as defining the common attributes between them. Residents in the context of this package are Animal Crossing characters that cannot be invited as home owners within the players town, city, or island. Residents perform a special role within the world and often are quest givers. An example of a Resident would be Isabelle, Tom Nook or Guliver. Villagers are Animal Crossing characters that can be invited to stay in the players town, city or island, and make up the larger world population. Characters such as Alfonso, Tabby and Egbert are all examples of Villagers. Villagers can be given gifts, have personalities and homes.

Design

This package separates and organises Animal Crossing characters by their animal type. This is a requirement due to the large number of characters there are in the series, and that some characters overlap with other components in name. An example of this is the name Petunia, who is both a Cow and a Rhinoceros. Another example is Snooty, which is the name of one of the wolves and a personality type.

Organisation

Nook at the package level only exports the concrete types consumed by this package. The philosophy was to keep each package extensible, without the concern of searching through various subpackages to find all types that make up the package. Through this, ideally, the pattern will keep the imports relatively straightforward and simple. It should also allow each child package to focus on using only the known set of building blocks to create its exports, and limit the exposure to coding towards circular dependencies. Most of the decisions were shaped by the content of the Animal Crossing series, versus developer preference. For example, the initial concept was to have all characters live at the root package, but name conflicts, data types, and maintenance became an issue. Having each character exist in its own directory was also attempted, but imports became confusing. All recommendations welcome, but for now this appears to be the best trade off.

Disclaimer

The information for this package has largely been sourced from various Wiki pages across the internet. All contributions and corrections are welcome and encouraged. If there are any corrections, please feel free to raise them in a pull request.

Installation

Add Nook as a dependency to your Go project using the following command:

go get -u github.com/lindsaygelle/nook

Docker

You can utilize Nook within a Docker container with the provided Dockerfile. Here's how to build and run the container:

Building the Docker container.

docker build . -t nook

Developing and running Go from within the Docker container.

docker run -it --rm --name nook nook

Docker-compose

A docker-compose.yml file has also been added for convenience.

Usage

The nook package can be used as the starting point for your own Animal Crossing program. By default all current Animal Crossing characters are provided. These can be imported by referencing the type of animal and the characters name.

Accessing individual villagers:

package main

import (
	"encoding/json"
	"fmt"

	"github.com/lindsaygelle/nook"
	"github.com/lindsaygelle/nook/character/cat"
)

// main is the entry point of the program.
// It demonstrates how to use the Nook package to access information about Animal Crossing characters.
func main() {
	// Loop through an array of Animal Crossing cat villagers (Ankha and Tabby).
	for _, cat := range []nook.Villager{cat.Ankha, cat.Tabby} {
		// Marshal the current cat villager into a JSON string.
		b, err := json.Marshal(cat)
		if err != nil {
			// If there is an error during JSON marshaling, panic with the error.
			panic(err)
		}
		// Print the JSON representation of the current cat villager.
		fmt.Println(string(b))
	}
}

Characters are also exported in bulk. These can be accessed by using the animal type and the villagers or residents variable:

package main

import (
	"fmt"

	"github.com/lindsaygelle/nook/character/dog"
	"golang.org/x/text/language"
)

// main is the entry point of the program.
// It demonstrates how to use the Nook package to access and display information about Animal Crossing dog villagers and residents.
func main() {
	// Loop through all dog villagers and print their names as villagers in Animal Crossing.
	for _, villager := range dog.Villagers {
		fmt.Println(fmt.Sprintf("%s is a villager in Animal Crossing", villager.Name.Must(language.AmericanEnglish).Value))
	}
	// Loop through all dog residents and print their names as residents in Animal Crossing.
	for _, resident := range dog.Residents {
		fmt.Println(fmt.Sprintf("%s is a resident in Animal Crossing", resident.Name.Must(language.AmericanEnglish).Value))
	}
}

Creating a simple API:

package main

import (
	"encoding/json"
	"net/http"

	"github.com/lindsaygelle/nook"
	"github.com/lindsaygelle/nook/character/cat"
	"github.com/lindsaygelle/nook/character/dog"
	"github.com/lindsaygelle/nook/character/wolf"
)

// rootHandler is an HTTP request handler for the root endpoint ("/").
// It returns a 200 OK response with an empty body.
func rootHandler(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusOK)
	w.Write(nil)
}

// createVillagersHandler creates an HTTP request handler for specific animal type villagers.
// It receives a slice of nook.Villagers for the specified animal type and returns an HTTP response with JSON data of the villagers.
func createVillagersHandler(villagers nook.Villagers) http.HandlerFunc {
	// Marshal the provided villagers into a JSON byte slice.
	b, err := json.Marshal(villagers)
	if err != nil {
		// If there is an error during JSON marshaling, panic with the error.
		panic(err)
	}
	// Return the HTTP request handler function.
	return func(w http.ResponseWriter, r *http.Request) {
		// Set the "Content-Type" header to indicate that the response contains JSON data.
		w.Header().Set("Content-Type", "application/json;charset=utf-8")
		// Write a 200 OK response with the JSON data in the response body.
		w.WriteHeader(http.StatusOK)
		w.Write(b)
	}
}

func main() {
	// Register HTTP request handlers for different endpoints.
	http.HandleFunc("/", rootHandler)              // Root endpoint
	http.HandleFunc("/cats", createVillagersHandler(cat.Villagers))   // Endpoint for cat villagers
	http.HandleFunc("/dogs", createVillagersHandler(dog.Villagers))   // Endpoint for dog villagers
	http.HandleFunc("/wolves", createVillagersHandler(wolf.Villagers)) // Endpoint for wolf villagers

	// Start the HTTP server on port 8080 and listen for incoming requests.
	http.ListenAndServe(":8080", nil)
}

Extending

Nook was designed with extensibility in mind. You can easily add new functionality by importing the relevant concrete types and applying the required changes. For example, you can create your custom attributes for villagers:

Below is an example of adding functionality to the nook.Villager type.

package main

import (
	"fmt"

	"github.com/lindsaygelle/nook"
	"github.com/lindsaygelle/nook/character/alligator"
	"golang.org/x/text/language"
)

// alligators is a slice containing some Animal Crossing alligator villagers.
var (
	alligators = []nook.Villager{
		alligator.Alfonso,
		alligator.Alli,
	}
)

// Villager represents an Animal Crossing villager with additional functionality.
type Villager struct {
	nook.Villager
}

// Greet returns a friendly greeting from the villager in the American English language.
func (v Villager) Greet() string {
	name := v.Name.Must(language.AmericanEnglish).Value
	phrase := v.Phrase.Must(language.AmericanEnglish).Value
	return fmt.Sprintf("%s! My name is %s. Nice to meet you.", phrase, name)
}

// makeVillager creates a new Villager from the provided nook.Villager.
func makeVillager(villager nook.Villager) Villager {
	return Villager{villager}
}

// makeVillagers creates a slice of Villagers from the provided nook.Villagers.
func makeVillagers(villagers ...nook.Villager) []Villager {
	v := make([]Villager, len(villagers))
	for i, villager := range villagers {
		v[i] = makeVillager(villager)
	}
	return v
}

func main() {
	// Create a slice of Villagers from the alligators slice.
	villagers := makeVillagers(alligators...)

	// Greet each villager and print their friendly messages.
	for _, villager := range villagers {
		fmt.Println(villager.Greet())
	}
}

Another example is adding an outfit to one of your favourite Animal Crossing villagers.

package main

import (
	"bytes"
	"encoding/json"
	"fmt"

	"github.com/lindsaygelle/nook"
	"github.com/lindsaygelle/nook/character/duck"
	"golang.org/x/text/language"
)

// Outfit represents an outfit of an Animal Crossing villager.
type Outfit struct {
	Name nook.Languages
}

// Villager represents an Animal Crossing villager with an additional Outfit field.
type Villager struct {
	nook.Villager
	Outfit Outfit
}

// outfitFrogTeeAmericanEnglish is the American English name for an outfit called "Frog Tee".
var outfitFrogTeeAmericanEnglish = nook.Name{
	Language: language.AmericanEnglish, Value: "Frog Tee"}

// outfitFrogTeeName contains the name of the outfit "Frog Tee" in the American English language.
var outfitFrogTeeName = nook.Languages{
	language.AmericanEnglish: outfitFrogTeeAmericanEnglish}

// outfitFrogTee is an Outfit with the name "Frog Tee".
var outfitFrogTee = Outfit{
	Name: outfitFrogTeeName}

// Scoot is a Villager named "Scoot" with the outfit "Frog Tee".
var Scoot = newVillager(duck.Scoot, outfitFrogTee)

// newVillager creates a new Villager with the provided nook.Villager and Outfit.
func newVillager(villager nook.Villager, outfit Outfit) Villager {
	return Villager{
		Villager: villager,
		Outfit:   outfit,
	}
}

func main() {
	// Create a buffer to store the JSON-encoded data.
	buffer := new(bytes.Buffer)

	// Create an encoder with the buffer to encode the Villager as JSON.
	encoder := json.NewEncoder(buffer)
	encoder.SetIndent("", "\t")

	// Encode the Scoot Villager as JSON and store it in the buffer.
	err := encoder.Encode(Scoot)
	if err != nil {
		panic(err)
	}

	// Print the JSON data stored in the buffer.
	fmt.Println(buffer.String())
}

Contributing

Contributions to Nook are welcome! If you have any ideas, bug reports, or enhancements, please submit them as GitHub issues or create a pull request with your changes. For major contributions, it is recommended to discuss your ideas first by creating an issue to ensure alignment with the project's goals and direction. Please see the CONTRIBUTION file fore more details.

License

Nook is licensed under the MIT License. Feel free to use, modify, and distribute the code within this repository as per the terms of the license. Please see the LICENSE file for more details.

Documentation

Overview

Package nook provides a comprehensive collection of character information from the video game series, Animal Crossing.

This package focuses on organizing and classifying characters into two main categories: residents and villagers. Residents are essential characters in the game world, playing unique roles and often serving as quest givers. They cannot be invited as homeowners to the player's town, city, or island. Examples of residents include Isabelle, Tom Nook, and Guliver. Villagers, on the other hand, form the larger world population and can be invited to stay in the player's town, city, or island. They possess distinct personalities, homes, and can receive gifts. Alfonso, Tabby, and Eggbert are among the charming villagers you may encounter.

To manage the vast number of characters in the series and potential naming overlaps, this package thoughtfully categorizes characters based on their animal type. For example, the name Petunia is shared by both a Cow and a Rhinoceros character, while Snooty is the name of both a wolf character and a personality type.

Index

• type Animal
• type Birthday
  • func (b Birthday) Ok() bool
• type Character
• type Code
  • func (c Code) Ok() bool
• type Gender
• type Key
• type Languages
  • func (v Languages) Add(name Name)
  • func (v Languages) Del(key language.Tag) bool
  • func (v Languages) Each(fn func(language.Tag, Name))
  • func (v Languages) EachWithBreak(fn func(language.Tag, Name) bool)
  • func (v Languages) Get(key language.Tag) (Name, bool)
  • func (v Languages) Has(key language.Tag) bool
  • func (v Languages) Must(key language.Tag) Name
• type Name
  • func (n Name) Ok() bool
• type Personality
• type Resident
• type Residents
  • func (v Residents) Add(resident Resident)
  • func (v Residents) Del(key Key) bool
  • func (v Residents) Each(fn func(Key, Resident))
  • func (v Residents) EachWithBreak(fn func(Key, Resident) bool)
  • func (v Residents) Get(key Key) (Resident, bool)
  • func (v Residents) Has(key Key) bool
  • func (v Residents) Must(key Key) Resident
• type Villager
• type Villagers
  • func (v Villagers) Add(villager Villager)
  • func (v Villagers) Del(key Key) bool
  • func (v Villagers) Each(fn func(Key, Villager))
  • func (v Villagers) EachWithBreak(fn func(Key, Villager) bool)
  • func (v Villagers) Get(key Key) (Villager, bool)
  • func (v Villagers) Has(key Key) bool
  • func (v Villagers) Must(key Key) Villager

Types

type Animal

type Animal struct {
	// Key is a unique identifier for the animal type.
	Key Key

	// Name contains the names of the animal type in different languages.
	Name Languages
}

Animal represents the animal type of an Animal Crossing character.

type Birthday

type Birthday struct {
	// Day is the day of the month when the character's birthday falls.
	Day uint8

	// Month is the month of the year when the character's birthday falls.
	Month time.Month
}

Birthday represents the birthday information of an Animal Crossing character.

func (Birthday) Ok

func (b Birthday) Ok() bool

Ok returns a boolean indicating whether the Birthday information is complete and valid. It checks if both the Day and Month fields have been set.

type Character

type Character struct {
	// Animal represents the animal type of the character.
	Animal

	// Birthday contains the birthday information of the character.
	Birthday Birthday

	// Code is a unique identifier for the character.
	Code Code

	// Key is a unique identifier for the character.
	Key Key

	// Gender represents the gender of the character.
	Gender Gender

	// Name contains the names of the character in different languages.
	Name Languages

	// Special indicates whether the character is special or has a unique role.
	Special bool
}

Character is a composite type that combines various attributes of an Animal Crossing character.

type Code

type Code struct {
	// Value holds the actual unique identifier code.
	Value string
}

Code represents the unique identifier assigned to an Animal Crossing character. These codes are based on data mined from various Animal Crossing games.

func (Code) Ok

func (c Code) Ok() bool

Ok returns a boolean indicating whether the Code information is complete and valid. It checks if the Value field has been set, meaning the code is not an empty string.

type Gender

type Gender struct {
	// Name contains the gender name of the character in different languages.
	Name Languages
}

Gender represents the gender of an Animal Crossing character.

type Key

type Key string

Key is a language agnostic name for a value.

type Languages

type Languages map[language.Tag]Name

Languages is a collection of language information, where each language tag maps to a Name.

func (Languages) Add

func (v Languages) Add(name Name)

Add adds a Name to the collection. The Name.Language is used as the key to store it in Languages.

func (Languages) Del

func (v Languages) Del(key language.Tag) bool

Del removes a Name from Languages using the specified language tag as the key. It returns true if the Name was found and removed, otherwise false.

func (Languages) Each

func (v Languages) Each(fn func(language.Tag, Name))

Each iterates over each language entry in Languages, executing the specified function for each Name.

func (Languages) EachWithBreak

func (v Languages) EachWithBreak(fn func(language.Tag, Name) bool)

EachWithBreak iterates over each language entry in Languages, executing the specified function for each Name. It is possible to break out of the loop by returning true as a callback.

func (Languages) Get

func (v Languages) Get(key language.Tag) (Name, bool)

Get retrieves a Name from Languages using the specified language tag as the key. It returns the Name and a boolean indicating whether the Name was found.

func (Languages) Has

func (v Languages) Has(key language.Tag) bool

Has checks if a Name exists for the specified language tag in Languages. It returns true if the Name is found, otherwise false.

func (Languages) Must

func (v Languages) Must(key language.Tag) Name

Must retrieves a Name from Languages using the specified language tag as the key. Unlike Languages.Get, Languages.Must panics if a Name cannot be retrieved for the given key.

type Name

type Name struct {
	// Language specifies the language tag of the name.
	Language language.Tag

	// Value holds the actual name value in the specified language.
	Value string
}

Name represents the name of a value in a specific language.

func (Name) Ok

func (n Name) Ok() bool

Ok returns a boolean indicating whether the Name information is complete and valid. It checks if the Value field has been set, meaning the name is not an empty string.

type Personality

type Personality struct {
	// Name contains the name of the personality type in different languages.
	Name Languages
}

Personality represents an Animal Crossing character's personality type.

type Resident

type Resident struct {
	Character
}

Resident represents an Animal Crossing character that performs special roles within the player's town, city, or island. Characters that are Residents cannot be invited to live within the player's world, but inhabit the world indirectly. Residents often serve as merchants, administrators, or quest givers.

type Residents

type Residents map[Key]Resident

Residents is a collection of Resident characters, where each Resident is identified by a unique Key.

func (Residents) Add

func (v Residents) Add(resident Resident)

Add adds a Resident to the collection.

func (Residents) Del

func (v Residents) Del(key Key) bool

Del removes a Resident from Residents using the specified Key. It returns true if the Resident was found and removed, otherwise false.

func (Residents) Each

func (v Residents) Each(fn func(Key, Resident))

Each iterates over each Resident in the collection, executing the specified function for each one.

func (Residents) EachWithBreak

func (v Residents) EachWithBreak(fn func(Key, Resident) bool)

EachWithBreak iterates over each Resident in the collection, executing the specified function for each one. It is possible to break out of the loop by returning true as a callback.

func (Residents) Get

func (v Residents) Get(key Key) (Resident, bool)

Get retrieves a Resident from Residents using the specified Key. It returns the Resident and a boolean indicating whether the Resident was found.

func (Residents) Has

func (v Residents) Has(key Key) bool

Has checks if a Resident exists for the specified Key in the collection. It returns true if the Resident is found, otherwise false.

func (Residents) Must

func (v Residents) Must(key Key) Resident

Must retrieves a Resident from Residents using the specified Key. Unlike Residents.Get, Residents.Must panics if a Resident cannot be retrieved for the given Key.

type Villager

type Villager struct {
	Character

	// Personality represents the personality type of the Villager.
	Personality Personality

	// Phrase contains the unique phrases associated with the Villager in different languages.
	Phrase Languages
}

Villager represents an Animal Crossing character that can be invited to live within the player's town, city, or island. Villagers are home owners and can befriend the player, allowing gift and decoration exchanges. Each Villager has a unique personality and set of phrases that accompany them.

type Villagers

type Villagers map[Key]Villager

Villagers is a collection of Villager characters, where each Villager is identified by a unique Key.

func (Villagers) Add

func (v Villagers) Add(villager Villager)

Add adds a Villager to the collection.

func (Villagers) Del

func (v Villagers) Del(key Key) bool

Del removes a Villager from Villagers using the specified Key. It returns true if the Villager was found and removed, otherwise false.

func (Villagers) Each

func (v Villagers) Each(fn func(Key, Villager))

Each iterates over each Villager in the collection, executing the specified function for each one.

func (Villagers) EachWithBreak

func (v Villagers) EachWithBreak(fn func(Key, Villager) bool)

EachWithBreak iterates over each Villager in the collection, executing the specified function for each one. It is possible to break out of the loop by returning true as a callback.

func (Villagers) Get

func (v Villagers) Get(key Key) (Villager, bool)

Get retrieves a Villager from Villagers using the specified Key. It returns the Villager and a boolean indicating whether the Villager was found.

func (Villagers) Has

func (v Villagers) Has(key Key) bool

Has checks if a Villager exists for the specified Key in the collection. It returns true if the Villager is found, otherwise false.

func (Villagers) Must

func (v Villagers) Must(key Key) Villager

Must retrieves a Villager from Villagers using the specified Key. Unlike Villagers.Get, Villagers.Must panics if a Villager cannot be retrieved for the given Key.