افزودن و بررسی یک پلاگین#

پلاگین بررسی‌شدهٔ Player Rig را در یک محیط موجود نصب کنید، آداپتر عمومی React Three Fiber آن را نمایش دهید و یک بازبینی تغییرناپذیر تازه از محیط را همراه همین نصب دقیق برای بررسی بفرستید.

نتیجه#

در پایان:

• manifest محیط، نسخهٔ دقیق انتشار پلاگین و آداپتر r3f را مشخص می‌کند؛
• al-amr.lock.json انتشار رجیستری، artifact بسته و صحت SHA-512 را ثبت می‌کند؛
• package.json شامل بستهٔ انتخاب‌شده است؛
• ریگ بازیکنِ قابل حرکت از راه آداپتر عمومی بررسی‌شده نمایش داده می‌شود؛
• بازبینی تازهٔ محیط بررسی‌های انتشار را گذرانده و آمادهٔ ارسال برای بازبینی است.

پیش‌نیازها#

• تکمیل و پیوند راهنمای Environment
• تنظیم یک رجیستری یکسان برای CLI و محیط در حال اجرا
• وجود نسخهٔ منتشرشدهٔ al-amr/player-rig در کاتالوگ همان رجیستری
• نصب بودن وابستگی‌های npm

همهٔ بلوک‌های قابل کپی، فرمان کامل و نسخه‌دار npx @al-amr/cli@0.1.0-alpha.7 را نشان می‌دهند. نصب یک Plugin مدیریت‌شده به نسخه‌ای وابسته است که Release Set ترفیع‌یافته اعلام می‌کند؛ اگر صفحهٔ Start فرمان نصب دقیق نشان نمی‌دهد، نسخه‌ای حدس نزنید. برای نصب dependencyها از package manager ثبت‌شده در package.json محیط استفاده کنید.

همهٔ فرمان‌ها را از پوشهٔ Environment اجرا کنید. al-amr.lock.json را دستی نسازید یا ویرایش نکنید.

۱. انتشار تغییرناپذیر را بررسی کنید#

npx @al-amr/cli@0.1.0-alpha.7 inspect al-amr/player-rig --json

نتیجه شامل کارت عمومی، manifest دقیق، نسخه‌های موجود، artifactهای قابل نصب، شناسهٔ تغییرناپذیر انتشار، نشانی راهنمای یکپارچه‌سازی و محیط‌های مصرف‌کنندهٔ پلاگین است. پیش از نصب بررسی کنید:

• runtimeClass برابر trusted_library باشد؛
• آداپتر r3f وجود داشته باشد و exportهای موردنیاز را اعلام کند؛
• سازگاری قرارداد و SDK با محیط یکسان باشد؛
• مجوزهای پلتفرم به نیاز واقعی پلاگین محدود باشند؛
• نیازهای مرورگر، دسترسی شبکه، شیوهٔ استفاده از داده و مجوز نرم‌افزار پذیرفتنی باشند؛
• artifact انتخاب‌شده صحت اعتبارسنجی‌شدهٔ رجیستری داشته باشد.

صفحهٔ canonical برابر https://developer.al-amr.com/plugins/al-amr/player-rig است. صفحهٔ نسخه و integration.md آن پس از انتشار تغییرناپذیرند.

۲. آداپتر انتخاب‌شده را اضافه و بایت‌ها را نصب کنید#

npx @al-amr/cli@0.1.0-alpha.7 add al-amr/player-rig@0.3.0-alpha.5 --adapter r3f --dry-run --json
npx @al-amr/cli@0.1.0-alpha.7 add al-amr/player-rig@0.3.0-alpha.5 --adapter r3f --yes --json
pnpm install
npx @al-amr/cli@0.1.0-alpha.7 validate --json

اجرای آزمایشی مرز اعتماد است. تأیید ناشر، هویت انتشار و artifact، کلاس runtime، مجوزها، اعلان‌های مرورگر/شبکه/داده، exportهای آداپتر، صحت و filesToChange را بررسی کنید. اجرای آزمایشی چیزی نمی‌نویسد. فرمان دوم همان ورودی‌های بررسی‌شده را تأیید می‌کند.

CLI یک به‌روزرسانی اتمیک metadata را در این فایل‌ها انجام می‌دهد:

• al-amr.environment.json که pluginId، releaseVersion و adapterId را ثبت می‌کند؛
• al-amr.lock.json که releaseId، artifactId، مشخصات بسته و صحت را می‌افزاید؛
• package.json که بستهٔ دقیق قابل نصب را اضافه می‌کند.

گزینهٔ --yes لازم است چون بایت‌های پلاگین frontend به‌صورت کد trusted library اجرا می‌شوند. این گزینه جایگزینی عمدی نسخهٔ قفل‌شدهٔ فعلی را هم اجازه می‌دهد، اما اعتبارسنجی رجیستری، صحت artifact، سازگاری یا بازبینی انتشار را دور نمی‌زند.

فرمان موفق پیام Added al-amr/player-rig@... می‌دهد و نسخه، آداپتر، نام بستهٔ بررسی‌شدهٔ رجیستری، صحت، نشانی canonical و فرمان نصب را برمی‌گرداند. data.packageName را specifier واردسازی در نظر بگیرید و دقیقاً فرمان data.installCommand را اجرا کنید. نام بسته را از نام workspace منبع حدس نزنید. اعتبارسنجی محلی پس از نصب همچنان باید با کد فرایند 0 تمام شود.

۳. Player Rig را از راه آداپتر انتخاب‌شده نمایش دهید#

برای این انتشار first-party، مقدار data.packageName برابر @al-amr-community/al-amr--player-rig است. فقط exportهای اعلام‌شده توسط آداپتر بررسی‌شدهٔ r3f را وارد و داخل canvas مشترک R3F نمایش دهید:

import { AlAmrProvider, AlAmrRuntimeGate } from "@al-amr/react";
import { createEnvironmentRuntimeClient } from "@al-amr/sdk";
import { EnvironmentCanvas } from "@al-amr/r3f/canvas";
import {
  PlayerRig,
  createFlatNavigationSurface,
  createPlayerController,
} from "@al-amr-community/al-amr--player-rig";
import { sdkConfig } from "./config.js";

// The controller and navigation surface live outside the canvas so a
// renderer retry or device-loss recovery never resets the player.
const controller = createPlayerController({ position: [0, 0, 6] });
const navigation = createFlatNavigationSurface(0);

// The platform this build talks to. The desktop client supplies `window.alamr`;
// `alamr dev` installs the loose build and returns the exact client link.
const runtimeClient = createEnvironmentRuntimeClient({ options: sdkConfig });

export function App() {
  return (
    <AlAmrProvider client={runtimeClient}>
      <AlAmrRuntimeGate direction="ltr">
        <EnvironmentCanvas controls={false}>
          <PlayerRig controller={controller} navigation={navigation} />
        </EnvironmentCanvas>
      </AlAmrRuntimeGate>
    </AlAmrProvider>
  );
}

محیط همچنان مالک terrain، مرجع برخورد و سیاست spawn است و NavigationSurface مورد پرس‌وجوی ریگ را تأمین می‌کند. Player Rig مالک حرکت، دوربین، نمایش آواتار و آداپتر رندر بررسی‌شدهٔ خودش است. controls={false} را بگذارید تا دوربین ریگ تنها دوربین فعال بماند. AlAmrRuntimeGate وقتی صفحه lease فعال Runtime را از دست بدهد جهان را unmount می‌کند. Shell دسکتاپ مالک تنها ویجت پلتفرم است؛ Environment نباید ویجت دیگری mount کند.

۴. یکپارچه‌سازی محلی را بررسی کنید#

npm run typecheck
npm run build
npx @al-amr/cli@0.1.0-alpha.7 inspect --json
npx @al-amr/cli@0.1.0-alpha.7 validate --json
npx @al-amr/cli@0.1.0-alpha.7 dev --json

خروجی inspect محلی باید نصب Player Rig را با انتشار انتخاب‌شده و آداپتر r3f نشان دهد. اعتبارسنجی همچنین تطابق هر نصب محیط با ورودی lock را بررسی می‌کند.

next action با نام open را که alamr dev برمی‌گرداند اجرا کنید. در client دسکتاپ تأیید کنید آواتار نمایش داده می‌شود و حرکت WASD و چرخش دوربین داخل canvas محیط پاسخ می‌دهند.

۵. بازبینی تازهٔ محیط را بررسی و ارسال کنید#

npx @al-amr/cli@0.1.0-alpha.7 test --bundle dist --json --visibility unlisted --channel preview
npx @al-amr/cli@0.1.0-alpha.7 publish --json --yes
npx @al-amr/cli@0.1.0-alpha.7 status --json

test بایت‌های دقیق dist را inventory، pack، upload، bind و بررسی می‌کند؛ از جمله digest تازهٔ manifest، نصب دقیق Plugin و نسخهٔ SDK. publish همان revision بررسی‌شده را برای review می‌فرستد. Registry منبع حقیقت زمان و وضعیت انتشار revision باقی می‌ماند.

خطاهای رایج#

• Plugin not found یا کد شبکهٔ 4 — مطمئن شوید رجیستری CLI شامل al-amr/player-rig است.
• آداپتر r3f ارائه نشده — انتشار را بررسی و یکی از آداپترهای اعلام‌شده را انتخاب کنید.
• انتشار yanked شده — یک نسخهٔ منتشرشدهٔ فعلی انتخاب کنید؛ نصب‌های قفل‌شدهٔ قدیمی بازتولیدپذیر می‌مانند.
• تعارض وابستگی — ورودی موجود package.json را بررسی و فقط برای جایگزینی عمدی --yes بدهید.
• ورودی lock گم یا قدیمی است — alamr add را برای نسخهٔ موردنظر دوباره اجرا کنید و lock را دستی تعمیر نکنید.
• TypeScript export را پیدا نمی‌کند — exportPath و exportهای نام‌دار را با types.d.ts نسخه مقایسه کنید.
• چیزی نمایش داده نمی‌شود یا بازیکن سقوط می‌کند — مؤلفه را داخل EnvironmentCanvas نگه دارید، از سطح ناوبری نقطهٔ زمین محدود برگردانید و کنترل‌های خود canvas را خاموش کنید تا با دوربین ریگ درگیر نشوند.

چک‌لیست امنیت#

• پلاگین frontend در v0.x کد trusted library در قلمرو JavaScript محیط است؛ مجوزها sandbox نیستند.
• پیش از افزودن، نسخهٔ دقیق، اعلان‌ها، منبع و صحت را بررسی کنید.
• فقط exportهای اعلام‌شدهٔ آداپتر و تعریف نوع بررسی‌شده را وارد کنید.
• هیچ توکن مدیریت یا راز مرورگر را به کد پلاگین ندهید.
• در صورت نیاز al-amr.lock.json را در کنترل منبع نگه دارید، ولی فیلدهای صحت و هویت را دستی ویرایش نکنید.

برای ساخت قابلیت قابل استفادهٔ مجدد خودتان سراغ ساخت پلاگین بروید. مرز دقیق فایل‌ها در مرجع Manifest آمده است.