开源生态丨Sample提交指南，一起成为我们的Contributors吧！（内附彩蛋）

在《版本更新 | Orillusion 0.7版本发布啦!》的文章中，我们提到过后续会出一期独立的内容，来告诉大家如何提交自己的示例Sample代码。现在教程终于来啦！

1 一些好处

示例Sample代码相对于引擎核心代码开发相对简单，不会太多的涉及到引擎内核代码的改动，更多的是根据我们的教程文档，直接调用引擎的API来完成一些应用功能的开发。

因为我们的Sample代码也属于「Orillusion 引擎」核心库的一部分，所以一旦提交的PR被接受，就可以成为Orillusion官方开源库中的Contributors角色！

所有引擎核心库中的Sample最终都会被我们同步发布到Orillusion的官方网站中，方便大家后续的引用、分享、和传播，官网链接为：
https://www.orillusion.com/example

我们会不定期地挑选一些优秀的Sample开发者，给予一些奖品奖励，作为对Orillusion开源社区贡献的鼓励、支持、和认可！同时，也会帮助每一个示例Sample的开发者，进行社区的宣传推广活动，包括国内的社区以及国外的社区。

在优秀的开源社区和项目中留下痕迹，是我们每一位开发者的荣誉。而且也可以非常实际的提升大家的CV背景，是最直接的技术实力的体现。那后面不言而喻的加分点，大家就都懂啦！

2提交之前

在开始介绍如何成为Orillusion开源项目的Contributors之前，我们先总结下目前项目中Sample的一些基本情况。

我们的Sample出现在两个Orillusion相关的开源项目中：

1. 官网网站项目：
   https://github.com/Orillusion/orillusion-web
2. 引擎核心项目：
   https://github.com/Orillusion/orillusion

两个项目都可以进行示例Sample的提交工作。但是我们强烈建议，直接在我们的引擎核心项目中进行Sample的提交。因为，这样每一位被接受的Sample的开发者，都会出现在引擎核心项目的Contributors名单中！

这两个项目中Sample的开发方法也有些不同。

简单概括，官网项目的Sample写法更加倾向于让开发者可以通过把整个项目代码进行复制，然后粘贴到自己的开发环境中就可以直接运行，即单文件项目；而引擎核心项目中的Sample有些写法是考虑到引擎核心开发者的代码复用性，做了一些简单的封装工作，需要大家了解下封装的逻辑，再进行Sample的编写。

不过，大家在给引擎核心项目提交Sample的时候，可以使用官方网站项目中的Sample写法，也可以使用引擎核心项目中的Sample写法。后续将Sample从引擎核心项目迁移到官网网站项目的工作，会由我们Orillusion团队的成员帮大家完成的。我们会一直在云端hosting每一位Contributor用心编写的Sample，方便大家随时进行线上访问！

如果大家用官方网站中Sample写法进行PR提交，可以稍微减少一些我们的迁移工作，那当然是非常感谢啦！

3 具体方法

下面我们就开始具体讲解如何完成Orillusion项目中Sample的提交。主要分为以下几个步骤：

具体方法

下面我们就开始具体讲解如何完成Orillusion项目中Sample的提交。主要分为以下几个步骤

1. 在你的 GitHub 上 fork Orillusion项目

2. 克隆你 fork 的 repo 到本地：

   git clone [e-mail]:xxxx/orillusion.git

3. 进入项目目录并切换到 dev 分支：

   cd orillusion && git checkout dev

4. 初始化 public 子模块：

   git submodule update --init

5. 安装开发依赖：

   pnpm i

6. 运行开发服务器：

   pnpm run dev

   注意：需要 Node.js 16版本以上，以及 PNPM 7版本以上。

编写新Sample

1. 在/samples/xxx/Sample_xxx.ts的对应类别文件夹中创建新入口文件，如果没有适合的类别文件夹，可以新建一个.ts 文件，文件名应该要具有一定自解释性，要体现该Sample的功能或特点
2. 编写你的场景代码，推荐以/samples/base/Sample_Transform.ts作为模板
3. 基本代码编写规则：

->从@orillusion/core导入核心模块，例如 Engine3D, Scene3D, Object3D...

->从@orillusion/xxx导入插件/扩展，例如 @orillusion/stats, @orillusion/particle, @orillusion/physics, ...

-> 建议使用Top-level await来初始化 Engine3D 和其他异步API

-> 建议将所有functions/classes/modules嵌入到一个单一的ts文件中，方便社区分享和维护

-> 建议使用dat.gui 创建 GUI 菜单来控制具体场景参数

-> 尽可能注释代码，使代码更易阅读和理解

4. 如果Sample需要本地文件，例如gltf模型或图片，我们建议你可以将它们上传到一个公共文件托管服务，例如github pages, cloudflare CDNs, npmjs, AWS S3, Aliyun OSS等。然后在你的样例中使用公共URL来导入它们。除此之外，也可以联系我们将你的文件添加到我们的assets仓库，这样你就可以直接从/public文件夹导入文件。

创建一个PR

1. 提交你的Sample，提交时的描述内容需要遵循提交信息规范（下方链接查看详情）
   https://github.com/Orillusion/orillusion/blob/main/.github/commit-convention.md
2. 推送到自己的fork仓库
3. 从自己fork仓库的dev分支向orillsuion引擎核心项目dev分支创建一个PR，添加PR详细描述和更改记录，内容描述也应该遵循提交信息规范

Sample提交方法的这三个步骤也有总结版本，已经放到github上啦，有需要的小伙伴可以直接在github中查看：

https://github.com/Orillusion/orillusion/blob/dev/.github/contributing.md#write-new-samples

好啦，下面我们就可以开始编写自己的Sample，赶快成为Orillusion项目的核心Contributors吧！

在这个过程中，如果发现任何bug或者有其他相关的问题，我们建议在Github Issues板块中提交对应的issue，我们都会定期查看，回复和跟进的！

希望每一位3D应用的开发者和我们共同努力，一起打造属于国人自己的开源的3D引擎社区，为未来3D应用爆发时代提供底层引擎基础工具！

彩蛋来啦

社区中使用「Orillusion 引擎」开发的WebGPU游戏，又更新啦！大家都已经开始热烈讨论开发一个在线联机游戏，上班摸鱼了...

( ͡° ͜ʖ ͡°)૭✧ 摸鱼不太鼓励，但是开发是可以做的！有兴趣的小伙伴，点开关注下作者吧！

---

Orillusion致力于打造全世界第一款完全开源基于WebGPU标准的一种轻量级渲染引擎,目标是在浏览器中实现桌面级的渲染效果，支持超大复杂场景的3D呈现。易上手，易分享，易迭代，易协作、成本低，跨平台是我们的核心优势，我们将为3D场景爆发时代提供引擎基础工具。

未来我们将会持续把最干货最前沿的WebGPU技术分享给每一位社区成员，也欢迎大家为Orillusion开源社区做出自己的贡献。我们一直坚信，开源社区的技术留痕是每一位技术人员最崇高的追求！因此，我们尊重，我们认可，我们更期待，加入Orillusion，让我们共同进步！

——Link uncharted, 链接未来世界