ساخت و ارسال یک محیط#

یک جهان کوچک با React Three Fiber بسازید، آن را به bundle تبدیل کنید، همان بایت‌ها را در کلاینت دسکتاپ الامر باز کنید و یک revision تغییرناپذیر را برای بازبینی بفرستید. این راهنما آگاهانه نمایهٔ رسمی و اختیاری نویسندگی R3F/WebGPU را انتخاب می‌کند. این فقط یک نقطهٔ شروع پشتیبانی‌شده است، نه تعریف Environment: مرز عمومی Environment خنثی نسبت به موتور است و می‌تواند از DOM، Canvas، WebGL، WebGPU، WASM یا هر موتور وب استفاده کند.

نتیجه#

در پایان این راهنما خواهید داشت:

• یک bundle ساخته‌شدهٔ Environment با index.html در ریشه؛
• یک نسخهٔ توسعهٔ محلی که کلاینت دسکتاپ الامر باز می‌کند؛
• یک پروژه در رجیستری که به شناسهٔ مستقل و اختصاص‌یافتهٔ محیط متصل است؛
• یک revision بررسی‌شده که بایت‌های بارگذاری‌شدهٔ آن به یکپارچگی SHA-512 متصل است؛
• یک درخواست انتشار که برای بازبینی انسانی فرستاده شده است.

بازبینی انتشار یک مرحلهٔ کنترل‌شده است. alamr publish نسخهٔ بررسی‌شده را برای بازبینی می‌فرستد؛ آن را همان لحظه تأیید یا عمومی نمی‌کند.

پیش‌نیازها#

• Node.js نسخهٔ ۲۲ یا جدیدتر و npm
• کلاینت دسکتاپ الامر نصب‌شده روی ماشین توسعه
• پشتیبانی WebGPU یا WebGL2 برای نمایهٔ R3F این راهنما (سیاست پشتیبانی رندرینگ را ببینید)
• دسترسی به یک رجیستری الامر
• حساب توسعه‌دهندهٔ الامر برای login، link و انتشار

همهٔ بلوک‌های قابل کپی، فرمان کامل و نسخه‌دار npx @al-amr/cli@0.1.0-alpha.7 را نشان می‌دهند. این نسخه از بایت‌های عمومی npm می‌آید و برای ساخت، اعتبارسنجی، اتصال حساب، بارگذاری bundle و ارسال به بازبینی قابل استفاده است. پس از ساخت پروژه، نصب وابستگی‌ها و scriptهای پروژه را با package manager ثبت‌شده در package.json اجرا کنید. Context Pack رسمی تا ترفیع Release Set جداگانه مسدود است.

CLI عمومی و پروژهٔ تولیدشده به‌طور پیش‌فرض از رجیستری پروداکشن https://registry.al-amr.com استفاده می‌کنند. اگر هنگام alamr create گزینهٔ --registry <url> را بدهید یا AL_AMR_REGISTRY_URL را تنظیم کنید، رجیستری انتخاب‌شده برای ابزارهای محلی ثبت می‌شود. برای فرمان‌های بعدی نیز هنگام استفاده از استقراری غیر از پیش‌فرض، همین تنظیم CLI را نگه دارید. توسعهٔ محلی خود پلتفرم باید http://localhost:4000 را صریح انتخاب کند. هیچ دادهٔ محرمانه‌ای را در متغیرهای VITE_* نگذارید.

۱. اسکلت پروژه را بسازید#

npx @al-amr/cli@0.1.0-alpha.7 create environment my-world
cd my-world
npm install
npx @al-amr/cli@0.1.0-alpha.7 validate --json

صفحهٔ شروع، bootstrap دقیق و ترفیع‌یافتهٔ create-al-amr را برای هر package manager پشتیبانی‌شده نیز می‌دهد. پروژهٔ تولیدشده نسخه‌های واقعی بسته‌های عمومی را ثبت می‌کند و این موارد را دارد:

• al-amr.environment.json برای manifest محلی محیط؛
• AGENTS.md برای قواعد پروژه در اختیار انسان و عامل کدنویسی؛
• تنظیمات SDK که از manifest خوانده می‌شود؛
• AlAmrProvider، AlAmrRuntimeGate و بوم مربوط به R3F؛
• خروجی Vite با ریشهٔ dist/index.html؛
• public/environment-cover.jpg نسبی به bundle که داخل dist کپی می‌شود؛
• بدون وابستگی workspace:*.

اعتبارسنجی موفق کد خروج 0، مقدار ok: true و پیام environment manifest is valid. برمی‌گرداند.

وابستگی‌های تولیدشده به @al-amr/r3f و @react-three/fiber metadata محلی‌ای هستند که al-amr.r3f-webgpu@1 را انتخاب می‌کنند. آن‌ها هیچ فیلد engine یا renderer به al-amr.environment.json اضافه نمی‌کنند. یک Environment عمومی می‌تواند این markerهای نمایه را نداشته باشد و پشتهٔ وب دیگری انتخاب کند. runEnvironmentConformance عمومی قرارداد مشترک میزبان را اعتبارسنجی می‌کند؛ binding مربوط به runR3fEnvironmentConformance در این starter همان بررسی‌ها را با قواعد gate و Canvas نمایهٔ اختیاری ترکیب می‌کند.

۲. مقصد را توصیف کنید#

manifest تولیدشده از ابتدا اعلان bundle جاری است. فیلدهای نمایشی آن را ویرایش کنید و شکل entry مربوط به bundle را نگه دارید:

{
  "contractVersion": "0.1.0-alpha.7",
  "environmentId": "env_local_example",
  "name": "My World",
  "shortDescription": "A quiet three-dimensional gathering place.",
  "category": "custom",
  "entry": { "kind": "bundle", "version": "0.1.0" },
  "portal": {
    "title": "My World",
    "blurb": "Enter a quiet gathering place.",
    "art": {
      "imageUrl": "environment-cover.jpg",
      "alt": "A quiet courtyard under a green evening sky"
    },
    "visibility": "private"
  },
  "capabilities": ["identity", "presence"],
  "plugins": []
}

scaffold یک environmentId محلی و یکتا می‌سازد؛ مقدار نمونهٔ بالا را کپی نکنید. alamr link شناسهٔ محلی را با شناسهٔ پایدار اختصاص‌یافته از Registry جایگزین می‌کند. شناسهٔ Project در .al-amr/project.json هویت مدیریتی جداگانه است.

entry.version نسخه‌ای است که ناشر برای بایت‌های این bundle نام می‌گذارد؛ با انتشار بایت‌های تغییرکرده آن را افزایش دهید. entry.minClient می‌تواند به‌شکل اختیاری قدیمی‌ترین نسخهٔ سازگار کلاینت دسکتاپ را اعلام کند. entry جاری bundle هیچ URL، callback مجوز یا callback خروج ندارد: Shell دسکتاپ تنها OAuth client است و بایت‌های تأییدشده را از alamr-env://<environmentId>/ سرو می‌کند. مسیر کاور، فایلی داخل bundle است که از public/environment-cover.jpg به ریشهٔ build کپی می‌شود.

اختیاری: بک‌اند متعلق به Environment را بسازید#

اگر مقصد دادهٔ پایدار یا نقش دامنه‌ای دارد، از مسیر عمومی زیر شروع کنید:

npx @al-amr/cli@0.1.0-alpha.7 create environment my-world --with-backend

قالب، اعلان دقیق بک‌اند، درخواست Grant در frontend و verifier امن در packages/backend را می‌سازد. npm run dev هر دو سرویس را بالا می‌آورد و alamr doctor --json سلامت بک‌اند را هم می‌سنجد. Registry ادمین اولیه را از مالک Project استخراج می‌کند، اما نقش‌هایی مانند برگزارکننده و audit آن‌ها در بک‌اند Environment ذخیره می‌شوند. production به HTTPS و ذخیره‌سازی پایدار نیاز دارد.

۳. شیء نمونه را با جهان خود جایگزین کنید#

فایل تولیدشدهٔ src/App.tsx از ابتدا مرزهای رسمی Runtime و رندرینگ را دارد:

const runtimeClient = createEnvironmentRuntimeClient({ options: sdkConfig });

<EnvironmentRenderingGate
  mode={readRenderingModeOverride() ?? "auto"}
  environmentName={manifest.name}
>
  <AlAmrProvider client={runtimeClient}>
    <AlAmrRuntimeGate direction="ltr" environmentName={manifest.name}>
      <EnvironmentCanvas onFirstFrame={() => ready()}>
        <mesh castShadow position={[0, 0.7, 0]}>
          <boxGeometry args={[1.4, 1.4, 1.4]} />
          <meshStandardMaterial color="#20b875" />
        </mesh>
      </EnvironmentCanvas>
    </AlAmrRuntimeGate>
  </AlAmrProvider>
</EnvironmentRenderingGate>;

mesh را با صحنهٔ خود عوض کنید. محتوای وابسته به Runtime را داخل AlAmrRuntimeGate نگه دارید و state پایدار نشست و controllerها را بیرون Canvas بگذارید تا بازیابی renderer آن را نابود نکند. Shell دسکتاپ مالک ورود حساب است و bridge مربوط به Environment را inject می‌کند؛ bundle هیچ OAuth token، access token، ID token یا refresh token دریافت نمی‌کند. همین Shell تنها ویجت پلتفرم برای محیط فعال را هم می‌سازد؛ داخل bundle، AlAmrWidget را mount نکنید.

نمایهٔ اختیاری رندرینگ این starter از @al-amr/r3f می‌آید (ADR-0048): EnvironmentRenderingGate پیش از mountشدن حضور یا پلاگین‌ها قابلیت گرافیکی را probe می‌کند و EnvironmentCanvas مشترک، WebGPURenderer مبتنی بر WebGPU را با fallback خودکار WebGL2، یک تلاش مجدد محدود، بازیابی گم‌شدن دستگاه و صفحهٔ پشتیبانی‌نشدهٔ دوزبانه می‌سازد. مواد سفارشی را فقط با TSL (three/tsl) بنویسید — ShaderMaterial با GLSL روی renderer مبتنی بر WebGPU اجرا نمی‌شود. قرارداد کامل در زمان اجرای رندرینگ آمده است.

پیش از تماس با رجیستری، برنامه را بررسی کنید:

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

۴. پروژهٔ رجیستری را بسازید و پیوند دهید#

npx @al-amr/cli@0.1.0-alpha.7 login
npx @al-amr/cli@0.1.0-alpha.7 link
npx @al-amr/cli@0.1.0-alpha.7 validate --json

login ابزار نویسندگی CLI را احراز هویت می‌کند؛ Environment را به OAuth client تبدیل نمی‌کند. وقتی شناسهٔ Project را نمی‌دهید، link از راه API عمومی مدیریت یک پروژهٔ Environment می‌سازد. برای اتصال به پروژهٔ موجود و متعلق به خودتان، شناسهٔ proj_* آن را بدهید.

پس از پیوند، al-amr.environment.json و .al-amr/project.json را بررسی کنید. اولی شناسهٔ جدید env_* و دومی شناسهٔ جداگانهٔ proj_* و مبدأ رجیستری را در خود دارد.

۵. پروژه را بسازید و در کلاینت دسکتاپ باز کنید#

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

alamr dev به پوشهٔ build کامل با index.html در ریشه نیاز دارد. این فرمان dist را در دایرکتوری محصول توسعهٔ آزاد کلاینت دسکتاپ کپی می‌کند و یک لینک alamr://environments/<environmentId> همراه با کنش بازکردن برمی‌گرداند. آن لینک را در کلاینت نصب‌شده باز کنید. پس از تغییرات دوباره build بگیرید و alamr dev را اجرا کنید؛ این بایت‌های توسعه بیرون ledger تغییرناپذیر انتشار می‌مانند. اگر خروجی build در dist نیست، --bundle <dir> بدهید.

۶. bundle تغییرناپذیر را بارگذاری و بررسی کنید#

npm run build
npx @al-amr/cli@0.1.0-alpha.7 test --bundle dist --json --visibility unlisted --channel preview

برای Environment باندلی، alamr test یک عملیات کامل انجام می‌دهد: manifest را اعتبارسنجی می‌کند، پوشهٔ build را به‌شکل قطعی pack می‌کند، وجود سند ورودی و کاور اعلام‌شده را می‌سنجد، یکپارچگی SHA-512 را محاسبه می‌کند، revision تغییرناپذیر را می‌سازد یا دوباره به کار می‌گیرد، بایت‌ها را بارگذاری می‌کند و checks انتشار را اجرا می‌کند. این فرمان آگاهانه یک‌مرحله‌ای است: همان invocation از اعتبارسنجی محلی تا نتیجهٔ نهایی checks مالک bundle می‌ماند و هیچ مرحلهٔ جداگانهٔ نویسندگی یا تحویل frontend بیرون از این جریان وجود ندارد.

موفقیت با کد خروج 0 و پیام Publication checks completed. مشخص می‌شود. نتیجهٔ ساخت‌یافته submission، revision، چکیدهٔ snapshot، یکپارچگی bundle، سطح نمایش، کانال و نتیجهٔ بررسی‌ها را دارد. unlisted و preview برای نخستین درخواست انتخاب‌های محتاطانه‌ای هستند.

۷. bundle بررسی‌شده را برای بازبینی بفرستید#

npx @al-amr/cli@0.1.0-alpha.7 publish --json --yes
npx @al-amr/cli@0.1.0-alpha.7 status --json

درخواست موفق پیام Publication submission sent for review. می‌دهد. status وضعیت پروژه در Registry و درخواست محلی پیوندشده را برمی‌گرداند. بازبینی به snapshot منجمد manifest و یکپارچگی bundle بارگذاری‌شده متصل می‌ماند. در این جریان هیچ preview میزبانی‌شده نزد ناشر، handshake مسیر well-known یا callback OAuth متعلق به Environment وجود ندارد. revision منتشرشده تغییرناپذیر است؛ بایت‌های تغییرکرده به revision تازه و افزایش entry.version نیاز دارند.

خطاهای رایج#

• No Al-Amr manifest found — فرمان را داخل my-world اجرا کنید یا --cwd بدهید.
• No built folder with an index.html — npm run build را اجرا کنید یا مسیر واقعی خروجی را با --bundle <dir> بدهید.
• کاور bundle پیدا نمی‌شود — public/environment-cover.jpg را نگه دارید و مطمئن شوید archive ساخته‌شده مقدار portal.art.imageUrl را در مسیر نسبی به ریشه دارد.
• لینک دسکتاپ باز نمی‌شود — کلاینت دسکتاپ الامر را نصب یا اجرا کنید و سپس data.link برگشتی از alamr dev را دوباره باز کنید.
• تعارض bundle تغییرناپذیر گزارش می‌شود — entry.version را افزایش دهید، دوباره build بگیرید و alamr test را اجرا کنید؛ بایت‌های متصل به revision موجود را جایگزین نکنید.
• خطای شبکهٔ Registry — مقدار --registry و Registry ذخیره‌شده در .al-amr/project.json را بررسی کنید.
• اتصال قبلی به رجیستری دیگر — از رجیستری ثبت‌شده در .al-amr/project.json استفاده کنید یا آگاهانه پروژهٔ درست و متعلق به خود را دوباره پیوند دهید.

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

• راز کلاینت، توکن پروژه، access token، ID token یا refresh token را در کد bundle یا تنظیمات VITE_* قرار ندهید. Shell مالک احراز هویت کاربر است.
• کد اجرایی و assetهای runtime را داخل bundle نگه دارید؛ میزبان دسکتاپ CSP محصول را inject می‌کند و bundle نمی‌تواند آن را گسترش دهد.
• هر پلاگین فرانت‌اند را کد مورد اعتماد میزبان بدانید و پیش از نصب بررسی کنید.
• برای lockهای Plugin از alamr add، update و remove استفاده کنید؛ al-amr.lock.json را دستی ویرایش نکنید.

در قدم بعد پلاگین Player Rig را اضافه کنید. برای مرز بسته‌ها مرجع SDK و برای تضمین‌های احراز هویت اعتماد و امنیت را بخوانید.