Python接口指南
使用示例
eden-v0使用示例
具体使用代码如下：
import gym, eden
import time
if __name__ == '__main__':
e = gym.make('eden-v0')
e.reset()
for t in range(100):
action = [[0,0,0]]
obs, rew, done, info = e.step(action)
print(f"[Step: {t}] info:{info}")
time.sleep(.5)
其中，obs为agent从环境中观测到的相关信息，该信息的具体组织方式参见一维变长Observation接口。若环境中只包含一个agent，该观察信息为如下所示的二维numpy.ndarray数组：
array([[ 0., 1., 0., 0., 1., 27., 11., 100., 99., 99., 45.,
10., 5., 1., 1., 8., 1., 2., 20., -1., -1., -1.,
-1., -1., -1., -1., -1., -1., -1., -1., -1., -1., -1.,
-1., -1., -1., -1., -1., -1., -1., -1., -1., -1., -1.,
-1., -1., -1., -1., -1., -1., -1., -1., -1., -1., -1.,
-1., -1., -1., -1., 4., -1., -1., -1., -1., 0., 4.,
6., 2., 24., 4., 3., 25., 3., 3., 28., 3., 1.,
32., 3., 0., 2., 26., 0., 7., 27., 0., 5., 28.,
0.]])
若环境中包含有多个agent，该观察信息为包含有多个list的一维numpy.ndarray数组：
array([list([0.0, 1.0, 0.0, 0.0, 1.0, 27.0, 11.0, 100.0, 99.0, 99.0, 45.0, 10.0, 5.0, 1.0, 1.0, 8.0, 1.0, 2.0, 20.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, 4.0, -1.0, -1.0, -1.0, -1.0, 0.0, 3.0, 4.0, 3.0, 24.0, 3.0, 3.0, 28.0, 3.0, 1.0, 32.0, 5.0, 1.0, 0.0, 22.0, 0.0, 2.0, 26.0, 0.0, 7.0, 27.0, 2.0, 8.0, 27.0, 0.0, 5.0, 28.0, 0.0]),
list([0.0, 1.0, 0.0, 0.0, 33.0, 39.0, 11.0, 100.0, 99.0, 99.0, 45.0, 10.0, 5.0, 1.0, 1.0, 8.0, 1.0, 2.0, 20.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, 4.0, -1.0, -1.0, -1.0, -1.0, 0.0, 2.0, 4.0, 32.0, 33.0, 6.0, 39.0, 38.0, 2.0, 2.0, 34.0, 35.0, 2.0, 36.0, 38.0, 0.0])],
dtype=object)
action为agent输出到环境中执行的动作，该变量为二维list或者numpy.ndarray数组，其中第一个维度代表agent的数目，第二个维度为输入到环境中的action参数，具体内容参见逻辑Action输入接口。
以上代码的输出结果如下：
(eden) eirrac@DESKTOP-UDNC6LP:~/project/Eden$ python main.py
pygame 2.1.2 (SDL 2.0.16, Python 3.8.12)
Hello from the pygame community. https://www.pygame.org/contribute.html
[Step: 0] info:[{'position': '1-27', 'action': 'Idle', 'target': 'None', 'result': 'success', 'attr_increment': {'Hunger': -1.0, 'Thirst': -1.0}, 'dead': False}]
eden-v1使用示例
具体使用代码如下：
import gym, eden
import time
if __name__ == '__main__':
e = gym.make('eden-v1')
e.reset()
for t in range(100):
action = [[0,0,0]]
obs, rew, done, info = e.step(action)
print(f"[Step: {t}] info:{info}")
time.sleep(.5)
其中，obs为agent从环境中观测到的相关信息，该信息的具体组织方式参见二维Observation接口。该观察信息的输出为如下所示三维numpy.ndarray数组，第一个维度表示agent的数目：
>>> obs = e.reset()
>>> type(obs)
<class 'numpy.ndarray'>
>>> obs
array([[[-1, -1, -1, ..., -1, -1, -1],
[-1, -1, -1, ..., -1, -1, -1],
[-1, -1, -1, ..., -1, -1, -1],
...,
[-1, -1, -1, ..., -1, -1, -1],
[-1, -1, -1, ..., 1, 1, 8],
[ 1, 2, -1, ..., -1, -1, -1]]])
>>> obs.shape
(1, 82, 40)
action为agent输出到环境中执行的动作，该tuple变量中包含有agent数目个一维numpy.ndarray数组，每个数组中包含有三个数值，具体内容参见鼠标点击Action输入接口，其输出如下：
>>> action = e.action_space.sample()
>>> type(action)
<class 'tuple'>
>>> action
(array([ 1, 31, 27]),)
>>> type(action[0])
<class 'numpy.ndarray'>
eden-v2使用示例
具体使用代码如下：
import gym, eden
import time
if __name__ == '__main__':
e = gym.make('eden-v2')
e.reset()
for t in range(100):
action = [[0,0,0]]
obs, rew, done, info = e.step(action)
print(f"[Step: {t}] info:{info}")
time.sleep(.5)
其中，obs为agent从环境中观测到的相关信息，该信息的具体组织方式参见一维定长Observation接口；action为agent输出到环境中执行的动作，该变量为二维list或者numpy.ndarray数组，其中第一个维度代表agent的数目，第二个维度为输入到环境中的action参数，具体内容参见逻辑Action输入接口。
各种接口说明
Observation接口
Observation接口给出智能体所能获得的观察信息，包括一维变长Observation接口、一维定长Observation接口，以及二维Observation接口等三种。
一维变长Observation接口
一维Observation接口的调用如下伪代码中所示：
import gym,eden
env = gym.make('eden-v0')
obs, rew, done, info = env.step(action)
其中obs为一个二维numpy数组，表示所有智能体接收到的Observation，第一维表示智能体的索引，第二维表示具体接收到的信息。该一维Observation向量按照Block块进行组织，各块的具体含义入下表中所示：
| Block | 开始索引 | 块长度 | 说明 |
|---|---|---|---|
| season | 0 | 1 | |
| is_daytime | season.end + 1 | 1 | |
| weather | is_daytime.end + 1 | 1 | |
| landform | weather.end + 1 | 1 | |
| position | landform.end +1 | 2 | |
| attribute | position.end + 1 | 1 + attribute_number | |
| backpack | attribute.end + 1 | 1 + backpack_slot_number * 2 | |
| equipment | backpack.end + 1 | 1 + equipment_slot_number | |
| other_agent (in vision) | equipment.end + 1 | 1 + other_agent_number * 3 | other_agent_number是可变的 |
| being (in vision) | other_agent.end+ 1 | 1 + being_number * 3 | being_number是可变的 |
| resource (in vision) | being.end + 1 | 1 + resource_number * 3 | resource_number是可变的 |
各个Block的具体含义如下表中所示：
| Block | 组织结构 | 示例 | 说明 |
|---|---|---|---|
| position | agent_x, agent_y | 5, 5 | |
| attribute | L, attr_1, …, attr_L | 11, {HP}, {Hunger}, {Thirst}, {Temperature}, {ATK}, {DEF}, {AttackDistance}, {CollectDistance}, {Vision}, {NightVision}, {Speed} | L表示该Block的长度 |
| backpack | L, item_1_nameInt, item_1_count, …, item_L_nameInt, item_L_count | 2, -1, -1, -1, -1 | nameInt表示物品对应的索引 |
| equipment | L, equipment_1_nameInt, …, equipment_L_nameInt | 3, -1, -1, -1 | |
| other_agent | L, agent_1_nameInt, agent_1_x, agent_1_y, …, agent_L_nameInt, agent_L_x, agent_L_y | 0 | |
| being | L, being_1_nameInt, being_1_x, being_1_y, …, being_L_nameInt, being_L_x, being_L_y | 1, 0, 2, 2 | |
| resource | L, resource_1_nameInt, resource_1_x, resource_1_y, …, resource_L_nameInt, resource_L_x, resource_L_y | 0 | |
| item | L, item_1_nameInt, item_1_x, item_1_y, …, item_L_nameInt, item_L_x, item_L_y | 1, 10, 3, 3 |
其中attribute的长度为11，backpack和equipment分别对应配置选项指南中2_agent.csv文件中的BackpackSize列中数值以及Slot列中装备槽的个数。
二维Observation接口
二维Observation接口的调用如下伪代码中所示：
import gym,eden
env = gym.make('eden-v1')
obs, rew, done, info = env.step(action)
其中obs为一个三维numpy数组，表示所有智能体接收到的Observation，第一维表示智能体的索引，第二、三维表示具体接收到的信息。该二维Observation数组按照如下图中所示的结构进行组织：
其中，MapSizeX和MapSizeY表示地图的大小，来自配置选项指南中的0_general.csv文件；
backpack表示背包中的物品情况，长度为$2\times BackpackSize$（来自配置选项指南中的2_agent.csv文件），每两位数值分别表示背包中物品的数目以及对应的类型，没有物品这些位的值为$-1,-1$；
equipment表示智能体身上的装备情况，没有装备时的默认值为$-1$，长度为配置选项指南中2_agent.csv文件中Slot列中的装备槽的数目；
synthesis表示合成表，对应配置选项指南中4_item.csv文件中SynthesizeTable列不为空的物品；
landform表示地图上各个位置所属的地形，对应配置选项指南中1_landform.csv文件中的地形，数值从索引0开始按该地形表的配置升序；
object表示智能体观察到的各种物品的情况，若观察到物品，则对应位置上的值为该物品的nameInt索引，否则为默认值$-1$；
图中白色部分表示agent当前的相关的属性值。
一维定长Observation接口
该接口为二维Observation接口的一维版本，相对位置按照二维Observation接口中描述计算。
Action接口
逻辑Action输入接口
在配置好的环境中，使用 env.step() 函数给入智能体输入到环境中的动作，具体伪代码如下所示:
import numpy as np
action = np.array([[1, 3, 2]])
obs, rew, done, info = env.step(action)
每个智能体在每个时间步给出一个 动作，将所有智能体的动作合并到action中后输入到环境中进行执行。 action 是一个维度为(n, 3)的二维numpy数组，其中 n 表示环境中的智能体数目。
智能体中的每个action各个维度之间的意义如下表中所示：
| Action | 参数0 | 参数1 | 参数2 | 说明 |
|---|---|---|---|---|
| Idle | 0 | meaningless | meaningless | |
| Attack | 1 | {x} of target | {y} of target | 参数1-2为动作目标的坐标 |
| Collect | 2 | {x} of target | {y} of target | 参数1-2为动作目标的坐标 |
| Pickup | 3 | {x} of target | {y} of target | 参数1-2为动作目标的坐标 |
| Consume | 4 | {nameInt} of ITEM | number | ITEM为4_item.csv中定义的物品 |
| Equip | 5 | {nameInt} of ITEM | meaningless | ITEM为4_item.csv中定义的物品 |
| Synthesize | 6 | {nameInt} of ITEM | number | ITEM为4_item.csv中定义的物品 |
| Discard | 7 | {nameInt} of ITEM | meaningless | ITEM为4_item.csv中定义的物品 |
| Move | 8 | {x} of destination | {y} of destination |
鼠标点击Action输入接口
在配置好的环境中，使用 env.step() 函数给入智能体输入到环境中的动作，具体伪代码如下所示:
import numpy as np
action = np.array([[1, 3, 2]])
obs, rew, done, info = env.step(action)
其中，action变量为二维numpy.ndarray数组，第一个维度表示agent的索引，第二个维度为给入环境的动作。
在该Action接口中，第一个数值type取值为${0,1}$，分别表示正向动作与负向动作，剩下两个数值表示地图上的某一个坐标或者背包以及合成表上的某个位置$(x,y)$。
- 当$(x,y)$为地图上坐标时，type的取值为0时表示Collect/Pickup/Move，取值为1时表示Attack/Move
- 当$(x,y)$坐标上没有物品或者超出agent动作范围时，该动作为Move
- 当$(x,y)$为背包上坐标时，type的取值为0时表示Consume/Equip，取值为1时表示Discard
- 当$(x,y)$为合成表上坐标时，type的取值为0时表示Synthesis