小游戏派对数据包须知 v1.1 (1/21)

Dahesor

小游戏派对数据包须知（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）
静态，永久开启

Rainbow_

催更捏

melon_444

这是ao的

Rainbow_

关于这次活动的赛程，我有一点想法。如果大家都有时间的话可以这么办：
首先是为时三天的集中独立开发，类似mapjam。单人或双人一组，美工+dper的形式。如果是两个 dper 合作开发，至少要有一人多负责一些美工，算是学习。
三天期满之后还没有收工的，作为惩罚，必须接受其他人共同接管并参与完善和修缮你的地图（动手动脚.jpg）。时间暂设两天。再用一天调整所有箱庭共通道具的数值和一致性，可能再邀请其他人来修缮一下美工，测试一下之类的。最后一天组织集中游玩。总共一周的历程。游玩之后总结需要改进的地方，修改完之后再开一次。开大概 2 ~ 3 次，就迭代的差不多可以作为合集地图对外发布了。最后总的历程应该在十五天左右。
这是以类似 jam 活动的形式来进行合集式集体创作的点子。只不过限时结束之后并不是终止，而是接管和合作阶段，大家一起把没做完的部分做完。既有独立开发也有合作开发，还是团建。并且表达形式多样但是有主题和大系统把所有子项联系在一起。我觉得这样的形式能办下来的话应该会挺有意思。
另外也可以加入评分机制。在每一轮游玩之后评分。被接管的项目分数要有三成到一半的比例被抽走。可能是丢掉可能是分给主要接管者（如果设置主要的接管者的话。也有可能是全员共同接管而不是帮扶形式）
我去单独发个帖吧

Rainbow_

我觉得应该每个游戏设置总的能获取的分数，然后参赛玩家根据游戏内得分，以一定的权重瓜分。游戏内得分和权重可以是线性，也可以是其他函数。比如说竞技性越强的，头部玩家得分越高，中后段的得分差距不大，可以拉类似指数函数的曲线。但是总的积分不变。这一点类似概率密度函数。不知道能不能实现这一点。

Dahesor

Rainbow_ 感觉更像是小游戏自己要考虑的？不过出规范指导啥的倒是可以

Rainbow_

Dahesor 分数毕竟是全局的东西。而且这种基本的内容如果也让开发者自己考虑，做框架的初衷就达不到了。
我的建议是以游戏整体的流程长度和其他方面的考虑，规定一个总体能获得的分。当然根据游戏表现，总体表现好分数总和就多也不是不行，但是最好也是出个约束算法。不然有可能会有人找漏洞刷分。
另外，我是觉得没必要太过考虑技术难度之类的。毕竟我们搞派对主要还是合家欢。从这个角度出发，反而应该多设置一点参与奖之类的。从竞技上来讲，分差的系数小一点，领先的人也要表现得更好、持续地好，才能不被颇具随机性地反超。
而且一提到拉分差之类的，我会比较担心有的人打法太分奴，或者一些朋友玩得没那么好受到打击。
所以分数还是作为添头就行。不应该出现打得差的十几分，打得好的一两百分这种情况。除非完全摆烂不玩。
也就是说我的思路更多的是根据参与度、交互频率和深度打分，而不是在技术、性能上的表现。
限定总分和设定密度函数的设计大概也是为此服务。

Dahesor

Rainbow_

小游戏总是要提供数据的吧。以下两者应该是等价的：

小游戏提供每位玩家得分，框架乘以一个系数调整
框架设定一个总分，小游戏提供每个玩家的得分百分比

Rainbow_

Dahesor 我意思框架设定总分，小游戏提供玩家的原始分数（权重，框架自行换算为百分比）。然后框架应该能通过一系列处理把玩家的原始分数映射为结算得分。
不过说的也是，分差应该给多大，小游戏内部设计好就行了，没必要交给框架做。