@occultus/article-api 0.18.2

package/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2025 CTN Studios
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+# Star Tenon Article API

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@occultus/article-api",
+  "version": "0.18.2",
+  "description": "Star Tenon format tool",
+  "main": "src/index.ts",
+  "keywords": [
+    "Minecraft",
+    "Occultus SDK",
+    "Script API"
+  ],
+  "contributors": [
+    "FangLimao <mucigames@outlook.com>",
+    "RawDiamondMC <RawDiamondMC@outlook.com>"
+  ],
+  "license": "MIT",
+  "author": "CTN Studios",
+  "dependencies": {
+    "@occultus/text-api": "0.18.1"
+  },
+  "peerDependencies": {
+    "@occultus/core": ">=0.18.2 || <0.19.0",
+    "@minecraft/server": ">=2.0.0",
+    "@minecraft/server-ui": ">=2.0.0"
+  },
+  "devDependencies": {
+    "typedoc": "^0.28.9"
+  }
+}

package/src/api/Article.ts

@@ -0,0 +1,135 @@
+import { Player } from "@minecraft/server";
+import { ActionFormData } from "@minecraft/server-ui";
+import { ChapterData } from "../interface/ChapterData";
+import { BaseArticle } from "./Base/BaseArticle";
+import { parseText, TextProvider } from "@occultus/text-api";
+import { OccultusSDKError } from "@occultus/core";
+
+/**
+ * 创建一个文章
+ * @category Stable
+ * @since 1.0.0
+ */
+export class Article extends BaseArticle {
+  /**
+   * @param id 文章ID
+   * @param title 文章标题
+   * @param body 文章内容，支持字符串、RawMessage 和动态生成
+   * @param chapters 文章的章节
+   * @param iconPath 文章的图标路径
+   * @param needUnlock 是否需要解锁
+   */
+  constructor(
+    public readonly id: string,
+    public title: TextProvider,
+    public body: TextProvider,
+    public chapters?: ChapterData[],
+    public iconPath?: string,
+    public needUnlock = true
+  ) {
+    super(id, title, body, chapters);
+  }
+  /**
+   * 向玩家展示文章（文章无章节时）
+   * @param player 要展示文章的玩家
+   * @param backTo 关闭文章后返回的界面
+   * @private
+   */
+  private simpleDisplay(player: Player, backTo?: BaseArticle): void {
+    if (!this.checkUnlock(player)) {
+      this.unlock(player);
+    }
+    const title = parseText(this.title, player);
+    const body = parseText(this.body, player);
+    const mainForm = new ActionFormData()
+      .title(title)
+      .body(body)
+      .button({ translate: "gui.ok" });
+    // @ts-ignore
+    mainForm.show(player).then((response) => {
+      if (response.selection === 0 || response.canceled) {
+        backTo?.display(player);
+        return;
+      }
+    });
+  }
+  /**
+   * 向玩家展示文章（文章有章节时）
+   * @param player 要展示文章的玩家
+   * @param backTo 关闭文章后返回的界面
+   * @private
+   */
+  private chapterDisplay(player: Player, backTo?: BaseArticle): void {
+    if (!this.checkUnlock(player)) {
+      this.unlock(player);
+    }
+    const [title, body] = [
+      parseText(this.title, player),
+      parseText(this.body, player),
+    ];
+    const contentsForm = new ActionFormData().title(title).body(body);
+    if (!this.chapters) {
+      throw new OccultusSDKError("Cannot find chapter data!");
+    }
+    this.chapters.forEach((chapter) => {
+      const chapterTitle = parseText(chapter.title, player);
+      contentsForm.button(chapterTitle, chapter.iconPath);
+    });
+    // @ts-ignore
+    contentsForm.show(player).then((response) => {
+      if (response.canceled || response.selection === undefined) {
+        backTo?.display(player);
+        return;
+      }
+      if (!this.chapters) {
+        throw new OccultusSDKError("Invaild chapter data!");
+      }
+      const [chapterTitle, chapterBody] = [
+        parseText(this.chapters[response.selection].title, player),
+        parseText(this.chapters[response.selection].body, player),
+      ];
+
+      const chapterForm = new ActionFormData()
+        .title(chapterTitle)
+        .body(chapterBody)
+        .button({ translate: "gui.ok" });
+      // @ts-ignore
+      chapterForm.show(player).then((response) => {
+        if (response.selection === 0 || response.canceled) {
+          // @ts-ignore
+          contentsForm.show(player);
+          return;
+        }
+      });
+    });
+  }
+  /**
+   * 向玩家展示文章
+   * @param player 要展示文章的玩家
+   * @param backTo 关闭文章后返回的界面
+   */
+  display(player: Player, backTo?: BaseArticle): void {
+    if (this.chapters) {
+      this.chapterDisplay(player, backTo);
+      return;
+    }
+    this.simpleDisplay(player, backTo);
+  }
+  /**
+   * 在文章中心里解锁文章
+   * @param player
+   */
+  unlock(player: Player): void {
+    player.addTag(`articleUnlock:${this.id}`);
+  }
+  /**
+   * 检查文章是否在文章中心里解锁
+   * @param player
+   */
+  checkUnlock(player: Player): boolean {
+    if (this.needUnlock) {
+      return player.hasTag(`articleUnlock:${this.id}`);
+    }
+    return true;
+  }
+}

package/src/api/ArticleCenter.ts

@@ -0,0 +1,111 @@
+import { Player } from "@minecraft/server";
+import { MessageFormData } from "@minecraft/server-ui";
+import { ArticleRegistries } from "./Base/ArticleRegistries";
+import { Article } from "./Article";
+import { BaseArticle } from "./Base/BaseArticle";
+import { generateContentForm } from "../lib/utils";
+import { TextProvider } from "@occultus/text-api";
+
+/**
+ * 集中显示文章的类
+ *
+ * 核心功能包括：
+ * - 显示文章列表给玩家
+ * - 处理文章的解锁和显示
+ *
+ * 注意：
+ * - 如果`articles`参数为布尔值，如果为`true`，则会从该脚本环境注册的所有文章中显示已经解锁的文章，反之则显示无文章提示
+ * - 如果`articles`参数为文章列表，则只从提供的文章中显示已解锁的文章
+ *
+ * @example
+ * const articleCenter = new ArticleCenter("article:id", title, body, true);
+ * articleCenter.display(player); // 显示文章中心给玩家
+ * articleCenter.subscribeEvent("itemId"); // 注册文章事件
+ * articleCenter.registryComponent("componentName"); // 注册自定义组件
+ *
+ * @category Stable
+ * @since 1.0.0
+ */
+
+
+export class ArticleCenter extends BaseArticle {
+  /**
+   * @param id 文章中心ID
+   * @param title 文章中心标题
+   * @param body 文章中心内容
+   * @param articles 可用的文章，如果为`true`，则会从该脚本环境注册的所有文章中显示已经解锁的文章，反之则显示无文章提示，如果为文章列表，则只从提供的文章中显示已解锁的文章
+   */
+  constructor(
+    public readonly id: string,
+    public title: TextProvider,
+    public body: TextProvider,
+    public articles: Article[] | boolean,
+    public readonly articlesManager: ArticleRegistries,
+    public iconPath?: string
+  ) {
+    super(id, title, body, articles);
+  }
+  /**
+   * 向玩家展示文章中心
+   * @param player 要展示文章中心的玩家
+   */
+  display(player: Player): void {
+    if (typeof this.articles === "boolean") {
+      if (!this.articles) {
+        this.warn(player);
+        return;
+      }
+      const contentForm = generateContentForm(
+        player,
+        this.title,
+        this.body,
+        this.articlesManager.getAll()
+      );
+      if (!contentForm) {
+        this.warn(player);
+        return;
+      }
+      // @ts-ignore
+      contentForm.form.show(player).then((response) => {
+        if (response.canceled || response.selection === undefined) {
+          return;
+        }
+        contentForm.list[response.selection].display(player, this);
+      });
+      return;
+    }
+    const contentForm = generateContentForm(
+      player,
+      this.title,
+      this.body,
+      this.articles
+    );
+    if (!contentForm) {
+      this.warn(player);
+      return;
+    }
+    // @ts-ignore
+    contentForm.form.show(player).then((response) => {
+      if (response.canceled || response.selection === undefined) {
+        return;
+      }
+      contentForm.list[response.selection].display(player, this);
+    });
+  }
+  /**
+   * 当没有可用的文章时，向玩家显示警告
+   * @param player 被显示提示的玩家
+   * @private
+   */
+  private warn(player: Player): void {
+    const warningForm = new MessageFormData()
+      .title({ translate: "article.nothing.title" })
+      .body({ translate: "article.nothing.body" })
+      .button1({ translate: "gui.ok" })
+      .button2({ translate: "gui.close" });
+    // @ts-ignore
+    warningForm.show(player).then((_response) => {
+      return;
+    });
+  }
+}

package/src/api/Base/ArticleRegistries.ts

@@ -0,0 +1,65 @@
+import { Registries } from "@occultus/core";
+import { Article } from "../Article";
+import { BaseArticle } from "./BaseArticle";
+import { articleRegister } from "../../lib/utils";
+import { ArticleCenter } from "../ArticleCenter";
+import { ReadableArticle } from "../../types/ReadableArticle";
+import { system } from "@minecraft/server";
+
+/**
+ * 管理文章数据的类
+ *
+ * 该类提供了获取所有文章和文章ID列表的方法，以及根据ID获取特定文章的功能。
+ *
+ * @category Stable
+ * @since 1.0.0
+ */
+export class ArticleRegistries extends Registries {
+  id = "ArticleRegistries";
+  /**
+   * @category Internal
+   * @since 1.0.0
+   */
+  private registry: Map<string, Article | ArticleCenter> = new Map();
+
+  add(value: ReadableArticle | ReadableArticle[]): void {
+    if (Array.isArray(value)) {
+      value.forEach((article) => this.add(article));
+      return;
+    }
+    this.registry.set(value.id, value);
+  }
+  register(): void {
+    system.beforeEvents.startup.subscribe((arg) => {
+      this.registry.forEach((article) => {
+        articleRegister(article.id, article, arg);
+      });
+    });
+  }
+  delete(id: string) {
+    return this.registry.delete(id);
+  }
+  /**
+   * 获取该注册表下所有文章
+   * @returns 一个包含该注册表下所有文章的数组
+   */
+  getAll() {
+    return Array.from(this.registry.values());
+  }
+  /**
+   * 根据文章ID获取文章
+   * @param id 文章ID
+   * @return 返回找到的文章，如果没有找到则返回`undefined`
+   */
+  get(id: string): undefined | BaseArticle {
+    return this.registry.get(id);
+  }
+  /**
+   * 判断注册表中是否含有某一特定文章
+   * @param id 文章的 ID
+   * @return 如果含有该文章，则返回`true`，否则返回`false`
+   */
+  has(id: string): boolean {
+    return this.registry.has(id);
+  }
+}

package/src/api/Base/BaseArticle.ts

@@ -0,0 +1,26 @@
+import { Player } from "@minecraft/server";
+import { TextProvider } from "@occultus/text-api";
+
+/**
+ * 描述文章的抽象类
+ */
+export abstract class BaseArticle {
+  /**
+   * @param id 文章的唯一标识符
+   * @param title 文章的标题
+   * @param body 文章的内容
+   * @param data 文章的其他数据
+   */
+  constructor(
+    public readonly id: string,
+    public title: TextProvider,
+    public body: TextProvider,
+    public data: unknown
+  ) {}
+  /**
+   * 向玩家展示文章
+   * @param player 要展示文章的玩家
+   * @param backTo 展示后返回的界面
+   */
+  abstract display(player: Player, backTo?: BaseArticle): void;
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./lib/utils";
+export * from "./api/Article";
+export * from "./api/ArticleCenter";
+export * from "./api/Base/ArticleRegistries";
+export * from "./api/Base/BaseArticle";
+export * from "./interface/ChapterData";

package/src/interface/ChapterData.ts

@@ -0,0 +1,20 @@
+import { TextProvider } from "@occultus/text-api";
+
+
+/**
+ * 描述文章的章节数据的接口
+ */
+export interface ChapterData {
+  /**
+   * 章节标题
+   */
+  title: TextProvider;
+  /**
+   * 章节内容
+   */
+  body: TextProvider;
+  /**
+   * 章节图标路径
+   */
+  iconPath?: string;
+}

package/src/lib/utils.ts

@@ -0,0 +1,67 @@
+import {
+  Player,
+  RawMessage,
+  StartupEvent,
+  system,
+  world,
+} from "@minecraft/server";
+import { ActionFormData } from "@minecraft/server-ui";
+import { Article } from "../api/Article";
+import { BaseArticle } from "../api/Base/BaseArticle";
+import { ReadableArticle } from "../types/ReadableArticle";
+import { TextProvider, parseText } from "@occultus/text-api";
+
+/**
+ * 根据提供的资源生成目录表单
+ * @param player
+ * @param rawTitle
+ * @param rawBody
+ * @param articles
+ * @returns
+ * @category Internal
+ * @since 1.0.0
+ */
+export function generateContentForm(
+  player: Player,
+  rawTitle: TextProvider,
+  rawBody: TextProvider,
+  articles: ReadableArticle[]
+): { form: ActionFormData; list: ReadableArticle[] } | undefined {
+  const unlockedArticles: ReadableArticle[] = [];
+  const [title, body] = [
+    parseText(rawTitle, player),
+    parseText(rawBody, player),
+  ];
+  const contentForm = new ActionFormData().title(title).body(body);
+  articles.forEach((article) => {
+    if (article instanceof Article) {
+      if (!article.checkUnlock(player)) {
+        return;
+      }
+      const title = parseText(article.title, player);
+      contentForm.button(title, article.iconPath);
+      unlockedArticles.push(article);
+      return;
+    }
+    const title = parseText(article.title, player);
+    contentForm.button(title, article.iconPath);
+    unlockedArticles.push(article);
+  });
+  if (unlockedArticles.length === 0) {
+    return;
+  }
+  return { form: contentForm, list: unlockedArticles };
+}
+
+export function articleRegister(
+  componentId: string,
+  article: BaseArticle,
+  arg: StartupEvent
+) {
+  arg.itemComponentRegistry.registerCustomComponent(componentId, {
+    onUse: (callback) => {
+      article.display(callback.source);
+    },
+  });
+}
+

package/src/types/ReadableArticle.ts

@@ -0,0 +1,7 @@
+import { Article } from "../api/Article";
+import { ArticleCenter } from "../api/ArticleCenter";
+
+/**
+ * 所有可读文章类型
+ */
+export type ReadableArticle = Article | ArticleCenter;

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "include": ["src/*"],
+  "exclude": ["./out"],
+  "Modules": {
+    "resolvePackageJsonExports": true
+  },
+  "compilerOptions": {
+    "noEmit": true,
+    "noEmitOnError": true,
+    "target": "es2022",
+    "lib": ["es2020", "dom"],
+    "strict": true,
+    "esModuleInterop": true,
+    "module": "es2022",
+    "moduleResolution": "bundler",
+    "outDir": ".",
+    "removeComments": true,
+    "newLine": "lf",
+    "resolveJsonModule": true
+  }
+}