gachapy

A gacha engine built in Python for developing gacha games

Directory

controller

The controller used for all high level management of the gacha game

objects

Objects used for low level management and data storage of the gacha game

loader

Library of loader functions for loading gachapy objects from json files

keylang

The tokenizer, parser, and interpreter for KeyLang, the language used by

gachapy to save and load custom rarity to drop rate functions

Author: Jacob Kerr, 2021

Submodules

• gachapy.controller
• gachapy.keylang
• gachapy.loader
• gachapy.objects

Package Contents

Classes

Item	A representation of an item in the gacha game.
Banner	A representation of a banner in the gacha game.
Player	A representation of a player in the gacha game.
Ast	The base class of the abstract syntax tree
_Expr	An expression in the KeyLang grammar
_Term	A term in the KeyLang grammar
_Factor	A factor in the KeyLang grammar
_Float	A float literal in the KeyLang grammar
_Rar	A rarity variable in the KeyLang grammar
Controller	A controller used to control an instance of a gacha game. Used to
Item	A representation of an item in the gacha game.
Banner	A representation of a banner in the gacha game.
Player	A representation of a player in the gacha game.
Ast	The base class of the abstract syntax tree
_Expr	An expression in the KeyLang grammar
_Term	A term in the KeyLang grammar
_Factor	A factor in the KeyLang grammar
_Float	A float literal in the KeyLang grammar
_Rar	A rarity variable in the KeyLang grammar
Item	A representation of an item in the gacha game.
Banner	A representation of a banner in the gacha game.
Player	A representation of a player in the gacha game.
Ast	The base class of the abstract syntax tree
_Expr	An expression in the KeyLang grammar
_Term	A term in the KeyLang grammar
_Factor	A factor in the KeyLang grammar
_Float	A float literal in the KeyLang grammar
_Rar	A rarity variable in the KeyLang grammar
Controller	A controller used to control an instance of a gacha game. Used to
Ast	The base class of the abstract syntax tree
_Expr	An expression in the KeyLang grammar
_Term	A term in the KeyLang grammar
_Factor	A factor in the KeyLang grammar
_Float	A float literal in the KeyLang grammar
_Rar	A rarity variable in the KeyLang grammar

Functions

_sort_item_key(→ float)	The function used to sort items in a list of items
_get_random_weights(→ List[float])	Returns the random weights of the items for the random function
parse(→ Ast)	Parses the inputed KeyLang expression into a KeyLang abstract syntax
_tokenize(→ List[str])	Converts the inputed KeyLang expression into a list of tokens
_parse_tokens(→ Ast)	Parses the inputted tokens into a KeyLang abstract syntax tree
_parse_expr(→ Ast)	Parses the inputted tokens as an expression
_parse_term(→ Ast)	Parses the inputted tokens as a term
_parse_factor(→ Ast)	Parses the inputted tokens as a factor
_parse_base(→ Ast)	Parses the inputted tokens as a base
_parse_const(→ Ast)	Parses the inputted tokens as a constant
interpret(→ float)	Evaluates the KeyLang AST to a value using the rarity
_sort_item_key(→ float)	The function used to sort items in a list of items
_sort_player_key(→ float)	The key used to sort players in a list of players
_get_random_weights(→ List[float])	Returns the random weights of the items for the random function
parse(→ Ast)	Parses the inputed KeyLang expression into a KeyLang abstract syntax
_tokenize(→ List[str])	Converts the inputed KeyLang expression into a list of tokens
_parse_tokens(→ Ast)	Parses the inputted tokens into a KeyLang abstract syntax tree
_parse_expr(→ Ast)	Parses the inputted tokens as an expression
_parse_term(→ Ast)	Parses the inputted tokens as a term
_parse_factor(→ Ast)	Parses the inputted tokens as a factor
_parse_base(→ Ast)	Parses the inputted tokens as a base
_parse_const(→ Ast)	Parses the inputted tokens as a constant
interpret(→ float)	Evaluates the KeyLang AST to a value using the rarity
load_controller(→ gachapy.controller.Controller)	Creates a Controller object from the specified json files
save_controller(→ None)	Saves the controller in json format into the specified files
_sort_item_key(→ float)	The function used to sort items in a list of items
_get_random_weights(→ List[float])	Returns the random weights of the items for the random function
parse(→ Ast)	Parses the inputed KeyLang expression into a KeyLang abstract syntax
_tokenize(→ List[str])	Converts the inputed KeyLang expression into a list of tokens
_parse_tokens(→ Ast)	Parses the inputted tokens into a KeyLang abstract syntax tree
_parse_expr(→ Ast)	Parses the inputted tokens as an expression
_parse_term(→ Ast)	Parses the inputted tokens as a term
_parse_factor(→ Ast)	Parses the inputted tokens as a factor
_parse_base(→ Ast)	Parses the inputted tokens as a base
_parse_const(→ Ast)	Parses the inputted tokens as a constant
interpret(→ float)	Evaluates the KeyLang AST to a value using the rarity
_sort_player_key(→ float)	The key used to sort players in a list of players
parse(→ Ast)	Parses the inputed KeyLang expression into a KeyLang abstract syntax
_tokenize(→ List[str])	Converts the inputed KeyLang expression into a list of tokens
_parse_tokens(→ Ast)	Parses the inputted tokens into a KeyLang abstract syntax tree
_parse_expr(→ Ast)	Parses the inputted tokens as an expression
_parse_term(→ Ast)	Parses the inputted tokens as a term
_parse_factor(→ Ast)	Parses the inputted tokens as a factor
_parse_base(→ Ast)	Parses the inputted tokens as a base
_parse_const(→ Ast)	Parses the inputted tokens as a constant
interpret(→ float)	Evaluates the KeyLang AST to a value using the rarity

Attributes

DEFAULT_KEY	The default key function converting rarity to drop rate (1 / rarity)
DEFAULT_KEY	The default key function converting rarity to drop rate (1 / rarity)

class gachapy.Item(name: str, id: str, rarity: float)

A representation of an item in the gacha game. An item is something that players can collect and pull from banners. Each item must be unique

Fields

namestring

the name of the item

idstring

the id of the item Invariant: must be unique

rarityint

rarity of the item where the higher the number, the higher the rarity Invariant: must be >= 1

name: str

The name of the item

id: str

The id of the item Invariant: must be unique

rarity: int

Rarity of the item where the higher the number, the higher the rarity Invariant: must be >= 1

change_rarity(rarity: float) → bool

Changes the rarity of the Item

Parameters

rarityfloat

new rarity of the item Precondition: rarity must be >= 1

Returns

bool

True if the rarity successfully updated, false otherwise

__str__() → str

Return str(self).

__eq__(other) → bool

Return self==value.

class gachapy.Banner(name: str, id: str, items: List[Item], price: float, key: str)

A representation of a banner in the gacha game. A Banner is where players can choose to spend money in order to obtain a random item from the specific item pool presented in the Banner. Each Banner (should) contain different items and have different prices than other banners to distinguish their offerings

Fields

namestr

name of the banner

idstr

id of the banner Invariant: must be unique

itemsList[Item]

the list of items in the banner

pricefloat

the price of pulling from the banner

keystr

function that takes in rarity and returns the drop rate of the item, written in KeyLang

_weightsList[float]

list of drop weights for items Invariant: weights[i] corresponds to items[i]

name: str

Name of the banner

id: str

The id of the banner Invariant: must be unique

items: List[Item]

The list of the items in the banner

price: float

The price of pulling from the banner

key: str

Function that takes in rarity and returns the drop rate of the item, written in keylang

_weights: List[float]

List of drop weights for items Invariant: weights[i” corresponds to items[i]

add_item(item: Item) → bool

Adds an item to the banner

Parameters

itemItem

item to add to the banner

Returns

None

remove_item(item: Item) → bool

Removes the first occurence of an item from the banner

Parameters

itemItem

item to remove from the banner

Returns

bool

True if item is found in banner, False if otherwise

pull() → Item

Returns a random item out of a banner randomized by weight

Returns

Item

the random item from the pull

__str__() → str

Return str(self).

__eq__(other) → bool

Return self==value.

class gachapy.Player(name: str, id: str, items: List[Item], money: float)

A representation of a player in the gacha game. A Player is someone who can use money to purchase pulls from banners, receive items from banners, and collect items. Each Player is unique and may own different items from each other

Fields

namestr

the name of the player

idstr

the id of the player Invariant: must be unique

itemsList[Item]

the list of items that the player owns

moneyfloat

the amount of money that the player owns

name: str

The name of the player

id: str

The id of the player Invariant: must be unique

items: List[Item]

The list of iterms that the player owns

money: float

The amount of money that the player owns

add_item(item: Item) → None

Adds an item to the player’s inventory

Parameters

itemItem

item to add to player inventory

Returns

None

remove_item(item: Item) → bool

Removes an item from the player’s inventory

Parameters

itemItem

item to add to player inventory

Returns

bool

True if item is found in inventory, False if not

change_money(amount: float) → bool

Adds or removes money from player

Parameters

amountfloat

the amount to add or remove (positive if add, negative if remove) Precondition: if amount removed, leftover amount must be nonnegative

Returns

bool

True if the amount was able to be added or removed from account (does not create a negative money value), False otherwise

get_net_worth() → float

Returns the net worth of the player, calculated by the sum of the rarities of all of the items they own

Returns

float

the net worth of the player

__str__() → str

Return str(self).

__eq__(other) → bool

Return self==value.

gachapy._sort_item_key(item: Item) → float

The function used to sort items in a list of items

Parameters

itemItem

the item to extract the key from

Returns

float

the key of the item

gachapy._get_random_weights(items, key: str) → List[float]

Returns the random weights of the items for the random function

Parameters

itemsList[Item]

list of items to find weights of

keystr

function that takes in rarity and returns the drop rate of the item, written in KeyLang

Returns

List[float]

the list of weights of the items

exception gachapy.SyntaxError

Bases: BaseException

The exception thrown when a syntax error is found

class gachapy.Ast(left=None, right=None, data=None)

Bases: object

The base class of the abstract syntax tree

class gachapy._Expr(left=None, right=None, data=None)

Bases: Ast

An expression in the KeyLang grammar

__str__() → str

Return str(self).

class gachapy._Term(left=None, right=None, data=None)

Bases: Ast

A term in the KeyLang grammar

__str__() → str

Return str(self).

class gachapy._Factor(left=None, right=None, data=None)

Bases: Ast

A factor in the KeyLang grammar

__str__() → str

Return str(self).

class gachapy._Float(left=None, right=None, data=None)

Bases: Ast

A float literal in the KeyLang grammar

__str__() → str

Return str(self).

class gachapy._Rar(left=None, right=None, data=None)

Bases: Ast

A rarity variable in the KeyLang grammar

__str__() → str

Return str(self).

gachapy.parse(s: str) → Ast

Parses the inputed KeyLang expression into a KeyLang abstract syntax tree

Parameters

sstr

the expression to parse

Returns

Ast

the KeyLang AST representative of the expression

gachapy._tokenize(s: str) → List[str]

Converts the inputed KeyLang expression into a list of tokens

Parameters

sstr

the KeyLang expression to tokenize

Returns

List[str]

the list of tokens

gachapy._parse_tokens(tokens: List[str]) → Ast

Parses the inputted tokens into a KeyLang abstract syntax tree

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the tokens

gachapy._parse_expr(tokens: List[str]) → Ast

Parses the inputted tokens as an expression

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the expression

gachapy._parse_term(tokens: List[str]) → Ast

Parses the inputted tokens as a term

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the term

gachapy._parse_factor(tokens: List[str]) → Ast

Parses the inputted tokens as a factor

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the factor

gachapy._parse_base(tokens: List[str]) → Ast

Parses the inputted tokens as a base

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the base

gachapy._parse_const(tokens: str) → Ast

Parses the inputted tokens as a constant

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the constant

gachapy.interpret(ast: Ast, rarity: float) → float

Evaluates the KeyLang AST to a value using the rarity

Parameters

astAst

the AST of the expression

rarityfloat

the value for the rarity

Returns

float

the result of the expression

gachapy.DEFAULT_KEY = '1 / R'

The default key function converting rarity to drop rate (1 / rarity)

gachapy._sort_item_key(item: gachapy.objects.Item) → float

The key used to sort items in a list of items

Parameters

itemItem

the item to extract the key from

Returns

float

the key of the item

gachapy._sort_player_key(player: gachapy.objects.Player) → float

The key used to sort players in a list of players

Parameters

playerPlayer

the player to extract the key from

Returns

float

the key of the player

exception gachapy.PullError

Bases: Exception

An exception thrown when pulling from a banner

class gachapy.Controller(items: Dict[str, gachapy.objects.Item] = {}, banners: Dict[str, gachapy.objects.Banner] = {}, players: Dict[str, gachapy.objects.Player] = {})

A controller used to control an instance of a gacha game. Used to perform all actions needed in a game and manage game information in the form of gachapy objects

Fields

itemsDict[str,Item]

the list of items that are in the item pool for the gacha

bannersDict[str,Banner]

the list of banners that are available for the gacha

playersDict[str,Player]

the list of players enrolled in the gacha

items: Dict[str, gachapy.objects.Item]

The list of items that are in the item pool for the gacha

banners: Dict[str, gachapy.objects.Banner]

The list of banners that are available for the gacha

players: Dict[str, gachapy.objects.Player]

The list of players enrolled in the gacha

find_item_by_name(item_name: str) → gachapy.objects.Item | None

Returns the Item object with the given name or None if not found DEPRICATED: consider using find_item_by_id

Parameters

item_namestr

the name of the item

Returns

Optional[Item]

the item object with the given name or None if not found

find_banner_by_name(banner_name: str) → gachapy.objects.Banner | None

Returns the Banner object with the given name or None if not found DEPRICATED: consider using find_banner_by_id

Parameters

banner_namestr

the name of the banner

Returns

Optional[Banner]

the banner object with the given name or None if not found

find_player_by_name(player_name: str) → gachapy.objects.Player | None

Returns the Player object with the given name or None if not found DEPRICATED: consider using find_player_by_id

Parameters

player_namestr

the name of the player

Returns

Optional[player]

the player object with the given name or None if not found

find_item_by_id(item_id: str) → gachapy.objects.Item | None

Returns the Item object with the given id or None if not found

Parameters

item_idstr

the id of the item

Returns

Optional[Item]

the item object with the given id or None if not found

find_banner_by_id(banner_id: str) → gachapy.objects.Banner | None

Returns the Banner object with the given id or None if not found

Parameters

banner_idstr

the id of the banner

Returns

Optional[Banner]

the banner object with the given id or None if not found

find_player_by_id(player_id: str) → gachapy.objects.Player | None

Returns the Player object with the given id or None if not found

Parameters

player_idstr

the id of the player

Returns

Optional[player]

the player object with the given id or None if not found

pull(player_id: str, banner_id: str) → gachapy.objects.Item | None

Pulls and returns an item from the specified banner for the specified player

Parameters

player_idstr

the id of the selected player Preconditon: must be a valid id

banner_idstr

the id of the selected banner Preconditon: must be a valid id

Returns

Optional[Item]

the item if the pull is successful or None if the player does not have enough money

Raises

PullError if player or banner are not valid

add_new_item(name: str, id: str, rarity: float) → gachapy.objects.Item | None

Adds a new item to the gacha game

Parameters

namestr

the name of the new item

idstr

the id of the new item Precondition: must be unique

rarityfloat

rarity of the item where the higher the number, the higher the rarity Precondition: must be >= 1

Returns

Optional[Item]

the Item object representing the new item or None if an item with the specified id already exists

add_new_banner(name: str, id: str, items_str: gachapy.objects.List[str], price: float, key: str = DEFAULT_KEY) → gachapy.objects.Banner | None

Adds a new banner to the gacha game

Parameters

namestr

the name of the new banner

idstr

the id of the new banner Precondition: must be unique

items_strList[str]

the list of the ids of the items in the banner

pricefloat

the price of pulling from the banner

keystr

function that takes in rarity and returns the drop rate of the item, written in KeyLang

Returns

Optional[Banner]

the Banner object representing the new banner or None if a banner with the specified id already exists

add_new_player(name: str, id: str, start_money: float, items_str: gachapy.objects.List[str] = []) → gachapy.objects.Player | None

Adds a new player to the gacha game

Parameters

namestr

the name of the new player

idstr

the id of the new player

start_moneyfloat

the amount of money the new player will start with

items_strList[str]

the list of the ids of the items the player has

Returns

Optional[Player]

the Player object representing the new player or None if a player with the specified id already exists

remove_item(item_id: str) → gachapy.objects.Item | None

Removes the specified item from the gacha game WARNING: Will also remove from banners and players if found, costly operation

Parameters

item_idstr

the name of the item to remove

Returns

Optional[Item]

the removed item or None if item does not exist

remove_banner(banner_id: str) → gachapy.objects.Banner | None

Removes the specified banner from the gacha game

Parameters

banner_idstr

the id of the banner to remove

Returns

Optional[Banner]

the removed banner or None if banner does not exist

remove_player(player_id: str) → gachapy.objects.Player | None

Removes the specified player from the gacha game

Parameters

player_idstr

the id of the player to remove

Returns

Optional[Player]

the removed player or None if player does not exist

create_random_banner(name: str, id: str, num_items: int, price: float = -1, key: str = DEFAULT_KEY) → gachapy.objects.Banner | None

Creates a random banner with the given name and number of items

The price is automatically determined by the average of the rarities of the items selected if a price is not specified

Parameters

namestr

the name of the random banner

idstr

the id of the random banner Precondition: must be unique

num_itemsint

the number of items in the banner

pricefloat

the price of the banner

keystr

function that takes in rarity and returns the drop rate of the item, written in KeyLang

Returns

Optional[Banner]

the banner created or None if a banner with the name specified already exists

remove_all_banners() → None

Removes all of the banners in the game

Returns

None

top_items(num_items: int) → gachapy.objects.List[gachapy.objects.Item]

Returns the top specified number of items in the game sorted by rarity

Parameters

num_itemsint

the number of items to return Precondition: must be >= 1

Returns

List[Item]

the list of top items

top_players(num_players: int) → gachapy.objects.List[gachapy.objects.Player]

Returns the top specified number of players in the game sorted by net worth

Parameters

num_playersint

the number of players to return Precondition: must be >= 1

Returns

List[Player]

the list of top players

__str__() → str

Return str(self).

class gachapy.Item(name: str, id: str, rarity: float)

A representation of an item in the gacha game. An item is something that players can collect and pull from banners. Each item must be unique

Fields

namestring

the name of the item

idstring

the id of the item Invariant: must be unique

rarityint

rarity of the item where the higher the number, the higher the rarity Invariant: must be >= 1

name: str

The name of the item

id: str

The id of the item Invariant: must be unique

rarity: int

Rarity of the item where the higher the number, the higher the rarity Invariant: must be >= 1

change_rarity(rarity: float) → bool

Changes the rarity of the Item

Parameters

rarityfloat

new rarity of the item Precondition: rarity must be >= 1

Returns

bool

True if the rarity successfully updated, false otherwise

__str__() → str

Return str(self).

__eq__(other) → bool

Return self==value.

class gachapy.Banner(name: str, id: str, items: List[Item], price: float, key: str)

A representation of a banner in the gacha game. A Banner is where players can choose to spend money in order to obtain a random item from the specific item pool presented in the Banner. Each Banner (should) contain different items and have different prices than other banners to distinguish their offerings

Fields

namestr

name of the banner

idstr

id of the banner Invariant: must be unique

itemsList[Item]

the list of items in the banner

pricefloat

the price of pulling from the banner

keystr

function that takes in rarity and returns the drop rate of the item, written in KeyLang

_weightsList[float]

list of drop weights for items Invariant: weights[i] corresponds to items[i]

name: str

Name of the banner

id: str

The id of the banner Invariant: must be unique

items: List[Item]

The list of the items in the banner

price: float

The price of pulling from the banner

key: str

Function that takes in rarity and returns the drop rate of the item, written in keylang

_weights: List[float]

List of drop weights for items Invariant: weights[i” corresponds to items[i]

add_item(item: Item) → bool

Adds an item to the banner

Parameters

itemItem

item to add to the banner

Returns

None

remove_item(item: Item) → bool

Removes the first occurence of an item from the banner

Parameters

itemItem

item to remove from the banner

Returns

bool

True if item is found in banner, False if otherwise

pull() → Item

Returns a random item out of a banner randomized by weight

Returns

Item

the random item from the pull

__str__() → str

Return str(self).

__eq__(other) → bool

Return self==value.

class gachapy.Player(name: str, id: str, items: List[Item], money: float)

A representation of a player in the gacha game. A Player is someone who can use money to purchase pulls from banners, receive items from banners, and collect items. Each Player is unique and may own different items from each other

Fields

namestr

the name of the player

idstr

the id of the player Invariant: must be unique

itemsList[Item]

the list of items that the player owns

moneyfloat

the amount of money that the player owns

name: str

The name of the player

id: str

The id of the player Invariant: must be unique

items: List[Item]

The list of iterms that the player owns

money: float

The amount of money that the player owns

add_item(item: Item) → None

Adds an item to the player’s inventory

Parameters

itemItem

item to add to player inventory

Returns

None

remove_item(item: Item) → bool

Removes an item from the player’s inventory

Parameters

itemItem

item to add to player inventory

Returns

bool

True if item is found in inventory, False if not

change_money(amount: float) → bool

Adds or removes money from player

Parameters

amountfloat

the amount to add or remove (positive if add, negative if remove) Precondition: if amount removed, leftover amount must be nonnegative

Returns

bool

True if the amount was able to be added or removed from account (does not create a negative money value), False otherwise

get_net_worth() → float

Returns the net worth of the player, calculated by the sum of the rarities of all of the items they own

Returns

float

the net worth of the player

__str__() → str

Return str(self).

__eq__(other) → bool

Return self==value.

gachapy._get_random_weights(items, key: str) → List[float]

Returns the random weights of the items for the random function

Parameters

itemsList[Item]

list of items to find weights of

keystr

function that takes in rarity and returns the drop rate of the item, written in KeyLang

Returns

List[float]

the list of weights of the items

exception gachapy.SyntaxError

Bases: BaseException

The exception thrown when a syntax error is found

class gachapy.Ast(left=None, right=None, data=None)

Bases: object

The base class of the abstract syntax tree

class gachapy._Expr(left=None, right=None, data=None)

Bases: Ast

An expression in the KeyLang grammar

__str__() → str

Return str(self).

class gachapy._Term(left=None, right=None, data=None)

Bases: Ast

A term in the KeyLang grammar

__str__() → str

Return str(self).

class gachapy._Factor(left=None, right=None, data=None)

Bases: Ast

A factor in the KeyLang grammar

__str__() → str

Return str(self).

class gachapy._Float(left=None, right=None, data=None)

Bases: Ast

A float literal in the KeyLang grammar

__str__() → str

Return str(self).

class gachapy._Rar(left=None, right=None, data=None)

Bases: Ast

A rarity variable in the KeyLang grammar

__str__() → str

Return str(self).

gachapy.parse(s: str) → Ast

Parses the inputed KeyLang expression into a KeyLang abstract syntax tree

Parameters

sstr

the expression to parse

Returns

Ast

the KeyLang AST representative of the expression

gachapy._tokenize(s: str) → List[str]

Converts the inputed KeyLang expression into a list of tokens

Parameters

sstr

the KeyLang expression to tokenize

Returns

List[str]

the list of tokens

gachapy._parse_tokens(tokens: List[str]) → Ast

Parses the inputted tokens into a KeyLang abstract syntax tree

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the tokens

gachapy._parse_expr(tokens: List[str]) → Ast

Parses the inputted tokens as an expression

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the expression

gachapy._parse_term(tokens: List[str]) → Ast

Parses the inputted tokens as a term

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the term

gachapy._parse_factor(tokens: List[str]) → Ast

Parses the inputted tokens as a factor

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the factor

gachapy._parse_base(tokens: List[str]) → Ast

Parses the inputted tokens as a base

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the base

gachapy._parse_const(tokens: str) → Ast

Parses the inputted tokens as a constant

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the constant

gachapy.interpret(ast: Ast, rarity: float) → float

Evaluates the KeyLang AST to a value using the rarity

Parameters

astAst

the AST of the expression

rarityfloat

the value for the rarity

Returns

float

the result of the expression

gachapy.load_controller(filename: str) → gachapy.controller.Controller

Creates a Controller object from the specified json files

Parameters

filenamestr

the path of the json file

Returns

Controller

the controller loaded from the specified files

gachapy.save_controller(controller: gachapy.controller.Controller, filename: str) → None

Saves the controller in json format into the specified files

Parameters

controllerController

the controller to save into files

filenamestr

the path to the json file

Returns

None

class gachapy.Item(name: str, id: str, rarity: float)

A representation of an item in the gacha game. An item is something that players can collect and pull from banners. Each item must be unique

Fields

namestring

the name of the item

idstring

the id of the item Invariant: must be unique

rarityint

rarity of the item where the higher the number, the higher the rarity Invariant: must be >= 1

name: str

The name of the item

id: str

The id of the item Invariant: must be unique

rarity: int

Rarity of the item where the higher the number, the higher the rarity Invariant: must be >= 1

change_rarity(rarity: float) → bool

Changes the rarity of the Item

Parameters

rarityfloat

new rarity of the item Precondition: rarity must be >= 1

Returns

bool

True if the rarity successfully updated, false otherwise

__str__() → str

Return str(self).

__eq__(other) → bool

Return self==value.

class gachapy.Banner(name: str, id: str, items: List[Item], price: float, key: str)

A representation of a banner in the gacha game. A Banner is where players can choose to spend money in order to obtain a random item from the specific item pool presented in the Banner. Each Banner (should) contain different items and have different prices than other banners to distinguish their offerings

Fields

namestr

name of the banner

idstr

id of the banner Invariant: must be unique

itemsList[Item]

the list of items in the banner

pricefloat

the price of pulling from the banner

keystr

function that takes in rarity and returns the drop rate of the item, written in KeyLang

_weightsList[float]

list of drop weights for items Invariant: weights[i] corresponds to items[i]

name: str

Name of the banner

id: str

The id of the banner Invariant: must be unique

items: List[Item]

The list of the items in the banner

price: float

The price of pulling from the banner

key: str

Function that takes in rarity and returns the drop rate of the item, written in keylang

_weights: List[float]

List of drop weights for items Invariant: weights[i” corresponds to items[i]

add_item(item: Item) → bool

Adds an item to the banner

Parameters

itemItem

item to add to the banner

Returns

None

remove_item(item: Item) → bool

Removes the first occurence of an item from the banner

Parameters

itemItem

item to remove from the banner

Returns

bool

True if item is found in banner, False if otherwise

pull() → Item

Returns a random item out of a banner randomized by weight

Returns

Item

the random item from the pull

__str__() → str

Return str(self).

__eq__(other) → bool

Return self==value.

class gachapy.Player(name: str, id: str, items: List[Item], money: float)

A representation of a player in the gacha game. A Player is someone who can use money to purchase pulls from banners, receive items from banners, and collect items. Each Player is unique and may own different items from each other

Fields

namestr

the name of the player

idstr

the id of the player Invariant: must be unique

itemsList[Item]

the list of items that the player owns

moneyfloat

the amount of money that the player owns

name: str

The name of the player

id: str

The id of the player Invariant: must be unique

items: List[Item]

The list of iterms that the player owns

money: float

The amount of money that the player owns

add_item(item: Item) → None

Adds an item to the player’s inventory

Parameters

itemItem

item to add to player inventory

Returns

None

remove_item(item: Item) → bool

Removes an item from the player’s inventory

Parameters

itemItem

item to add to player inventory

Returns

bool

True if item is found in inventory, False if not

change_money(amount: float) → bool

Adds or removes money from player

Parameters

amountfloat

the amount to add or remove (positive if add, negative if remove) Precondition: if amount removed, leftover amount must be nonnegative

Returns

bool

True if the amount was able to be added or removed from account (does not create a negative money value), False otherwise

get_net_worth() → float

Returns the net worth of the player, calculated by the sum of the rarities of all of the items they own

Returns

float

the net worth of the player

__str__() → str

Return str(self).

__eq__(other) → bool

Return self==value.

gachapy._sort_item_key(item: Item) → float

The function used to sort items in a list of items

Parameters

itemItem

the item to extract the key from

Returns

float

the key of the item

gachapy._get_random_weights(items, key: str) → List[float]

Returns the random weights of the items for the random function

Parameters

itemsList[Item]

list of items to find weights of

keystr

function that takes in rarity and returns the drop rate of the item, written in KeyLang

Returns

List[float]

the list of weights of the items

exception gachapy.SyntaxError

Bases: BaseException

The exception thrown when a syntax error is found

class gachapy.Ast(left=None, right=None, data=None)

Bases: object

The base class of the abstract syntax tree

class gachapy._Expr(left=None, right=None, data=None)

Bases: Ast

An expression in the KeyLang grammar

__str__() → str

Return str(self).

class gachapy._Term(left=None, right=None, data=None)

Bases: Ast

A term in the KeyLang grammar

__str__() → str

Return str(self).

class gachapy._Factor(left=None, right=None, data=None)

Bases: Ast

A factor in the KeyLang grammar

__str__() → str

Return str(self).

class gachapy._Float(left=None, right=None, data=None)

Bases: Ast

A float literal in the KeyLang grammar

__str__() → str

Return str(self).

class gachapy._Rar(left=None, right=None, data=None)

Bases: Ast

A rarity variable in the KeyLang grammar

__str__() → str

Return str(self).

gachapy.parse(s: str) → Ast

Parses the inputed KeyLang expression into a KeyLang abstract syntax tree

Parameters

sstr

the expression to parse

Returns

Ast

the KeyLang AST representative of the expression

gachapy._tokenize(s: str) → List[str]

Converts the inputed KeyLang expression into a list of tokens

Parameters

sstr

the KeyLang expression to tokenize

Returns

List[str]

the list of tokens

gachapy._parse_tokens(tokens: List[str]) → Ast

Parses the inputted tokens into a KeyLang abstract syntax tree

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the tokens

gachapy._parse_expr(tokens: List[str]) → Ast

Parses the inputted tokens as an expression

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the expression

gachapy._parse_term(tokens: List[str]) → Ast

Parses the inputted tokens as a term

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the term

gachapy._parse_factor(tokens: List[str]) → Ast

Parses the inputted tokens as a factor

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the factor

gachapy._parse_base(tokens: List[str]) → Ast

Parses the inputted tokens as a base

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the base

gachapy._parse_const(tokens: str) → Ast

Parses the inputted tokens as a constant

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the constant

gachapy.interpret(ast: Ast, rarity: float) → float

Evaluates the KeyLang AST to a value using the rarity

Parameters

astAst

the AST of the expression

rarityfloat

the value for the rarity

Returns

float

the result of the expression

gachapy.DEFAULT_KEY = '1 / R'

The default key function converting rarity to drop rate (1 / rarity)

gachapy._sort_player_key(player: gachapy.objects.Player) → float

The key used to sort players in a list of players

Parameters

playerPlayer

the player to extract the key from

Returns

float

the key of the player

exception gachapy.PullError

Bases: Exception

An exception thrown when pulling from a banner

class gachapy.Controller(items: Dict[str, gachapy.objects.Item] = {}, banners: Dict[str, gachapy.objects.Banner] = {}, players: Dict[str, gachapy.objects.Player] = {})

A controller used to control an instance of a gacha game. Used to perform all actions needed in a game and manage game information in the form of gachapy objects

Fields

itemsDict[str,Item]

the list of items that are in the item pool for the gacha

bannersDict[str,Banner]

the list of banners that are available for the gacha

playersDict[str,Player]

the list of players enrolled in the gacha

items: Dict[str, gachapy.objects.Item]

The list of items that are in the item pool for the gacha

banners: Dict[str, gachapy.objects.Banner]

The list of banners that are available for the gacha

players: Dict[str, gachapy.objects.Player]

The list of players enrolled in the gacha

find_item_by_name(item_name: str) → gachapy.objects.Item | None

Returns the Item object with the given name or None if not found DEPRICATED: consider using find_item_by_id

Parameters

item_namestr

the name of the item

Returns

Optional[Item]

the item object with the given name or None if not found

find_banner_by_name(banner_name: str) → gachapy.objects.Banner | None

Returns the Banner object with the given name or None if not found DEPRICATED: consider using find_banner_by_id

Parameters

banner_namestr

the name of the banner

Returns

Optional[Banner]

the banner object with the given name or None if not found

find_player_by_name(player_name: str) → gachapy.objects.Player | None

Returns the Player object with the given name or None if not found DEPRICATED: consider using find_player_by_id

Parameters

player_namestr

the name of the player

Returns

Optional[player]

the player object with the given name or None if not found

find_item_by_id(item_id: str) → gachapy.objects.Item | None

Returns the Item object with the given id or None if not found

Parameters

item_idstr

the id of the item

Returns

Optional[Item]

the item object with the given id or None if not found

find_banner_by_id(banner_id: str) → gachapy.objects.Banner | None

Returns the Banner object with the given id or None if not found

Parameters

banner_idstr

the id of the banner

Returns

Optional[Banner]

the banner object with the given id or None if not found

find_player_by_id(player_id: str) → gachapy.objects.Player | None

Returns the Player object with the given id or None if not found

Parameters

player_idstr

the id of the player

Returns

Optional[player]

the player object with the given id or None if not found

pull(player_id: str, banner_id: str) → gachapy.objects.Item | None

Pulls and returns an item from the specified banner for the specified player

Parameters

player_idstr

the id of the selected player Preconditon: must be a valid id

banner_idstr

the id of the selected banner Preconditon: must be a valid id

Returns

Optional[Item]

the item if the pull is successful or None if the player does not have enough money

Raises

PullError if player or banner are not valid

add_new_item(name: str, id: str, rarity: float) → gachapy.objects.Item | None

Adds a new item to the gacha game

Parameters

namestr

the name of the new item

idstr

the id of the new item Precondition: must be unique

rarityfloat

rarity of the item where the higher the number, the higher the rarity Precondition: must be >= 1

Returns

Optional[Item]

the Item object representing the new item or None if an item with the specified id already exists

add_new_banner(name: str, id: str, items_str: gachapy.objects.List[str], price: float, key: str = DEFAULT_KEY) → gachapy.objects.Banner | None

Adds a new banner to the gacha game

Parameters

namestr

the name of the new banner

idstr

the id of the new banner Precondition: must be unique

items_strList[str]

the list of the ids of the items in the banner

pricefloat

the price of pulling from the banner

keystr

function that takes in rarity and returns the drop rate of the item, written in KeyLang

Returns

Optional[Banner]

the Banner object representing the new banner or None if a banner with the specified id already exists

add_new_player(name: str, id: str, start_money: float, items_str: gachapy.objects.List[str] = []) → gachapy.objects.Player | None

Adds a new player to the gacha game

Parameters

namestr

the name of the new player

idstr

the id of the new player

start_moneyfloat

the amount of money the new player will start with

items_strList[str]

the list of the ids of the items the player has

Returns

Optional[Player]

the Player object representing the new player or None if a player with the specified id already exists

remove_item(item_id: str) → gachapy.objects.Item | None

Removes the specified item from the gacha game WARNING: Will also remove from banners and players if found, costly operation

Parameters

item_idstr

the name of the item to remove

Returns

Optional[Item]

the removed item or None if item does not exist

remove_banner(banner_id: str) → gachapy.objects.Banner | None

Removes the specified banner from the gacha game

Parameters

banner_idstr

the id of the banner to remove

Returns

Optional[Banner]

the removed banner or None if banner does not exist

remove_player(player_id: str) → gachapy.objects.Player | None

Removes the specified player from the gacha game

Parameters

player_idstr

the id of the player to remove

Returns

Optional[Player]

the removed player or None if player does not exist

create_random_banner(name: str, id: str, num_items: int, price: float = -1, key: str = DEFAULT_KEY) → gachapy.objects.Banner | None

Creates a random banner with the given name and number of items

The price is automatically determined by the average of the rarities of the items selected if a price is not specified

Parameters

namestr

the name of the random banner

idstr

the id of the random banner Precondition: must be unique

num_itemsint

the number of items in the banner

pricefloat

the price of the banner

keystr

function that takes in rarity and returns the drop rate of the item, written in KeyLang

Returns

Optional[Banner]

the banner created or None if a banner with the name specified already exists

remove_all_banners() → None

Removes all of the banners in the game

Returns

None

top_items(num_items: int) → gachapy.objects.List[gachapy.objects.Item]

Returns the top specified number of items in the game sorted by rarity

Parameters

num_itemsint

the number of items to return Precondition: must be >= 1

Returns

List[Item]

the list of top items

top_players(num_players: int) → gachapy.objects.List[gachapy.objects.Player]

Returns the top specified number of players in the game sorted by net worth

Parameters

num_playersint

the number of players to return Precondition: must be >= 1

Returns

List[Player]

the list of top players

__str__() → str

Return str(self).

exception gachapy.SyntaxError

Bases: BaseException

The exception thrown when a syntax error is found

class gachapy.Ast(left=None, right=None, data=None)

Bases: object

The base class of the abstract syntax tree

class gachapy._Expr(left=None, right=None, data=None)

Bases: Ast

An expression in the KeyLang grammar

__str__() → str

Return str(self).

class gachapy._Term(left=None, right=None, data=None)

Bases: Ast

A term in the KeyLang grammar

__str__() → str

Return str(self).

class gachapy._Factor(left=None, right=None, data=None)

Bases: Ast

A factor in the KeyLang grammar

__str__() → str

Return str(self).

class gachapy._Float(left=None, right=None, data=None)

Bases: Ast

A float literal in the KeyLang grammar

__str__() → str

Return str(self).

class gachapy._Rar(left=None, right=None, data=None)

Bases: Ast

A rarity variable in the KeyLang grammar

__str__() → str

Return str(self).

gachapy.parse(s: str) → Ast

Parses the inputed KeyLang expression into a KeyLang abstract syntax tree

Parameters

sstr

the expression to parse

Returns

Ast

the KeyLang AST representative of the expression

gachapy._tokenize(s: str) → List[str]

Converts the inputed KeyLang expression into a list of tokens

Parameters

sstr

the KeyLang expression to tokenize

Returns

List[str]

the list of tokens

gachapy._parse_tokens(tokens: List[str]) → Ast

Parses the inputted tokens into a KeyLang abstract syntax tree

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the tokens

gachapy._parse_expr(tokens: List[str]) → Ast

Parses the inputted tokens as an expression

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the expression

gachapy._parse_term(tokens: List[str]) → Ast

Parses the inputted tokens as a term

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the term

gachapy._parse_factor(tokens: List[str]) → Ast

Parses the inputted tokens as a factor

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the factor

gachapy._parse_base(tokens: List[str]) → Ast

Parses the inputted tokens as a base

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the base

gachapy._parse_const(tokens: str) → Ast

Parses the inputted tokens as a constant

Parameters

tokensList[str]

the list of tokens to parse

Returns

Ast

the abstract syntax tree representative of the constant

gachapy.interpret(ast: Ast, rarity: float) → float

Evaluates the KeyLang AST to a value using the rarity

Parameters

astAst

the AST of the expression

rarityfloat

the value for the rarity

Returns

float

the result of the expression