State Representations

dcss-ai-wrapper offers multiple state representations to support multiple types of AI agents.

Vector-based Representations

Vector-based representations are available as a python list data type containing values where the index of the list corresponds to the feature. The complete specification is listed below, per category of data describing the state (i.e. player stats, map data, etc.).

• Player stats (vector)

• Player inventory (vector)

• Player spells (vector)

• Player abilities (vector)

• Player skills (vector)

• Map data Line-of-Sight (LOS) (vector)

• Map data current level (vector)

• Map data all (vector)

PDDL-based Representations

Planning Domain Definition Language (PDDL) is a relational, symbolic logic state representation. The following state data is available via functions that return a set of PDDL facts, that are aligned with the PDDL domain file found under models/fastdownward_simple.pddl.

• Player stats (PDDL)

• Player inventory (PDDL)

• Player skills (PDDL)

• Map data Line-of-Sight (LOS) (PDDL)

• Map data current level (PDDL)

• Map data all (PDDL)

• Static Background Knowledge (PDDL)

API: Vector-based Representations

Player stats (vector)

src.dcss.state.game.GameState.get_player_stats_vector(verbose=False)

The following player stats are returned by this function:

Vector Index	Description of Data	Data Type if available
0	health	Int
1	health_max	Int
2	health_max_real	Int
3	mana_points	Int
4	mana_points_max	Int
5	mana_points_real	Int
6	AC	Int
7	EV	Int
8	SH	Int
9	Str	Int
10	Str max	Int
11	Int	Int
12	Int max	Int
13	Dex	Int
14	Dex max	Int
15	XL	Int
16	Experience until next level	0-100 percentage
14	God	Int
15	Piety Level	Int
16	Spell slots left	Int
17	gold	Int
18	rFire	Int
19	rCold	Int
20	rNeg	Int
21	rPois	Int
22	rElec	Int
23	rCorr	Int
24	MR	Int
25	Stealth	Int
26	HPRegen per turn	Float
27	MPRegen per turn	Float
28	See invisible	Boolean
30	Faith	Boolean
31	Spirit	Boolean
32	Reflect	Boolean
33	Harm	Boolean
34	game turns	Float
35	game time	Float
36	attack speed	Int
37	movement speed	Int
169	Player Place (Dungeon, Vaults, etc.)	Boolean
38	Agile status effect	Boolean
39	Antimagic status effect	Boolean
40	Augmentation status effect	Boolean
41	Bad Forms status effect	Boolean
42	Berserk status effect	Boolean
170	Unable to Berserk status effect	Boolean
43	Black Mark status effect	Boolean
44	Blind status effect	Boolean
45	Brilliant status effect	Boolean
46	Charm status effect	Boolean
47	Confusing Touch status effect	Boolean
48	Confusion status effect	Boolean
49	Constriction status effect	Boolean
50	Cooldowns status effect	Boolean
51	Corona status effect	Boolean
52	Corrosion status effect	Boolean
53	Darkness status effect	Boolean
54	Dazed status effect	Boolean
55	Death Channel status effect	Boolean
56	Death’s Door status effect	Boolean
57	Deflect Missiles status effect	Boolean
58	Disjunction status effect	Boolean
59	Divine Protection status effect	Boolean
60	Divine Shield status effect	Boolean
61	Doom Howl status effect	Boolean
62	Drain status effect	Boolean
63	Engorged status effect	Boolean
64	Engulf status effect	Boolean
65	Fast+Slow status effect	Boolean
66	Fear status effect	Boolean
67	Finesse status effect	Boolean
68	Fire Vulnerable status effect	Boolean
69	Flayed status effect	Boolean
70	Flight status effect	Boolean
71	Frozen status effect	Boolean
72	Haste status effect	Boolean
73	Heavenly Storm status effect	Boolean
74	Held status effect	Boolean
75	Heroism status effect	Boolean
76	Horrified status effect	Boolean
77	Inner Flame status effect	Boolean
78	Invisibility status effect	Boolean
79	Lava status effect	Boolean
80	Leda’s Liquefaction status effect	Boolean
81	Leda’s Liquefaction status effect	Boolean
82	Magic Contamination status effect	Boolean
83	Mark status effect	Boolean
84	Mesmerised status effect	Boolean
85	Might status effect	Boolean
86	Mirror Damage status effect	Boolean
87	No Potions status effect	Boolean
88	No Scrolls status effect	Boolean
89	Olgreb’s Toxic Radiance status effect	Boolean
90	Orb status effect	Boolean
91	Ozocubu’s Armour status effect	Boolean
92	Paralysis status effect	Boolean
93	Petrifying/Petrified status effect	Boolean
94	Poison status effect	Boolean
95	Powered by Death status effect	Boolean
96	Quad Damage status effect	Boolean
97	Recall status effect	Boolean
98	Regenerating status effect	Boolean
99	Repel Missiles status effect	Boolean
100	Resistance status effect	Boolean
101	Ring of Flames status effect	Boolean
102	Sapped Magic status effect	Boolean
103	Scrying status effect	Boolean
104	Searing Ray status effect	Boolean
105	Serpent’s Lash status effect	Boolean
106	Shroud of Golubria status effect	Boolean
107	Sickness status effect	Boolean
108	Silence status effect	Boolean
109	Silence status effect	Boolean
110	Sleep status effect	Boolean
111	Slimify status effect	Boolean
112	Slow status effect	Boolean
113	Sluggish status effect	Boolean
114	Starving status effect	Boolean
115	Stat Zero status effect	Boolean
116	Sticky Flame status effect	Boolean
117	Still Winds status effect	Boolean
118	Swiftness status effect	Boolean
119	Teleport Prevention status effect	Boolean
120	Teleport status effect	Boolean
121	Tornado status effect	Boolean
122	Transmutations status effect	Boolean
123	Umbra status effect	Boolean
124	Vitalisation status effect	Boolean
125	Vulnerable status effect	Boolean
126	Water status effect	Boolean
127	Weak status effect	Boolean
128	Acute Vision mutation	Boolean
129	Antennae mutation	Boolean
130	Beak mutation	Boolean
131	Big Wings mutation	Boolean
132	Blink mutation	Boolean
133	Camouflage mutation	Boolean
134	Clarity mutation	Boolean
135	Claws mutation	Boolean
136	Cold Resistance mutation	Boolean
137	Electricity Resistance mutation	Boolean
138	Evolution mutation	Boolean
139	Fangs mutation	Boolean
140	Fire Resistance mutation	Boolean
141	High MP mutation	Boolean
142	Hooves mutation	Boolean
143	Horns mutation	Boolean
144	Icy Blue Scales mutation	Boolean
145	Improved Attributes mutation	Boolean
146	Iridescent Scales mutation	Boolean
147	Large Bone Plates mutation	Boolean
148	Magic Resistance mutation	Boolean
149	Molten Scales mutation	Boolean
150	Mutation Resistance mutation	Boolean
151	Passive Mapping mutation	Boolean
152	Poison Breath mutation	Boolean
153	Poison Resistance mutation	Boolean
154	Regeneration mutation	Boolean
155	Repulsion Field mutation	Boolean
156	Robust mutation	Boolean
157	Rugged Brown Scales mutation	Boolean
158	Shaggy Fur mutation	Boolean
159	Slimy Green Scales mutation	Boolean
160	Stinger mutation	Boolean
161	Strong Legs mutation	Boolean
162	Talons mutation	Boolean
163	Tentacle Spike mutation	Boolean
164	Thin Metallic Scales mutation	Boolean
165	Thin Skeletal Structure mutation	Boolean
166	Tough Skin mutation	Boolean
167	Wild Magic mutation	Boolean
168	Yellow Scales mutation	Boolean

Returns:

A list of features representing the player’s stats

Player inventory (vector)

src.dcss.state.game.GameState.get_player_inventory_vector()

Player has 52 inventory slots corresponding to each lowercase and uppercase letter of the English alphabet.

Each item is represented by a vector of size 7:

Vector Index	Description of Data	Data Type if available
0	Item type
1	quantity	Int
2	Item Bonus	Int
3	Is Equipped	Boolean
4	First property
5	Second property
6	Third property

Returns:

a list of size 364 (52 inventory items each represented with 7 features shown above)

Player spells (vector)

src.dcss.state.game.GameState.get_player_spells_vector()

Player has a maximum of 21 spell slots for spells to be learned.

Each of these 21 spells slots is represented by a vector of 3 values:

Vector Index	Description of Data	Data Type if available
0	Spell ID.	Int repr. spell ID
1	Spell SkillName	Int repr. skill ID
2	Spell SkillName #2	Int repr. skill ID
3	Spell SkillName #3	Int repr. skill ID
4	Failure Likelihood	Int 0-100
5	Spell Level	Int

Additionally, there are 118 spells that can be learned if the player has found a book item with a given spell, therefore we need an additional 118 slots in this vector representing whether each spell is available to be learned.

Returns:

a list of size 21*6 + 118.

Player abilities (vector)

src.dcss.state.game.GameState.get_player_abilities_vector()

There are 94 possible abilities a player may acquire. For each of these abilities, they are represented by the following vector:

Vector Index	Description of Data	Data Type if available
0	Ability is ID	Int repr. spell ID
1	Failure Likelihood	Int 0-100
2	Magic Point Cost	Boolean
3	Piety Point Cost	Boolean
4	Has Delay Cost	Boolean
5	Has Frailty Cost	Boolean

# TODO there are probably more costs (like health, etc) that should end up as additional rows in this table

Returns:

a list of size 94*6.

Player skills (vector)

src.dcss.state.game.GameState.get_player_skills_vector()

Player has 31 skills that increase over time if the player is actively ‘training’ those skills.

Each skill is represented by a vector of size 3:

Vector Index	Description of Data	Data Type if available
0	Current value	Float
1	Training Percentage	Int (0-100)
2	Aptitude	Int

Returns:

a list of size 93

Map data Line-of-Sight (LOS) (vector)

src.dcss.state.game.GameState.get_egocentric_LOS_map_data_vector(radius=7)

Returns a vector containing data on the tiles in a ((radius*2)+1)^2 square centered on the player.

See cell.py get_cell_vector() for a description of what is in each cell vector.

Map data current level (vector)

src.dcss.state.game.GameState.get_egocentric_level_map_data_vector()

Returns a vector containing data on the tiles on the player’s current level.

Uses the same tile representation of vectors of size 34 from get_egocentric_LOS_map_data()

Returns a vector with no upperbound if traveling through levels such as Abyss or Labyrinth. More realistically returns a vector ranging from a minimum size of 7,650 (225 LOS tiles * 34) up to possible sizes of 68,000+ (2000 tiles * 34).

Map data all (vector)

src.dcss.state.game.GameState.get_all_map_data_vector()

Returns a vector containing data on the tiles the player has encountered so far in the game.

Uses the same tile representation of vectors of size 34 from get_egocentric_LOS_map_data()

Returns a vector with no upperbound if traveling through levels such as Abyss or Labyrinth. More realistically returns a vector ranging from a minimum size of 7,650 (225 LOS tiles * 34) up to possible sizes of 3,400,000+ (100,000 tiles * 34).

API: PDDL-based Representations

Player stats (PDDL)

src.dcss.state.game.GameState.get_player_stats_pddl()

Returns PDDL 2.2 level 1 which DOES NOT include all aspects of numeric planning.

PDDL predicates that are provided via this function:

• playerhealth

• playermagicpoints

• player_worshipping

• player_piety

• player_has_available_spell_slot

• player_resist_fire

• player_resist_cold

• player_resist_neg

• player_resist_pois

• player_resist_elec

• player_resist_corr

• player_willpower

• player_stealth

• player_see_invis

• player_faith_status

• player_spirit_status

• player_reflect_status

• player_harm_status

• player_movement_speed

• player_attack_speed

• playerplace

• player_has_status_effect

• player_has_mutation

Therefore the following player stats aren’t available.

Player Stat	Description of Data	Why not included?
AC	Represents Armour	Non-relative Int
EV	Represents Evasion	Non-relative Int
SH	Represents Shelf	Non-relative Int
Strength	Current value	Non-relative Int
Intelligence	Training Percentage	Non-relative Int
Dexterity	Aptitude	Non-relative Int

Returns a list of PDDL facts representing player stats

Player inventory (PDDL)

src.dcss.state.game.GameState.get_player_inventory_pddl()

Returns a simple PDDL representation for inventory items that will describe items with the following predicates. Note that this function returns two data objects, first is a list of inventory object names and the second is a list of the pddl facts, as strings, about those objects.

Predicates currently supported: * equipped * cursed * item_bonus (refers to the +3 kinds of bonuses on items) * weapon, scroll, ammunition, potion, or armour (others may be discovered and then must be added here) * only_one_left or more_than_one_remaining

Player skills (PDDL)

src.dcss.state.game.GameState.get_player_skills_pddl()

Skill names as objects are already provided in the PDDL domain file since they are constant across all characters and game modes.

Only PDDL facts about whether each skill has training off, low, or high is returned, and the current value of said skill using qualitative quantifiers of: ‘none’, ‘low’, ‘medium_low’, ‘medium’, ‘medium_high’, ‘high’, ‘maxed’

Map data Line-of-Sight (LOS) (PDDL)

src.dcss.state.game.GameState.get_egocentric_LOS_map_data_pddl(radius=7)

Returns a list of PDDL facts representing the tiles around the player for the given radius. Information about tiles outside of this radius is not returned.

Map data current level (PDDL)

Map data all (PDDL)

src.dcss.state.game.GameState.get_all_map_data_pddl()

Returns a list of PDDL facts for every tile encountered by the player thus far.

Static Background Knowledge (PDDL)

src.dcss.state.game.GameState.get_background_pddl()

Returns a static list of pddl facts, including all type instances and dungeon level connections.