开源生态丨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 [email protected]: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 菜单来控制具体场景参数

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

  1. 如果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, 链接未来世界

你可能感兴趣的:(前端)