重新排布项目结构

.github/workflows/build.yml

@@ -1,7 +1,7 @@
-name: Build on Main Branch
+name: Build and Publish
 on:
   pull_request:
-    types: [ closed ]
+    types: [opened, synchronize, closed]
     branches:
       - master
       - main
@@ -10,19 +10,20 @@ on:
       - master
       - main
   workflow_dispatch:
+
+permissions:
+  contents: write
+
 jobs:
   build:
-    if: |
-      github.event_name == 'push' 
-      || (github.event_name == 'pull_request' && github.event.pull_request.merged == true)
-      || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
+    env:
+      RELEASE_BUILD: ${{ ((github.event_name == 'pull_request' && github.event.pull_request.merged == true) || github.event_name == 'workflow_dispatch') && 'true' || '' }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
-      - uses: ./.github/actions/checkout-submodules
         with:
-          token: ${{ secrets.SUBMODULE_PAT }}
+          fetch-depth: 0
       - name: Setup JDK 25
         uses: actions/setup-java@v4
         with:
@@ -36,6 +37,28 @@ jobs:
         run: |
           chmod +x gradlew
           ./gradlew build --no-daemon --build-cache
+      - name: Publish to Maven (Release)
+        if: ${{ (github.event_name == 'pull_request' && github.event.pull_request.merged == true) || github.event_name == 'workflow_dispatch' }}
+        run: |
+          ./gradlew publish --no-daemon
+        env:
+          ORG_GRADLE_PROJECT_ptcrysUsername: ${{ secrets.PTCRYS_USERNAME }}
+          ORG_GRADLE_PROJECT_ptcrysPassword: ${{ secrets.PTCRYS_PASSWORD }}
+      - name: Get version
+        id: version
+        if: ${{ (github.event_name == 'pull_request' && github.event.pull_request.merged == true) || github.event_name == 'workflow_dispatch' }}
+        run: |
+          VERSION=$(./gradlew -q properties --no-daemon 2>/dev/null | grep '^version:' | awk '{print $2}')
+          echo "value=$VERSION" >> "$GITHUB_OUTPUT"
+      - name: Create GitHub Release
+        if: ${{ (github.event_name == 'pull_request' && github.event.pull_request.merged == true) || github.event_name == 'workflow_dispatch' }}
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.version.outputs.value }}
+          name: v${{ steps.version.outputs.value }}
+          generate_release_notes: true
+          files: |
+            build/libs/*.jar
       - name: Upload artifacts
         uses: actions/upload-artifact@v4
         with:

.github/workflows/code-spoless.yml

@@ -1,21 +1,15 @@
 name: Spotless Code Format Check
 on:
-  pull_request:
   push:
-    branches: [ main, master ]
+  workflow_dispatch:
 permissions:
-  pull-requests: write
-  issues: write
   contents: read
 jobs:
   spotless:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
-      - uses: ./.github/actions/checkout-submodules
-        with:
-          token: ${{ secrets.SUBMODULE_PAT }}
       - name: Setup JDK 25
         uses: actions/setup-java@v4
         with:
@@ -29,14 +23,7 @@ jobs:
         run: |
           chmod +x gradlew
           ./gradlew spotlessCheck --no-daemon
-      - name: Comment on PR if failed
-        if: github.event_name == 'pull_request' && failure()
-        uses: actions/github-script@v7
-        with:
-          script: |
-            github.rest.issues.createComment({
-              issue_number: context.issue.number,
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              body: `❌ **代码格式化检查未通过**\n\n请运行 \`./gradlew spotlessApply\` 修复格式化后重新推送。\n\n[查看详情](https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId})`
-            });
+      - name: Format failure summary
+        if: failure()
+        run: |
+          echo "::error::Spotless 格式化检查失败，请运行 ./gradlew spotlessApply 修复后重新推送"

.github/workflows/deploy-docs.yml

@@ -72,6 +72,7 @@ jobs:
 
   publish:
     runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
     needs: build
     steps:
       - name: Checkout source

build.gradle

@@ -10,13 +10,14 @@ plugins {
 }
 
 allprojects {
-    group = 'net.phasetranscrystal'
+    group = 'net.ptcrys'
 }
 
 def buildDate = new Date()
 def dynamicVersion = "${String.format('%ty', buildDate)}.${buildDate.month + 1}.${buildDate.date}"
-ext.mod_version = dynamicVersion
-version = dynamicVersion
+def isRelease = System.getenv('RELEASE_BUILD') == 'true'
+version = isRelease ? dynamicVersion : "${dynamicVersion}-SNAPSHOT"
+ext.mod_version = version
 group = mod_group_id
 
 tasks.named('wrapper', Wrapper).configure {
@@ -73,22 +74,28 @@ publishing {
         }
     }
     repositories {
-        maven {
-            name = "reposilite"
-            // 根据版本类型选择 URL
-            def releasesRepoUrl = 'https://maven.nilarea.cn/releases'
-            def snapshotsRepoUrl = 'https://maven.nilarea.cn/snapshots'
-            url = version.endsWith('SNAPSHOT') ? snapshotsRepoUrl : releasesRepoUrl
-            // 认证信息在此配置
-            credentials {
-                username = project.findProperty('reposiliteUsername')
-                password = project.findProperty('reposilitePassword')
+        if (isRelease) {
+            maven {
+                name = "PtcrysReleases"
+                url = uri("https://maven.ptcrys.net/releases")
+                credentials {
+                    username = project.findProperty('ptcrysUsername')
+                    password = project.findProperty('ptcrysPassword')
+                }
+            }
+        } else {
+            maven {
+                name = "PtcrysSnapshots"
+                url = uri("https://maven.ptcrys.net/snapshots")
+                credentials {
+                    username = project.findProperty('ptcrysUsername')
+                    password = project.findProperty('ptcrysPassword')
+                }
             }
         }
     }
 }
 
-// IDEA不再自动下载依赖项的源码/javadoc jar，因此需要显式启用此行为。
 idea {
     module {
         downloadSources = true

dependencies.gradle

@@ -1,36 +1,26 @@
 dependencies {
     implementation "net.neoforged:neoforge:${neo_version}"
-    // Kt依赖
+
     implementation('org.jetbrains.kotlin:kotlin-stdlib:2.3.0')
     implementation("org.jetbrains.kotlin:kotlin-reflect:2.3.0")
-    // Jar内嵌
-    if (findProperty('devBuild') == "true") {
-        implementation("net.phasetranscrystal:brealib:${brealib_version}-debug")
-        implementation("net.phasetranscrystal:RegistryLib:${registry_lib_version}")
-        implementation("com.lowdragmc.ldlib2:ldlib2-neoforge-26.1:${ldlib2_version}")
-    } else {
-        jarJar(api("net.phasetranscrystal:brealib:${brealib_version}"))
-        jarJar(api("net.phasetranscrystal:RegistryLib:${registry_lib_version}"))
-        jarJar(api("com.lowdragmc.ldlib2:ldlib2-neoforge-26.1:${ldlib2_version}"))
-    }
-    // 编译时
+
+    jarJar(api("net.ptcrys:RegistryLib:${registry_lib_version}"))
+    jarJar(api("com.lowdragmc.ldlib2:ldlib2-neoforge-26.1:${ldlib2_version}"))
+
     compileOnly("dev.vfyjxf:taffy:1.1.4")// Source: https://mvnrepository.com/artifact/dev.vfyjxf/taffy
     compileOnly("org.appliedenergistics:appliedenergistics2:${ae2_version}:api")
     compileOnly("top.theillusivec4.curios:curios-neoforge:${curios_version}+26.1.2:api")
     compileOnly("mezz.jei:jei-26.1.2-neoforge-api:${jei_version}")
-    //
-    implementation("curse.maven:jade-324717:8068368")
+    implementation("curse.maven:jade-324717:8326300")
     implementation("dev.toma.configuration:configuration-neoforge:${configuration_version}+26.1.2")
-    // 运行时
+
     runtimeOnly("org.appliedenergistics:guideme:${guideme_version}")
     runtimeOnly("org.appliedenergistics:appliedenergistics2:${ae2_version}")
     runtimeOnly("top.theillusivec4.curios:curios-neoforge:${curios_version}+26.1.2")
     runtimeOnly("mezz.jei:jei-26.1.2-neoforge:${jei_version}")
-    // runtimeOnly("icyllis.modernui:ModernUI-NeoForge:26.1.2-${modern_ui_version}")
 
-    // JUnit 5
-    testImplementation 'org.junit.jupiter:junit-jupiter-api:5.10.0'
-    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.10.0'
-    testRuntimeOnly 'org.junit.platform:junit-platform-launcher:1.10.0'
-    testImplementation 'org.junit.jupiter:junit-jupiter-params:5.10.0'
+    testImplementation("org.junit.jupiter:junit-jupiter:6.0.1")
+    testImplementation("com.google.guava:guava:33.5.0-jre")
+    testImplementation("it.unimi.dsi:fastutil:8.5.18")
+    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
 }

docs/quick-start.md → docs/1-quick-start.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 1
 ---
 
 # 快速开始
@@ -8,24 +8,27 @@ sidebar_position: 2
 
 ## 环境要求
 
-| 工具        | 版本           |
-|-----------|--------------|
-| JDK       | Java 25      |
-| Gradle    | 8.x（Wrapper） |
-| Minecraft | 26.1         |
-| Mod 平台    | NeoForge     |
+| 工具      | 版本             |
+|-----------|------------------|
+| JDK       | Java 25          |
+| Gradle    | 9.6.1（Wrapper） |
+| Minecraft | 26.1.2           |
+| Mod 平台  | NeoForge         |
 
 ## 添加依赖
 
 在 DLC 模组的 `build.gradle` 中添加：
 
 ```groovy
 repositories {
-    maven { url = 'https://maven.nilarea.cn/releases' }
+    maven {
+        name = "Ptcrys Releases"
+        url = uri("https://maven.ptcrys.net/releases")
+    }
 }
-
+// build.gradle
 dependencies {
-    implementation("net.phasetranscrystal:BreakdownKernal:0.1.0")
+    implementation("net.ptcrys:BreakdownKernal:26.7.27")
 }
 ```
 
@@ -35,9 +38,9 @@ dependencies {
 
 ```
 YourDLC/
-├── src/main/java/com/yourname/dlc/
+├── src/main/java/net/ptcrys/dlcname/
 ├── src/main/resources/
-│   └── data/yourdlc/          # 数据包（配方、结构等）
+│   └── data/dlcname/
 ├── build.gradle
 └── settings.gradle
 ```
@@ -47,7 +50,6 @@ YourDLC/
 ```
 Your DLC
   └── BreakdownKernel（公开 API）
-        └── BreaLib（内置，闭源，通过 BreakdownKernel API 间接使用）
 ```
 
 DLC **只需依赖 BreakdownKernel**，不能直接依赖 BreaLib。所有底层能力通过 BreakdownKernel 的公开 API 访问。
@@ -82,5 +84,5 @@ public class YourDLC implements IBreaAddon {
 ## 下一步
 
 - [通用材料系统](material/index.md) — 定义你的材料
-- [机器系统](multiblock.md) — 创建自定义机器
-- [API 参考](api-reference.md) — 完整接口速查
+- [机器系统](machine/multiblock/index.md) — 创建自定义机器
+- [API 参考](2-api-reference.md) — 完整接口速查

docs/2-api-reference.md

@@ -0,0 +1,62 @@
+---
+sidebar_position: 2
+---
+
+# API 参考
+
+BreakdownKernel 为 DLC 模组提供稳定的核心 API。以下为各模块公开接口速查。
+
+## 模块总览
+
+| 模块      | 包路径                        | 用途                             |
+|-----------|-------------------------------|----------------------------------|
+| 材料系统  | `breakdown.api.material`      | 材料定义、元素、属性、变体       |
+| 机器系统  | `breakdown.api.machine`       | 机器定义、MetaMachine、特性      |
+| DLC 扩展  | `breakdown.api.addon`         | @BreaAddon 注解、IBreaAddon 接口 |
+| 注册系统  | `breakdown.api.registry`      | BreaRegistry、Registrate 扩展    |
+| Perk 系统 | `breakdown.api.perk`          | 实体加成、属性修改器             |
+| 事件分发  | `breakdown.api.eventdispatch` | 实体事件分发器                   |
+| 能量系统  | `breakdown.api.energy`        | 相变能量（规划中）               |
+| 世界生成  | `breakdown.api.worldgen`      | 矿石/结构生成（规划中）          |
+
+## 核心常量
+
+定义在 `BreaApi` 中：
+
+| 常量 | 值        | 说明                     |
+|------|-----------|--------------------------|
+| `M`  | 3,628,800 | 一单位材料的标准物质量   |
+| `L`  | 144       | 每材料单位的流体量（mB） |
+
+## DLC 入口
+
+```java
+
+@BreaAddon("your_mod_id")
+public class YourDLC implements IBreaAddon {
+    // getRegistrate() / initComplete() / addElement() / addMaterial() / addMaterialVariant()
+}
+```
+
+## 材料 API
+
+参见 [通用材料系统](material/index.md)。
+
+核心类：`Material`、`Element`、`MaterialAttribute`、`MaterialVariant`、`RegisterCondition`、`RegisterAction`。
+
+## 机器 API
+
+参见 [机器与多方块系统](machine/multiblock/index.md)。
+
+核心类：`MachineDefinition`、`MetaMachine`、`MachineTrait`、`IMachineFeature`。
+
+## 数据附件
+
+通过 `IMachineBlockEntity` 的 `MultiManagedStorage` 实现方块实体的自定义数据同步，支持 `@DescSynced`（客户端同步）和
+`@Persisted`（持久化）注解。
+
+## 相关页面
+
+- [快速开始](1-quick-start.md)
+- [通用材料系统](material/index.md)
+- [机器与多方块系统](machine/multiblock/index.md)

docs/world-gen.md → docs/3-world-gen.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 3
 ---
 
 # 世界生成
@@ -20,5 +20,5 @@ BreakdownKernel 的世界生成系统负责矿石放置、结构生成和生物
 
 ## 相关页面
 
-- [机器与多方块系统](multiblock.md) — 多方块结构
-- [API 参考](api-reference.md) — 世界生成 API
+- [机器与多方块系统](machine/multiblock/index.md) — 多方块结构
+- [API 参考](2-api-reference.md) — 世界生成 API