@occultus/article-api 0.24.0-beta.1 → 0.24.0-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@occultus/article-api",
-  "version": "0.24.0-beta.1",
+  "version": "0.24.0-beta.3",
   "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,35 @@ 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,
+          undefined,
+          undefined,
+          false
+        );
+        this.jumpTo(player, chapter, backTo);
+      })
+      .catch((err) => {
+        console.error(`[Article] Failed to display article: ${err}`);
+        this.quit(player, backTo as readonly FormLike[]);
+      });
   }
   /**
    * 向玩家展示文章
@@ -106,10 +120,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 +147,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, OccultusCore, OccultusSDKError } from "@occultus/core";
+import { FormLike, OccultusSDKError } from "@occultus/core";
 import { ReadableArticle } from "../types/ReadableArticle";
 
 /**
@@ -32,13 +31,13 @@ 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: ReadableArticle[] | boolean,
+    public articleSource: ReadableArticle[] | "registry" | "auto",
     public readonly bindTo?: ArticleRegistries,
     public iconPath?: string
   ) {
@@ -53,7 +52,7 @@ export class ArticleCenter extends FormLike {
       player,
       this.title,
       this.body,
-      this.getAvailableArticles()
+      this.getAvailableArticles(player)
     );
 
     if (!contentForm) {
@@ -76,9 +75,8 @@ 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!"
@@ -86,7 +84,10 @@ export class ArticleCenter extends FormLike {
       }
       return this.bindTo.getAll();
     }
-    return this.articles;
+    if (this.articleSource === "auto") {
+      return autoGetArticles(player);
+    }
+    return this.articleSource;
   }
   /**
    * 当没有可用的文章时，向玩家显示警告

package/src/api/Bindings/ArticleServerBindings.ts

@@ -1,21 +1,18 @@
-import { ItemStack, RawMessage, StartupEvent, system } from "@minecraft/server";
+import { StartupEvent, system } from "@minecraft/server";
 import { ArticleBindingConfig } from "./BindingConfig";
 import { OccultusSDKError } from "@occultus/core";
-import { parseText, TextProvider } from "@occultus/text-api";
+import { TextProvider } from "@occultus/text-api";
 import { ChapterData } from "../../interface/ChapterData";
 import { ReadableArticle } from "../../types/ReadableArticle";
-import { Article } from "../Article";
-import {
-  ArticleCenterComponentParams,
-  ArticleComponentParams,
-  ArticleContentParams
-} from "./ComponentParams";
 import { ArticleCenter } from "../ArticleCenter";
+import {
+  getArticle,
+} from "../../lib/utils";
 
 /**
  * 文章内容类型别名
  */
-type ArticleContent =
+export type ArticleContent =
   | TextProvider
   | { chapter: ChapterData[]; description: TextProvider };
 
@@ -24,32 +21,16 @@ export class ArticleServerBindings {
   private static center: ArticleCenter | undefined;
   private preloadedContent: Map<string, ArticleContent> = new Map();
   private articles: Map<string, ReadableArticle> = new Map();
-  /**
-   * 获取文章的内容
-   * @param item
-   * @param config
-   * @returns
-   */
-  private getArticleContent(item: ItemStack, config: ArticleBindingConfig) {
-    const params = item.getComponent(config.contentComponentName)
-      ?.customComponentParameters.params as ArticleContentParams;
-    if (!params) return;
-    if (typeof params === "string") {
-      return this.preloadedContent.get(params);
-    }
-    return params;
-  }
-  private 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;
+  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,
@@ -57,38 +38,14 @@ export class ArticleServerBindings {
   ) {
     const self = this;
     event.itemComponentRegistry.registerCustomComponent(config.componentName, {
-      onUse(event, componentParams) {
+      onUse(event) {
         const { itemStack, source } = event;
-        const params = componentParams.params as ArticleComponentParams;
         if (!itemStack) return;
-        // 该文章已经被注册
         if (self.articles.has(itemStack.typeId)) {
           self.articles.get(itemStack.typeId)?.display(source, []);
           return;
         }
-        // 该文章没有被注册，先注册一下
-        const content = self.getArticleContent(itemStack, config);
-        let article: ReadableArticle;
-        if (!content) return;
-        if (typeof content !== "string" && "chapter" in content) {
-          article = new Article(
-            itemStack.typeId,
-            params.title,
-            content.description,
-            content.chapter,
-            params.icon_path
-          );
-          self.articles.set(itemStack.typeId, article);
-          article.display(source, []);
-          return;
-        }
-        article = new Article(
-          itemStack.typeId,
-          params.title,
-          self.parseDescription(content),
-          undefined,
-          params.icon_path
-        );
+        const article = getArticle(itemStack);
         self.articles.set(itemStack.typeId, article);
         article.display(source, []);
       }
@@ -107,26 +64,14 @@ export class ArticleServerBindings {
     event: StartupEvent,
     config: ArticleBindingConfig
   ) {
-    const self = this;
     event.itemComponentRegistry.registerCustomComponent(
       config.centerComponentName,
       {
-        onUse(event, componentParams) {
+        onUse(event) {
           const { itemStack, source } = event;
-          const params = componentParams.params as ArticleCenterComponentParams;
           if (!itemStack) return;
           const center = ArticleServerBindings.center;
           if (!center) {
-            const newCenter = new ArticleCenter(
-              itemStack.typeId,
-              params.title,
-              params.description,
-              Array.from(self.articles.values()),
-              undefined,
-              params.icon_path
-            );
-            ArticleServerBindings.center = newCenter;
-            newCenter.display(source, []);
             return;
           }
           center.display(source, []);
@@ -141,6 +86,7 @@ export class ArticleServerBindings {
     system.beforeEvents.startup.subscribe((event) => {
       this.registryArticleComponent(event, config);
       this.registryArticleContentComponent(event, config);
+      this.initCenter(config);
       this.registryArticleCenterContent(event, config);
     });
   }
@@ -179,4 +125,15 @@ export class ArticleServerBindings {
     }
     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

@@ -1,5 +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

@@ -7,8 +7,4 @@ export type ArticleComponentParams = {
 
 export type ArticleContentParams = RawMessage[] | string;
 
-export type ArticleCenterComponentParams = {
-  title: RawMessage | string;
-  description: RawMessage | string;
-  icon_path?: string;
-};
+export type ArticleCenterComponentParams = {};

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 [];
+}