puzzlescript-gists

PuzzleScript人类创作游戏（完整Gist语料库）是一个包含34,712个由人类创作的PuzzleScript游戏源代码的数据集，这些代码从公共GitHub gist中收集。数据集旨在支持网格谜题动态的世界模型、代码生成、程序合成和游戏设计等研究任务。每个游戏都包含完整的PuzzleScript源代码，定义了游戏规则（机制）和一个或多个关卡（初始状态）。数据集以JSONL格式提供，包含以下字段：id（原始GitHub gist标识符）、content（完整的PuzzleScript源代码）、source_collections（来源档案名称，如PuzzleScript Gallery、Pedros PuzzleScript Archive、itch.io或GitHub gist）、parse_status（解析状态，如ok、parse_error等）、n_objects和n_levels（解析后的对象和关卡计数）、mechanics_hash和levels_hash（基于机制和关卡的规范哈希值，用于去重）、dedup_group（去重聚类键）、is_dedup_representative（是否为聚类的代表样本）和n_in_dedup_group（聚类大小）。数据集经过去重处理，基于机制和关卡的哈希值进行聚类，确保仅当两者完全匹配时才视为重复，从而保留真实的变体。去重后包含25,103个独特游戏。数据来源于多个公共档案，包括PuzzleScript Gallery、Pedros PuzzleScript Archive和itch.io，以及原始GitHub gist抓取。数据集遵循“other”许可，每个游戏属于其原始作者，仅用于研究目的。Human-Created PuzzleScript Games (Complete Gist Corpus) is a dataset containing 34,712 human-authored PuzzleScript game source codes collected from public GitHub Gists. This dataset is designed to support research tasks such as dynamic world models for grid puzzles, code generation, program synthesis, and game design. Each entry contains complete PuzzleScript source code that defines the game rules (mechanics) and one or more levels (initial states). The dataset is provided in JSONL format, with the following fields: "id" (original GitHub Gist identifier), "content" (full PuzzleScript source code), "source_collections" (name of the source archive, e.g., PuzzleScript Gallery, Pedros PuzzleScript Archive, itch.io, or GitHub Gists), "parse_status" (parsing status, e.g., "ok", "parse_error", etc.), "n_objects" and "n_levels" (counts of parsed objects and levels), "mechanics_hash" and "levels_hash" (canonical hashes based on game mechanics and levels for deduplication), "dedup_group" (deduplication clustering key), "is_dedup_representative" (whether the entry is the representative sample of its cluster), and "n_in_dedup_group" (size of the deduplication cluster). The dataset has undergone deduplication processing: clustering is performed based on the mechanics and levels hashes, with duplicates only considered when both values match exactly to preserve genuine variants. After deduplication, the dataset contains 25,103 unique games. The data is sourced from multiple public archives including PuzzleScript Gallery, Pedros PuzzleScript Archive, itch.io, and raw GitHub Gist crawls. The dataset is licensed under "other" terms; each game belongs to its original author, and the dataset is intended for research purposes only.

原始信息汇总

数据集概述

数据集名称：PuzzleScript Human-Authored Games (Full Gist Corpus)
规模：34,712个由人类创作的PuzzleScript游戏，来自公共GitHub gists。
语言：主要使用英语。

数据集内容

• 包含每个游戏的完整PuzzleScript源代码。
• 每个游戏定义了重写规则（机制）和一个或多个关卡（初始状态）。
• 数据集中保留了每个不同的gist，每条数据都标注了去重簇标识，便于一步过滤出唯一游戏集（去重后为25,103个不同游戏）。

数据字段

字段	描述
id	原始GitHub gist ID
content	完整的PuzzleScript源代码
source_collections	游戏来源的档案名称（如PuzzleScript Gallery、Pedros PuzzleScript Archive、itch.io）或GitHub gist
parse_status	解析状态：ok、parse_error、preprocess_error、timeout
n_objects	游戏中的对象数量（仅限解析成功的游戏）
n_levels	关卡数量（仅限解析成功的游戏）
mechanics_hash	机制的唯一指纹（忽略名称和美术资源）
levels_hash	关卡的唯一指纹（忽略名称和美术资源）
dedup_group	去重簇的键
is_dedup_representative	是否为该簇的代表游戏（每个簇一个）
n_in_dedup_group	该簇中的游戏数量

去重逻辑

• 仅当机制指纹和关卡指纹均与已保留游戏匹配时，才视为重复；因此真正的小变体版本会被保留。
• 去重过程可重现，使用附带的dedup_master.json和dedup_master.py文件。

数据来源与许可

• 游戏来源包括：
  • PuzzleScript Gallery
  • Pedros PuzzleScript Archive
  • itch.io
  • 直接来自GitHub gists的爬取
• 不包含GitHub用户名，仅保留gist ID作为标识符。
• 本数据集中的游戏为第三方人类创作作品，仅供研究目的重新分发；每个游戏版权归原作者所有。
• 数据集许可证为other。

适用任务

• 文本生成
• 世界模型（网格谜题动力学）
• 代码生成
• 程序综合
• 游戏设计

搜集汇总

数据集介绍

构建方式

该数据集囊括了34,712款由人类创作的PuzzleScript游戏完整源代码，全部采集自公开的GitHub Gist平台。为确保数据纯净，数据集排除了非标准版的PuzzleScript-Plus文件，并对所有条目进行了可复现的去重处理，依据mechanics_hash与levels_hash双重指纹判定唯一性，保留了包含机制或关卡微小变体的有效差异。每条记录均标注了解析状态、对象与关卡数量、来源归档名称及去重聚类标识，构建过程严谨透明。

特点

数据集的核心特色在于其完整性与细粒度标注。所有游戏源代码被完整保留，并配备丰富的结构化字段，如parse_status、n_objects、n_levels及用于去重聚类的dedup_group与is_dedup_representative标记。独特的双重哈希指纹机制确保仅当机制与关卡完全一致时才被判定为重复，从而保留多样化的设计变体。此外，每款游戏均标注了来源归档，如PuzzleScript Gallery或itch.io，便于溯源与学术引用。

使用方法

数据集设计为开箱即用，用户可通过HuggingFace Datasets库快速加载。例如，调用load_dataset('smearle/puzzlescript-gists', split='train')载入全部数据，再使用filter(lambda r: r['is_dedup_representative'])轻松获取25,103款去重后的唯一游戏。每条记录包含完整源代码字符串及丰富的元数据，非常适合用于文本生成、代码合成、程序推演及网格谜题世界模型的训练与评估。

背景与挑战

背景概述

PuzzleScript是一种面向网格谜题游戏的领域特定语言，其简洁的语法和丰富的表现力吸引了大量游戏设计师与研究者。在此背景下，PuzzleScript Human-Authored Games (Full Gist Corpus)数据集于近年由研究机构或社区贡献者构建，旨在系统性地收集人类创作的PuzzleScript游戏源码。该数据集收录了34,712个来自公开GitHub Gist的游戏，并融合了PuzzleScript Gallery、Pedro's PuzzleScript Archive及itch.io等多个权威来源，为程序合成、代码生成及世界模型研究提供了大规模、高质量的语料。其核心研究问题聚焦于如何通过解析游戏规则与关卡结构，捕捉网格谜题的内在动态逻辑，进而推动基于学习的游戏设计与推理技术发展。该数据集的发布在AI与游戏交叉领域产生了显著影响，为探索结构化代码生成与物理世界建模的融合开辟了新途径。

当前挑战

该数据集面临的领域挑战在于，PuzzleScript游戏本质上是具有严格语法规则和空间约束的网格谜题，其世界模型的学习需要同时理解对象交互、规则改写和层次演化，这对现有序列生成模型在长程依赖和结构保真性上提出了更高要求。构建过程中，挑战主要体现在大规模源码的自动解析与去重上：游戏源文件可能因注释、命名差异或轻量修改而产生变体，为此研究团队设计了双重指纹机制（mechanics_hash与levels_hash）以识别真正语义重复，并保留了基于集合覆盖的去重策略。此外，非标准PuzzleScript-Plus扩展文件需通过专用检测脚本隔离，同时处理解析超时、预处理错误及编码异常等异常情况，以确保数据集的纯粹性与可复现性。

常用场景

经典使用场景

PuzzleScript Gists数据集汇聚了34,712款由人类创作的PuzzleScript游戏源码，是研究基于规则的网格推理解谜游戏的宝贵资源。其最经典的使用场景在于为世界模型学习提供丰富的游戏机制与关卡数据。研究者可以通过这些源码解析游戏中内蕴的物理规则与逻辑约束，从而训练能够理解并模拟网格世界动态演化的语言模型。此外，该数据集也广泛用于代码生成任务的基准测试——模型需要从零开始生成完整的PuzzleScript脚本，或在给定部分约束的条件下补全游戏逻辑。其去重版本保留了25,103款独立游戏，确保了训练数据的多样性与公平性，进一步提升了模型在复杂规则推理中的泛化能力。

实际应用

在实际应用层面，PuzzleScript Gists数据集为智能游戏设计工具与辅助创作系统提供了坚实的数据基石。基于该数据训练的语言模型能够自动生成符合逻辑约束的游戏关卡，或根据设计师输入的少量草图建议完整的游戏规则，大幅降低原型开发的门槛。在教育工作者的手中，该数据集可用于构建交互式编程教学平台，通过向学习者展示多样化的游戏源码案例，直观演示规则定义与状态转换的编程思想。此外，一些非线性叙事引擎与创意写作工具也借鉴了该数据中的规则设计模式，使得非专业用户能够快速构建出具备自洽逻辑的交互式故事场景。

衍生相关工作

此数据集的发布催生了一系列经典的研究工作，推动了神经符号学习与程序合成的前沿进展。研究人员基于PuzzleScript Gists率先提出了规则感知变换器架构，该模型通过显式编码游戏中的表格驱动条件来增强解码阶段的逻辑遵循能力。另一项开创性工作则专注于利用该数据训练世界模型，在潜空间中对游戏关卡的下一步动态进行模拟预测，显著提升了智能体在未见关卡上的零样本规划成功率。此外，针对代码摘要与检索任务，有学者构建了基于该数据的语意嵌入基准，证明了在游戏源码级别的结构化表示学习能够有效迁移至一般性编程语言的理解任务。这些衍生工作相互交织，共同推动了将结构规则嵌入大规模语言模型的标准化进程。