小游戏派对数据包须知（v1.1 | 1/21）

这是技术说明，详见活动说明页面

定义

定义在本说明文件中会出现的几个名词：

"这局游戏"，"一局游戏"：指的是由多个小游戏串联形成的一次玩家体验。玩家在不同的"小游戏"内获得分数最终相加以决定在"这局游戏"中的排名。
"小游戏"：指有一个作者制作的，单个小游戏。
"必须"，"必须不"：必须按照说明进行。违反其内容是不被接受的。框架中没有为违反其内容的可能留有余地。
"应当"，"不应当"：除非有及其特别且重要的理由，否则需要按照说明执行。框架已经为可能的违背留有准备。

依赖库文件

以下会提供两个依赖库文件：core.zip和libs.zip。
使用这两个文件可以使DHP在你编辑自己的数据包时提供来自核心框架以及其他库的补全和纠错——包括函数，记分板，标签，假玩家，存储的nbt检查等——而不需要将它们内置进数据包中。

下载这两个文件，将其置于电脑上的任意路径。（目前上传至群内）
在数据包的根目录新建文件spyglass.json，内容如下：

{
	"env": {
		"dependencies": [
                        "file:///C:/path/to/core.zip",
			"file:///C:/path/to/libs.zip",
			"@vanilla-mcdoc"
		],
		"gameVersion": "1.21.4"
	}
}

自行修改路径以指向两个下载的文件。路径允许包含空格或中文字符等。可以Ctrl+点击来确定路径可以打开下载的文件。
其中，core.zip包含了核心框架提供的内容。libs.zip包含了其他库提供的内容。若libs.zip提供的补全过多，干扰了正常工作，可以只使用core.zip。

让Vscode执行Developer:Reload Windows或重启Vscode。Spyglass初始化结束后应该就可以获得补全了。当更新文件后，或当你发现补全的行为异常（如部分补全丢失），请使Vs Code执行Spyglass: Reset Project Cahce命令

若你计划直接在ssh上编辑数据包，ssh服务器中已经有提前存在且会自动更新的依赖文件。简单地将路径设置为：

            "file:///_mcsvr/PPsWTFJP_Sandboxes/libs.zip",
            "file:///_mcsvr/PPsWTFJP_Sandboxes/core.zip",

即可直接引用它们

游戏运行与注册

想要一个小游戏被正确地识别与运行，需要创建6个指定名称的函数文件，位于同一个路径下：

ini.mcfunction - 初始化函数

任何无法在小游戏开始瞬间完成的初始化（比如随机生成建筑，需要数秒的操作等）均需要放置于此。

初始化结束后执行function core:event/ini_complete告知核心框架。若没有需要初始化的内容可以直接执行该函数。

所有小游戏的初始化步骤均会在一局游戏最开始进行（即没有任何小游戏正式开始前）。同一时间只会执行一个小游戏的初始化步骤，所有其他程序都会等待其执行完毕。注意这并非开始游戏的函数。在你的ini函数执行后，你的小游戏开始前，可能有其他小游戏执行。

start.mcfunction - 游戏开始

该函数被执行时证明小游戏开始。该函数应该负责所有小游戏自身的初始设置（例如传送等）。

当小游戏完全结束，且清理了所有标签，临时实体等后，执行function core:event/game_end告知框架。

reset.mcfunction - 游戏收尾

与ini函数相对地，任何无法瞬间完成，但是暂时不执行没有影响的收尾操作应当放置于此。所有小游戏执行结束后统一收尾。

没有类似需要，或执行结束后，执行function core:event/reset_complete通知主框架。

同一时间只会执行一个小游戏的收尾步骤。所有其他程序都会等待其执行完毕。

kill.mcfunction - 强制终止

该函数被执行时，应当可以立刻，无条件地终止该小游戏，并尽量擦除临时数据。
若一个小游戏因为特定原因不方便实现此功能应该备案。

cleanup.mcfunction - 重置玩家

该函数会被框架以玩家为执行者运行。它应该清理小游戏在该玩家身上留下的任何影响（比如任何可能的tag，状态效果，属性修饰器等）。本函数主要用于处理中途退出的玩家。您不应该依赖本函数来收尾小游戏，换言之在执行function core:event/game_end结束游戏之前仍需要手动清理所有残留影响。
该函数运行时玩家有可能从未玩过你的小游戏，因此执行时不要以“玩家有残留的影响”为前提清理残留的影响。

meta.mcfunction - 元文件

该函数包含了小游戏的基础信息。应该将本函数加入到标签#core:games中。
该函数中应该包含一条data命令，修改指定的storage以存储小游戏的信息。
修改至：data modify storage core:game new append value {...}

数据应当包含：

（借助Minecraft Wiki制作）

示范（点击展开）展开示范（点击展开）隐藏

data modify storage core:game new append value \
{id:"test",\
    author:"Dahesor",tie_break:0b,\
    path:"core:builtin/test_game/meta",\
    max_score:10,\
    display:{\
        name:'{"text": "测试游戏 ","color": "yellow","italic": false}',\
        credit:'{"text": "Dahesor","color": "yellow","italic": false}',\
        lore:['{"text": "用于测试的游戏","italic": false,"color": "gray"}','{"text": "没有实际的程序","italic": false,"color": "gray"}','{"text": "点击测试框架运行游戏","italic": false,"color": "gray"}'],\
        tutorial:"测试游戏。如果能看到这行文字说明教程显示成功了",\
        icon:{id:"minecraft:bedrock"}\
    },\
    location:[0,0],player_count:{group:1,min:1,max:2147483647},\
    allow_return:1b\
}

玩家管理

只有在记分板player上的分数为1的玩家才应该被视为参与了游戏。其他人为旁观者。任何选中所有游戏玩家的选择器都应该包含本条件。若没有在meta.mcfunction中设置allow_return:1b，则玩家的这个分数有可能因为退出重进游戏而改变。
旁观者在本记分板上的分数为0。你仍需要照顾旁观者，如在游戏开始时tp他们至游戏场地，限制其活动范围等。
player是一个只读记分板。请不要修改其内容。

提供的记分板数据，变量，实体等

提供以下记分板与数据：

int与calculator：
这两个记分板用于临时计算。请勿保存任何数值，使用时默认其上的数据可能已经被其他人做了任意修改
例外：#<数字>请勿设置为<数字>以外的值。如：请只将#10 int设置为10。
score：该记分板存有这局游戏至此所有玩家的分数。只读。
lifetime_score：该记分板存有所有玩家的生涯总分。只读。
data：该记分板存有本局游戏的各种数据：只读。
- round：当前是第几个小游戏。
- session：本局游戏的会话验证号。
- player_count：当前游戏中玩家的数量。
- ini_player_count：游戏刚开始时玩家的数量。
- time：自这局游戏开始至今过去的时间。
- gametime：存有time query gametime的返回值。
- multiplier：当前游戏的得分乘数。
new_score：应当把玩家本轮得分存入这里以进行交接（见下文"玩家得分"部分）。
uid：由VDC提供 -- 玩家的不重复UID。只读。

提供以下实体：

9-9-9-9-9：位于出生点区块上空，常加载的箱子矿车，用于物品操作。使用前假定其内容可能在其他人修改后为任何东西，使用后请擦除所有物品数据。勿要在这里保存任何数据。

提供以下存储：

minecraft:temp：临时计算与缓存用。使用前假定其内容可能在其他人修改后为任何东西，使用后请擦除所有数据。勿要在这里保存任何数据。

默认游戏规则与环境

在每个小游戏开始前，所有游戏规则都会重置为一个默认值。时间会被设置为noon，天气设定为晴朗。
如有需要请在开始前自行调整规则。
下附所有游戏规则的默认值：

默认值（点击展开）展开默认值（点击展开）隐藏

#gamerule sendCommandFeedback false
#本行暂不执行以方便测试

time set noon
weather clear
gamerule announceAdvancements true
gamerule blockExplosionDropDecay true
gamerule commandBlockOutput false
gamerule commandModificationBlockLimit 32768
gamerule disableElytraMovementCheck false
gamerule disablePlayerMovementCheck false
gamerule disableRaids true
gamerule doDaylightCycle false
gamerule doEntityDrops false
gamerule doFireTick false
gamerule doImmediateRespawn true
gamerule doInsomnia false
gamerule doLimitedCrafting false
gamerule doMobLoot false
gamerule doMobSpawning false
gamerule doPatrolSpawning false
gamerule doTileDrops false
gamerule doTraderSpawning false
gamerule doVinesSpread false
gamerule doWardenSpawning false
gamerule doWeatherCycle false
gamerule drowningDamage true
gamerule enderPearlsVanishOnDeath true
gamerule fallDamage true
gamerule fireDamage true
gamerule forgiveDeadPlayers true
gamerule freezeDamage true
gamerule globalSoundEvents true
gamerule keepInventory true
gamerule lavaSourceConversion false
gamerule logAdminCommands true
gamerule maxCommandChainLength 9999999
gamerule maxCommandForkCount 9999999
gamerule maxEntityCramming 0
gamerule mobExplosionDropDecay true
gamerule mobGriefing false
gamerule naturalRegeneration true
gamerule playersNetherPortalCreativeDelay 9999999
gamerule playersNetherPortalDefaultDelay 9999999
gamerule playersSleepingPercentage 120
gamerule projectilesCanBreakBlocks false
gamerule randomTickSpeed 0
gamerule reducedDebugInfo false
gamerule showDeathMessages true
gamerule snowAccumulationHeight 1
gamerule spawnChunkRadius 1
gamerule spawnRadius 0
gamerule spectatorsGenerateChunks true
gamerule tntExplosionDropDecay false
gamerule universalAnger false
gamerule waterSourceConversion true

玩家得分

玩家小游戏内获得的分数应当存储于new_score记分板上。小游戏开始时该所有玩家在该记分板上分数会被设置为0。
小游戏结束后框架会将new_score上的分数，乘以小游戏顺序系数后，加在该局游戏的玩家总分上。
为了确保各个游戏得分的均衡性，做如下规定：

小游戏中表现最好的玩家应当被奖励约50分左右。若你的小游戏比较复杂或具备技术性可以适当提高，反之亦然
小游戏中表现最差的玩家不应当被奖励超过25分，以让小游戏有拉开分差的能力。小游戏越具备技术难度，则应当允许玩家拉开更大的比分。

地理位置

为方便合作，所有作者应该在不同的mca文件上工作。(mca就是region，entities，与poi文件夹下用来存储区块信息的文件)
如此一来，每个人只需要提供自己的数据包以及建筑位于的mca文件即可，合并时不需要使用外部工具。
如上图元信息中所写，所有小游戏都会注明自身的地理位置。不允许不同的作者使用同一个mca。
请在占用mca之前在此帖报备，并检查是否已经有其他人占用了这个mca。
你可以在F3中查看当前所处的mca。
建议将建筑置于mca中心——尤其是建筑没有墙壁的时候——以尽量避免玩家在远处看到其他建筑。

r0.0.mca被大厅占用。

可选库

将提供以下几个库以便捷地实现各种功能。除了核心框架使用的库外，所有其他库默认禁用，需要手动开启。

gu

将数组UUID转为十六进制字符串。见Github。
静态库，永久开启。

VDC

雨弓前置。见此。
部分模块需要手动开启，详见说明。

Dahesor's Schdule

保留执行环境的schdule。见此。
动态。核心框架需要，无法关闭（无兼容性担忧）。

Health & Effects Display

【使用资源包】在list或belowName展示玩家当前生命值与状态效果。见此。
资源包下载见群文件“[资源包] 生命值与状态效果显示器”
动态，小游戏开始时默认禁用，需要手动开启：

#启用
function core:libs/hp_eff/enable
#禁用
function core:libs/hp_eff/disable

Actionbar Mixer

混合显示状态栏信息。见Github。
动态，小游戏开始时默认禁用，需要手动开启：

#启用
function core:libs/actionbar_mixer/enable
#禁用
function core:libs/actionbar_mixer/disable

记分板Sidebar UI显示器

【使用资源包】利用sidebar制作个性化的UI界面。请在群文件中查阅《记分板Sidebar UI显示器说明文档》。资源包下载见群文件"记分板Sidebar UI显示器 v1.0"中
动态，小游戏开始时默认禁用，需要手动开启：

#启用
function core:libs/sidebar_ui/enable
#禁用
function core:libs/sidebar_ui/disable

Pos -> Motion计算器

提供一个函数dtm:calculate_motion。会将执行位置的坐标减去执行者的Pos后，乘以0.4存入Motion中（莫问为啥是0.4）
静态，永久开启