diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..6dc972ee --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +.vitepress/cache \ No newline at end of file diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts new file mode 100644 index 00000000..c3a45406 --- /dev/null +++ b/docs/.vitepress/config.mts @@ -0,0 +1,21 @@ +import { defineConfig } from 'vitepress' +import SideBarConfiguration from './sidebars/index.mjs' + +// https://vitepress.dev/reference/site-config +export default defineConfig({ + title: "KasugaLib", + description: "A universal Minecraft Forge Mod Development Framework", + themeConfig: { + // https://vitepress.dev/reference/default-theme-config + nav: [ + { text: 'Home', link: '/' }, + { text: 'Examples', link: '/markdown-examples' } + ], + + sidebar: SideBarConfiguration, + + socialLinks: [ + { icon: 'github', link: 'https://github.com/vuejs/vitepress' } + ] + } +}) diff --git a/docs/.vitepress/sidebars/guide.mts b/docs/.vitepress/sidebars/guide.mts new file mode 100644 index 00000000..42a38b90 --- /dev/null +++ b/docs/.vitepress/sidebars/guide.mts @@ -0,0 +1,29 @@ +import {DefaultTheme} from "vitepress"; +export const GuideSideBar : DefaultTheme.SidebarItem[] = [ + { + text: '起步指南', + items:[ + { + text: "介绍", + link: "/guide/" + } + ] + }, + { + text: 'Javascript Addons 开发', + items:[ + { + text: "介绍", + link: "/guide/addons/" + }, + { + text: "初始化开发环境", + link: "/guide/addons/initialization" + }, + { + text: "编写你的第一个 Addon", + } + ] + } +] +export default GuideSideBar; \ No newline at end of file diff --git a/docs/.vitepress/sidebars/index.mts b/docs/.vitepress/sidebars/index.mts new file mode 100644 index 00000000..96997dd5 --- /dev/null +++ b/docs/.vitepress/sidebars/index.mts @@ -0,0 +1,7 @@ +import {DefaultTheme} from "vitepress/theme"; +import GuideSideBar from './guide.mjs' +export const sidebars: DefaultTheme.Config['sidebar'] = { + "/guide/": GuideSideBar +} + +export default sidebars; \ No newline at end of file diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts new file mode 100644 index 00000000..def4cfc8 --- /dev/null +++ b/docs/.vitepress/theme/index.ts @@ -0,0 +1,17 @@ +// https://vitepress.dev/guide/custom-theme +import { h } from 'vue' +import type { Theme } from 'vitepress' +import DefaultTheme from 'vitepress/theme' +import './style.css' + +export default { + extends: DefaultTheme, + Layout: () => { + return h(DefaultTheme.Layout, null, { + // https://vitepress.dev/guide/extending-default-theme#layout-slots + }) + }, + enhanceApp({ app, router, siteData }) { + // ... + } +} satisfies Theme diff --git a/docs/.vitepress/theme/style.css b/docs/.vitepress/theme/style.css new file mode 100644 index 00000000..35efbc33 --- /dev/null +++ b/docs/.vitepress/theme/style.css @@ -0,0 +1,139 @@ +/** + * Customize default theme styling by overriding CSS variables: + * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css + */ + +/** + * Colors + * + * Each colors have exact same color scale system with 3 levels of solid + * colors with different brightness, and 1 soft color. + * + * - `XXX-1`: The most solid color used mainly for colored text. It must + * satisfy the contrast ratio against when used on top of `XXX-soft`. + * + * - `XXX-2`: The color used mainly for hover state of the button. + * + * - `XXX-3`: The color for solid background, such as bg color of the button. + * It must satisfy the contrast ratio with pure white (#ffffff) text on + * top of it. + * + * - `XXX-soft`: The color used for subtle background such as custom container + * or badges. It must satisfy the contrast ratio when putting `XXX-1` colors + * on top of it. + * + * The soft color must be semi transparent alpha channel. This is crucial + * because it allows adding multiple "soft" colors on top of each other + * to create a accent, such as when having inline code block inside + * custom containers. + * + * - `default`: The color used purely for subtle indication without any + * special meanings attched to it such as bg color for menu hover state. + * + * - `brand`: Used for primary brand colors, such as link text, button with + * brand theme, etc. + * + * - `tip`: Used to indicate useful information. The default theme uses the + * brand color for this by default. + * + * - `warning`: Used to indicate warning to the users. Used in custom + * container, badges, etc. + * + * - `danger`: Used to show error, or dangerous message to the users. Used + * in custom container, badges, etc. + * -------------------------------------------------------------------------- */ + + :root { + --vp-c-default-1: var(--vp-c-gray-1); + --vp-c-default-2: var(--vp-c-gray-2); + --vp-c-default-3: var(--vp-c-gray-3); + --vp-c-default-soft: var(--vp-c-gray-soft); + + --vp-c-brand-1: var(--vp-c-indigo-1); + --vp-c-brand-2: var(--vp-c-indigo-2); + --vp-c-brand-3: var(--vp-c-indigo-3); + --vp-c-brand-soft: var(--vp-c-indigo-soft); + + --vp-c-tip-1: var(--vp-c-brand-1); + --vp-c-tip-2: var(--vp-c-brand-2); + --vp-c-tip-3: var(--vp-c-brand-3); + --vp-c-tip-soft: var(--vp-c-brand-soft); + + --vp-c-warning-1: var(--vp-c-yellow-1); + --vp-c-warning-2: var(--vp-c-yellow-2); + --vp-c-warning-3: var(--vp-c-yellow-3); + --vp-c-warning-soft: var(--vp-c-yellow-soft); + + --vp-c-danger-1: var(--vp-c-red-1); + --vp-c-danger-2: var(--vp-c-red-2); + --vp-c-danger-3: var(--vp-c-red-3); + --vp-c-danger-soft: var(--vp-c-red-soft); +} + +/** + * Component: Button + * -------------------------------------------------------------------------- */ + +:root { + --vp-button-brand-border: transparent; + --vp-button-brand-text: var(--vp-c-white); + --vp-button-brand-bg: var(--vp-c-brand-3); + --vp-button-brand-hover-border: transparent; + --vp-button-brand-hover-text: var(--vp-c-white); + --vp-button-brand-hover-bg: var(--vp-c-brand-2); + --vp-button-brand-active-border: transparent; + --vp-button-brand-active-text: var(--vp-c-white); + --vp-button-brand-active-bg: var(--vp-c-brand-1); +} + +/** + * Component: Home + * -------------------------------------------------------------------------- */ + +:root { + --vp-home-hero-name-color: transparent; + --vp-home-hero-name-background: -webkit-linear-gradient( + 120deg, + #b9d959 30%, + #41d1ff + ); + + --vp-home-hero-image-background-image: linear-gradient( + -45deg, + #e9cc5d 50%, + #b9d959 50% + ); + --vp-home-hero-image-filter: blur(22px); +} + +@media (min-width: 640px) { + :root { + --vp-home-hero-image-filter: blur(44px); + } +} + +@media (min-width: 960px) { + :root { + --vp-home-hero-image-filter: blur(56px); + } +} + +/** + * Component: Custom Block + * -------------------------------------------------------------------------- */ + +:root { + --vp-custom-block-tip-border: transparent; + --vp-custom-block-tip-text: var(--vp-c-text-1); + --vp-custom-block-tip-bg: var(--vp-c-brand-soft); + --vp-custom-block-tip-code-bg: var(--vp-c-brand-soft); +} + +/** + * Component: Algolia + * -------------------------------------------------------------------------- */ + +.DocSearch { + --docsearch-primary-color: var(--vp-c-brand-1) !important; +} + diff --git a/docs/api-examples.md b/docs/api-examples.md new file mode 100644 index 00000000..6bd8bb5c --- /dev/null +++ b/docs/api-examples.md @@ -0,0 +1,49 @@ +--- +outline: deep +--- + +# Runtime API Examples + +This page demonstrates usage of some of the runtime APIs provided by VitePress. + +The main `useData()` API can be used to access site, theme, and page data for the current page. It works in both `.md` and `.vue` files: + +```md + + +## Results + +### Theme Data +
{{ theme }}
+
+### Page Data
+{{ page }}
+
+### Page Frontmatter
+{{ frontmatter }}
+```
+
+
+
+## Results
+
+### Theme Data
+{{ theme }}
+
+### Page Data
+{{ page }}
+
+### Page Frontmatter
+{{ frontmatter }}
+
+## More
+
+Check out the documentation for the [full list of runtime APIs](https://vitepress.dev/reference/runtime-api#usedata).
diff --git a/docs/guide/addons/first-addon.md b/docs/guide/addons/first-addon.md
new file mode 100644
index 00000000..11e75168
--- /dev/null
+++ b/docs/guide/addons/first-addon.md
@@ -0,0 +1,25 @@
+# 编写你的第一个 Addon
+在本节中,我们将会教你如何编写你的第一个 Addon。
+
+在上一个章节中,我们已经创建了一个新的项目目录,并且初始化了一个新的 KasugaLib 项目。
+
+接下来,我们将会创建一个简单的 Addon,这个 Addon 将会在启动时向控制台输出一段文字。
+
+```typescript
+// src/index.ts
+import { EventBus } from '@kasugalib/core';
+EventBus.on('start', () => {
+ console.log('Hello, Kasuga!');
+});
+```
+
+然后使用以下命令编译你的代码并生成一个 Addon Pack。
+
+```bash
+yarn build --pack
+```
+
+生成的 Addon Pack 将会被保存在 `build/index.zip`,将其复制到`.minecraft/addons`目录下,
+然后启动游戏,你将会在游戏日志中看到`Hello, Kasuga!`的输出。
+
+恭喜你,你已经成功编写了你的第一个 Addon!
diff --git a/docs/guide/addons/gui.md b/docs/guide/addons/gui.md
new file mode 100644
index 00000000..bfff7907
--- /dev/null
+++ b/docs/guide/addons/gui.md
@@ -0,0 +1 @@
+## 教程: 开发GUI
\ No newline at end of file
diff --git a/docs/guide/addons/index.md b/docs/guide/addons/index.md
new file mode 100644
index 00000000..01259bd2
--- /dev/null
+++ b/docs/guide/addons/index.md
@@ -0,0 +1,5 @@
+# JavaScript Addon 开发系统介绍
+为了让开发者能更加方便的为 Minecraft 增加新的功能(如GUI,模型渲染等),
+我们提供了一套具有扩展性的 JavaScript Addons 套件给开发者使用,
+通过遵循 Javascript Addons 的开发规范,您不仅能享受到快速且便捷的开发体验,
+同时您也可以调用其他 Addons 提供的 API ,实现更加丰富的功能。
\ No newline at end of file
diff --git a/docs/guide/addons/initialization.md b/docs/guide/addons/initialization.md
new file mode 100644
index 00000000..f1c2513e
--- /dev/null
+++ b/docs/guide/addons/initialization.md
@@ -0,0 +1,83 @@
+# 初始化 Javascript Addons 开发环境
+对于 Kasuga Javascript Addons,我们使用 Node JS 的 yarn(npm) 包管理器来管理项目依赖,同时使用 `package.json` 文件来描述项目的基本信息和依赖。
+
+在开始开发 Javascript Addons 之前,我们强烈建议您安装 Node JS 和 yarn 包管理器,
+在接下来的示例中,我们将使用`yarn`作为管理您的开发环境的工具,
+您可以在 [Node JS 官网](https://nodejs.org/) 下载安装 Node JS。
+
+如果您不想使用这么笨重的开发环境,我们也提供了一种轻量的方式开始您的开发,但请注意,这种方式存在一定的限制
+(如:其他 Addons 不能调用您的 Addons 提供的 API,且您无法追踪对其他接口的调用)
+
+您可以查看 [单文件Addons开发](./sfa.md) 了解更多信息。
+
+## 下载模板项目
+
+我们提供了一个模板项目,您可以直接下载并开始开发。
+
+```bash
+git clone https://github.com/KasugaLibGroup/AddonsTemplate.git
+cd AddonsTemplate
+yarn
+```
+
+## 从命令行初始化项目
+
+首先,我们需要创建一个新的项目目录,然后在项目目录中初始化一个新的 Node JS 项目。
+
+```bash
+mkdir my-addon
+cd my-addon
+yarn init
+```
+
+在初始化项目时,您需要填写一些基本信息,如项目名称,版本,描述等。
+```bash
+yarn init v1.22.10
+question name (my-addon): my-addon
+question version (1.0.0): 1.0.0
+question description: My first Kasuga Addon
+question entry point (index.js):
+question repository url:
+question author: Your Name
+question license (MIT):
+question private:
+success Saved package.json
+Done in 20.41s.
+```
+
+接着我们需要创建基本项目架构
+```bash
+mkdir src # 存储编译前的源代码文件
+mkdir lib # 存储编译后的代码文件
+mkdir client # 存储客户端代码
+mkdir server # 存储服务端代码
+mkdir assets # 存储资源文件
+mkdir dist
+mkdir dist/client # 存储客户端编译后的代码
+mkdir dist/server # 存储服务端编译后的代码
+touch src/index.ts # 创建一个入口文件
+touch client/index.ts # 创建客户端入口文件
+```
+
+然后你需要在package.json中添加一些基本的配置
+```json5
+{
+ // ... names 等信息
+ "minecraft": {
+ "server": ["server/index.js"],
+ "client": ["client/index.js"],
+ "assets": "assets/"
+ }
+}
+```
+
+## 安装依赖
+
+接着我们需要安装用于开发的基本依赖项
+```bash
+yarn add -D @kasugalib/core # 导入 KasugaLib 核心库
+# 如果您需要使用 TypeScript 开发,您还需要安装 TypeScript, ESBuild 和 TypeScript 的类型定义,并配置tsconfig.json
+yarn add -D typescript esbuild @types/node
+```
+
+并参照模板项目的`tsconfig.json`,`tsconfig.client.json`,`tsconfig.server.json`文件配置合适的TypeScript配置。
\ No newline at end of file
diff --git a/docs/guide/index.md b/docs/guide/index.md
new file mode 100644
index 00000000..87613fc8
--- /dev/null
+++ b/docs/guide/index.md
@@ -0,0 +1,6 @@
+# 介绍
+> [!CAUTION]
+> KasugaLib尚未完成编写,因此无法保证 API 的稳定性。
+>
+> **请注意,此站点上的所有内容都可能随时更改。**
+## 特性
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 00000000..0a3560ac
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,31 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+ name: "KasugaLib"
+ tagline: Base mod aiming at expediate modding
+ image:
+ src: /logo.png
+ alt: KasugaLib Logo
+ actions:
+ - theme: brand
+ text: "🚀即刻开始"
+ link: /guide/
+ - theme: alt
+ text: "📄API 文档"
+ link: /api-examples
+
+ - theme: alt
+ text: "⬇️Mod下载"
+ link: /api-examples
+
+features:
+ - title: ⚡更快的注册机制
+ details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
+ - title: 🤖GUI与Javascript运行时
+ details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
+ - title: 🚆机械动力有关功能
+ details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
+---
+
diff --git a/docs/logo.png b/docs/logo.png
new file mode 100644
index 00000000..82cb7ccc
Binary files /dev/null and b/docs/logo.png differ
diff --git a/docs/markdown-examples.md b/docs/markdown-examples.md
new file mode 100644
index 00000000..f9258a55
--- /dev/null
+++ b/docs/markdown-examples.md
@@ -0,0 +1,85 @@
+# Markdown Extension Examples
+
+This page demonstrates some of the built-in markdown extensions provided by VitePress.
+
+## Syntax Highlighting
+
+VitePress provides Syntax Highlighting powered by [Shiki](https://github.com/shikijs/shiki), with additional features like line-highlighting:
+
+**Input**
+
+````md
+```js{4}
+export default {
+ data () {
+ return {
+ msg: 'Highlighted!'
+ }
+ }
+}
+```
+````
+
+**Output**
+
+```js{4}
+export default {
+ data () {
+ return {
+ msg: 'Highlighted!'
+ }
+ }
+}
+```
+
+## Custom Containers
+
+**Input**
+
+```md
+::: info
+This is an info box.
+:::
+
+::: tip
+This is a tip.
+:::
+
+::: warning
+This is a warning.
+:::
+
+::: danger
+This is a dangerous warning.
+:::
+
+::: details
+This is a details block.
+:::
+```
+
+**Output**
+
+::: info
+This is an info box.
+:::
+
+::: tip
+This is a tip.
+:::
+
+::: warning
+This is a warning.
+:::
+
+::: danger
+This is a dangerous warning.
+:::
+
+::: details
+This is a details block.
+:::
+
+## More
+
+Check out the documentation for the [full list of markdown extensions](https://vitepress.dev/guide/markdown).
diff --git a/package.json b/package.json
index bf01cec7..3e06bc2c 100644
--- a/package.json
+++ b/package.json
@@ -8,8 +8,16 @@
"license": "MIT",
"private": true,
"scripts": {
+ "build:bootstrap": "esbuild ./lib/bootstrap/bootstrap.ts --bundle --outfile=./src/generated/resources/assets/kasuga_lib/js/bootstrap.js",
+ "build:registry": "esbuild ./lib/modules/registry.ts --bundle --outfile=./src/generated/resources/assets/kasuga_lib/js/modules/registry.js --external:kasuga:internal/registry --platform=node",
+ "docs:dev": "vitepress dev docs",
+ "docs:build": "vitepress build docs",
+ "docs:preview": "vitepress preview docs",
"build": "tsx ./lib/build.ts"
},
+ "devDependencies": {
+ "vitepress": "^1.2.3"
+ },
"devDependencies": {
"tsx": "^4.15.7",
"@types/node": "^20.14.9",