@occultus/article-api 0.23.0 → 0.24.0-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@occultus/article-api",
-  "version": "0.23.0",
+  "version": "0.24.0-beta.2",
   "repository": {
     "type": "git",
     "url": "https://codeberg.org/TeamOccultus/StarTenonAPI"

package/src/api/Article.ts

@@ -10,6 +10,7 @@ import { FormLike } from "@occultus/core";
  * @since 1.0.0
  */
 export class Article extends FormLike {
+  static DYNAMIC_DATA_ID = "starock:unlocked_articles";
   /**
    * @param id 文章ID
    * @param title 文章标题
@@ -46,15 +47,18 @@ export class Article extends FormLike {
       .title(title)
       .body(body)
       .button({ translate: "gui.ok" });
-    mainForm.show(player).then((response) => {
-      if (response.canceled || response.selection === 0) {
-        this.quit(player, backTo);
-        return;
-      }
-    }).catch((err) => {
-      console.error(`[Article] Failed to display article: ${err}`);
-      this.quit(player, backTo as readonly FormLike[]);
-    });
+    mainForm
+      .show(player)
+      .then((response) => {
+        if (response.canceled || response.selection === 0) {
+          this.quit(player, backTo);
+          return;
+        }
+      })
+      .catch((err) => {
+        console.error(`[Article] Failed to display article: ${err}`);
+        this.quit(player, backTo as readonly FormLike[]);
+      });
   }
   /**
    * 向玩家展示文章（文章有章节时）
@@ -71,25 +75,28 @@ export class Article extends FormLike {
       parseText(this.body, player)
     ];
     const contentsForm = new ActionFormData().title(title).body(body);
-    this.chapters!.forEach((chapter) => {
+    this.chapters?.forEach((chapter) => {
       const chapterTitle = parseText(chapter.title, player);
       contentsForm.button(chapterTitle, chapter.iconPath);
     });
-    contentsForm.show(player).then((response) => {
-      if (response.canceled || response.selection === undefined) {
-        this.quit(player, backTo);
-        return;
-      }
-      const [chapterTitle, chapterBody] = [
-        parseText(this.chapters![response.selection].title, player),
-        parseText(this.chapters![response.selection].body, player)
-      ];
-      const chapter = new Article("temp:chapter", chapterTitle, chapterBody);
-      this.jumpTo(player, chapter, backTo);
-    }).catch((err) => {
-      console.error(`[Article] Failed to display article: ${err}`);
-      this.quit(player, backTo as readonly FormLike[]);
-    });
+    contentsForm
+      .show(player)
+      .then((response) => {
+        if (response.canceled || response.selection === undefined) {
+          this.quit(player, backTo);
+          return;
+        }
+        const [chapterTitle, chapterBody] = [
+          parseText(this.chapters![response.selection].title, player),
+          parseText(this.chapters![response.selection].body, player)
+        ];
+        const chapter = new Article("temp:chapter", chapterTitle, chapterBody);
+        this.jumpTo(player, chapter, backTo);
+      })
+      .catch((err) => {
+        console.error(`[Article] Failed to display article: ${err}`);
+        this.quit(player, backTo as readonly FormLike[]);
+      });
   }
   /**
    * 向玩家展示文章
@@ -106,10 +113,26 @@ export class Article extends FormLike {
   /**
    * 在文章中心里解锁文章
    * @param player
+   * @return `true`如果文章需要解锁，并且成功解锁；否则返回`false`
    */
-  unlock(player: Player): void {
-    if (this.needUnlock) {
-      player.addTag(`articleUnlock:${this.id}`);
+  unlock(player: Player): boolean {
+    if (!this.needUnlock || this.checkUnlock(player)) return false;
+    try {
+      const raw = player.getDynamicProperty(Article.DYNAMIC_DATA_ID);
+      let unlockedIds: string[] = [];
+      if (raw && typeof raw === "string") {
+        const parsed = JSON.parse(raw);
+        unlockedIds = Array.isArray(parsed) ? parsed : [];
+      }
+      player.setDynamicProperty(
+        Article.DYNAMIC_DATA_ID,
+        JSON.stringify([...unlockedIds, this.id])
+      );
+      return true;
+    } catch (err) {
+      console.error(`Failed to unlock article ${this.id}:`, err);
+      player.setDynamicProperty(Article.DYNAMIC_DATA_ID, "[]");
+      return false;
     }
   }
   /**
@@ -117,9 +140,16 @@ export class Article extends FormLike {
    * @param player
    */
   checkUnlock(player: Player): boolean {
-    if (this.needUnlock) {
-      return player.hasTag(`articleUnlock:${this.id}`);
+    if (!this.needUnlock) return true;
+    try {
+      const raw = player.getDynamicProperty(Article.DYNAMIC_DATA_ID);
+      if (!raw || typeof raw !== "string") return false;
+      const json = JSON.parse(raw);
+      if (!Array.isArray(json)) return false;
+      return json.includes(this.id);
+    } catch (err) {
+      console.error(`Failed to check status of article ${this.id}:`, err);
     }
-    return true;
+    return false;
   }
 }

package/src/api/ArticleCenter.ts

@@ -1,10 +1,9 @@
 import { Player } from "@minecraft/server";
 import { MessageFormData } from "@minecraft/server-ui";
 import { ArticleRegistries } from "./Base/ArticleRegistries";
-import { Article } from "./Article";
-import { generateContentForm } from "../lib/utils";
+import { autoGetArticles, generateContentForm } from "../lib/utils";
 import { TextProvider } from "@occultus/text-api";
-import { FormLike } from "@occultus/core";
+import { FormLike, OccultusSDKError } from "@occultus/core";
 import { ReadableArticle } from "../types/ReadableArticle";
 
 /**
@@ -32,14 +31,14 @@ export class ArticleCenter extends FormLike {
    * @param id 文章中心ID
    * @param title 文章中心标题
    * @param body 文章中心内容
-   * @param articles 可用的文章，如果为`true`，则会从该脚本环境注册的所有文章中显示已经解锁的文章，反之则显示无文章提示，如果为文章列表，则只从提供的文章中显示已解锁的文章
+   * @param articleSource 文章来源，如果为`true`，则会从该脚本环境注册的所有文章中显示已经解锁的文章，反之则显示无文章提示，如果为文章列表，则只从提供的文章中显示已解锁的文章
    */
   constructor(
     public readonly id: string,
     public title: TextProvider,
     public body: TextProvider,
-    public articles: Article[] | boolean,
-    public readonly bindTo: ArticleRegistries,
+    public articleSource: ReadableArticle[] | "registry" | "auto",
+    public readonly bindTo?: ArticleRegistries,
     public iconPath?: string
   ) {
     super();
@@ -53,7 +52,7 @@ export class ArticleCenter extends FormLike {
       player,
       this.title,
       this.body,
-      this.getAvailableArticles()
+      this.getAvailableArticles(player)
     );
 
     if (!contentForm) {
@@ -76,12 +75,19 @@ export class ArticleCenter extends FormLike {
         this.quit(player, backTo as readonly FormLike[]);
       });
   }
-  private getAvailableArticles(): ReadableArticle[] {
-    if (typeof this.articles === "boolean") {
-      if (!this.articles) return [];
+  private getAvailableArticles(player: Player): ReadableArticle[] {
+    if (this.articleSource === "registry") {
+      if (!this.bindTo) {
+        throw new OccultusSDKError(
+          "You must bind article registries to the center when using the boolean parameter!"
+        );
+      }
       return this.bindTo.getAll();
     }
-    return this.articles;
+    if (this.articleSource === "auto") {
+      return autoGetArticles(player);
+    }
+    return this.articleSource;
   }
   /**
    * 当没有可用的文章时，向玩家显示警告

package/src/api/Bindings/ArticleServerBindings.ts

@@ -0,0 +1,139 @@
+import { StartupEvent, system } from "@minecraft/server";
+import { ArticleBindingConfig } from "./BindingConfig";
+import { OccultusSDKError } from "@occultus/core";
+import { TextProvider } from "@occultus/text-api";
+import { ChapterData } from "../../interface/ChapterData";
+import { ReadableArticle } from "../../types/ReadableArticle";
+import { ArticleCenter } from "../ArticleCenter";
+import {
+  getArticle,
+} from "../../lib/utils";
+
+/**
+ * 文章内容类型别名
+ */
+export type ArticleContent =
+  | TextProvider
+  | { chapter: ChapterData[]; description: TextProvider };
+
+export class ArticleServerBindings {
+  private static instance: ArticleServerBindings | undefined;
+  private static center: ArticleCenter | undefined;
+  private preloadedContent: Map<string, ArticleContent> = new Map();
+  private articles: Map<string, ReadableArticle> = new Map();
+  private initCenter(config: ArticleBindingConfig) {
+    const center = new ArticleCenter(
+      "starock:bindings.article_center",
+      config.centerConfig.title,
+      config.centerConfig.description,
+      "auto",
+      undefined,
+      config.centerConfig.icon_path
+    );
+    ArticleServerBindings.center = center;
+  }
+  private registryArticleComponent(
+    event: StartupEvent,
+    config: ArticleBindingConfig
+  ) {
+    const self = this;
+    event.itemComponentRegistry.registerCustomComponent(config.componentName, {
+      onUse(event) {
+        const { itemStack, source } = event;
+        if (!itemStack) return;
+        if (self.articles.has(itemStack.typeId)) {
+          self.articles.get(itemStack.typeId)?.display(source, []);
+          return;
+        }
+        const article = getArticle(itemStack);
+        self.articles.set(itemStack.typeId, article);
+        article.display(source, []);
+      }
+    });
+  }
+  private registryArticleContentComponent(
+    event: StartupEvent,
+    config: ArticleBindingConfig
+  ) {
+    event.itemComponentRegistry.registerCustomComponent(
+      config.contentComponentName,
+      {}
+    );
+  }
+  private registryArticleCenterContent(
+    event: StartupEvent,
+    config: ArticleBindingConfig
+  ) {
+    event.itemComponentRegistry.registerCustomComponent(
+      config.centerComponentName,
+      {
+        onUse(event) {
+          const { itemStack, source } = event;
+          if (!itemStack) return;
+          const center = ArticleServerBindings.center;
+          if (!center) {
+            return;
+          }
+          center.display(source, []);
+        }
+      }
+    );
+  }
+  private constructor(public config: ArticleBindingConfig) {
+    if (!config) {
+      throw new OccultusSDKError("ArticleBindingConfig is required!");
+    }
+    system.beforeEvents.startup.subscribe((event) => {
+      this.registryArticleComponent(event, config);
+      this.registryArticleContentComponent(event, config);
+      this.initCenter(config);
+      this.registryArticleCenterContent(event, config);
+    });
+  }
+  static create(config: ArticleBindingConfig): void {
+    if (ArticleServerBindings.instance) {
+      throw new OccultusSDKError("ArticleServerBindings already created!");
+    }
+    ArticleServerBindings.instance = new ArticleServerBindings(config);
+  }
+  static getInstance(): ArticleServerBindings {
+    if (!ArticleServerBindings.instance) {
+      throw new OccultusSDKError("ArticleServerBindings not created!");
+    }
+    return ArticleServerBindings.instance;
+  }
+  static getCenter(): ArticleCenter {
+    if (!ArticleServerBindings.center) {
+      throw new OccultusSDKError("ArticleCenter not found!");
+    }
+    return ArticleServerBindings.center;
+  }
+  /**
+   * 预载文章内容
+   * @param id
+   * @param content
+   */
+  preloadContent(
+    id: string,
+    content:
+      | TextProvider
+      | { chapter: ChapterData[]; description: TextProvider }
+  ) {
+    if (!id || !content) {
+      console.warn(`Preload data failed with id: ${id}`);
+      return;
+    }
+    this.preloadedContent.set(id, content);
+  }
+  readPreloadedContent(
+    id: string
+  ):
+    | TextProvider
+    | { chapter: ChapterData[]; description: TextProvider }
+    | undefined {
+    return this.preloadedContent.get(id);
+  }
+  getArticle(id: string): ReadableArticle | undefined {
+    return this.articles.get(id);
+  }
+}

package/src/api/Bindings/BindingConfig.ts

@@ -0,0 +1,12 @@
+import { RawMessage } from "@minecraft/server";
+
+export type ArticleBindingConfig = {
+  componentName: string;
+  centerComponentName: string;
+  contentComponentName: string;
+  centerConfig: {
+    title: RawMessage | string;
+    description: RawMessage | string;
+    icon_path?: string;
+  };
+};

package/src/api/Bindings/ComponentParams.ts

@@ -0,0 +1,10 @@
+import { RawMessage } from "@minecraft/server";
+
+export type ArticleComponentParams = {
+  title: RawMessage | string;
+  icon_path?: string;
+};
+
+export type ArticleContentParams = RawMessage[] | string;
+
+export type ArticleCenterComponentParams = {};

package/src/index.ts

@@ -6,3 +6,6 @@ export * from "./api/Article";
 export * from "./api/ArticleCenter";
 export * from "./api/Base/ArticleRegistries";
 export * from "./interface/ChapterData";
+export * from "./api/Bindings/ArticleServerBindings";
+export * from "./api/Bindings/BindingConfig";
+export * from "./api/Bindings/ComponentParams";

package/src/lib/utils.ts

@@ -1,8 +1,19 @@
-import { Player, StartupEvent } from "@minecraft/server";
+import { ItemStack, Player, RawMessage, StartupEvent } from "@minecraft/server";
 import { ActionFormData } from "@minecraft/server-ui";
 import { Article } from "../api/Article";
 import { ReadableArticle } from "../types/ReadableArticle";
 import { TextProvider, parseText } from "@occultus/text-api";
+import { ArticleBindingConfig } from "../api/Bindings/BindingConfig";
+import {
+  ArticleComponentParams,
+  ArticleContentParams
+} from "../api/Bindings/ComponentParams";
+import {
+  ArticleContent,
+  ArticleServerBindings
+} from "../api/Bindings/ArticleServerBindings";
+import { ArticleCenter } from "../api/ArticleCenter";
+import { OccultusSDKError } from "@occultus/core";
 
 /**
  * 根据提供的资源生成目录表单
@@ -57,3 +68,79 @@ export function articleRegister(
     }
   });
 }
+
+export function parseDescription(
+  text: ArticleContent | RawMessage[]
+): TextProvider {
+  if (typeof text === "string") return text;
+  if (Array.isArray(text)) {
+    return {
+      rawtext: text
+    };
+  }
+  if ("description" in text) {
+    return text.description;
+  }
+  return text;
+}
+
+export function getArticleContent(item: ItemStack) {
+  const config = ArticleServerBindings.getInstance().config;
+  const params = item.getComponent(config.contentComponentName)
+    ?.customComponentParameters.params as ArticleContentParams;
+  if (!params) return;
+  if (typeof params === "string") {
+    return ArticleServerBindings.getInstance().readPreloadedContent(params);
+  }
+  return params;
+}
+
+export function getArticle(item: ItemStack): Article {
+  const config = ArticleServerBindings.getInstance().config;
+  const mainParams = item.getComponent(config.componentName)
+    ?.customComponentParameters.params as ArticleComponentParams;
+  const content = getArticleContent(item);
+  let article: Article | undefined;
+  if (!content){
+    throw new OccultusSDKError("Article content not found!");
+  }
+  if (typeof content !== "string" && "chapter" in content) {
+    article = new Article(
+      item.typeId,
+      mainParams.title,
+      content.description,
+      content.chapter,
+      mainParams.icon_path
+    );
+    return article;
+  }
+  article = new Article(
+    item.typeId,
+    mainParams.title,
+    parseDescription(content),
+    undefined,
+    mainParams.icon_path
+  );
+  return article;
+}
+
+/**
+ * 自动获得文章
+ * @param player
+ */
+export function autoGetArticles(player: Player): ReadableArticle[] {
+  try {
+    const raw = player.getDynamicProperty(Article.DYNAMIC_DATA_ID);
+    if (!raw || typeof raw !== "string") return [];
+    const json = JSON.parse(raw);
+    if (!Array.isArray(json)) return [];
+    return json.map(
+      (id: string) =>
+        ArticleServerBindings.getInstance().getArticle(id) ??
+        getArticle(new ItemStack(id))
+    );
+  } catch (e) {
+    console.error("Failed to get articles from player:" + e);
+  }
+  return [];
+}