---
type: tutorial
title: عدّة engine-kit
summary: عدّة تأليف اختيارية تنتج run إعادة تشغيل مطابقًا من مُختزِل عادي، متولّيةً الحتمية، وحلقة الخطوة الثابتة، وترميز الأثر، وفحصًا ذاتيًّا محليًّا عنك.
---

`@caputchin/engine-kit` عدّة تأليف اختيارية تحوّل مُختزِل لعبة عاديًّا إلى [`run`](/docs/marketplace-game-development/replay-contract) مطابق، متولّيةً الحتمية، وحلقة الخطوة الثابتة، وترميز الأثر عنك. إنها طريقة مريحة واحدة لإنتاج ذلك الناتج، لا شرط: تستطيع تجاهل العدّة كليًّا وشحن `run` عاريٍ كتبته يدويًّا. امتدّ إليها حين تؤثر كتابة منطق لعبة عاديّ وأن تُتولّى الحتمية، وحلقة إعادة التشغيل، وترميز الأثر عنك.

تعيد العدّة تصدير سطح [عقد إعادة التشغيل](/docs/marketplace-game-development/replay-contract) كله، فلمستخدمي العدّة موقع استيراد واحد.

```bash
npm install @caputchin/engine-kit
```

## الفكرة: اكتب مُختزِلًا، احصل على run

حركة العدّة الجوهرية أن تتيح لك التعبير عن لعبتك كـ **مُختزِل نقيّ**: دالة تأخذ الحالة الحالية ومُدخَل خطوة واحدة وتعيد الحالة التالية. من ذلك المُختزِل إضافةً إلى أوّليات حتمية، ينتج محوّل `toRun` في العدّة `run(seed, config, trace)` يطابق العقد بالبناء.

```js
import { defineEngine, toRun, cap } from "@caputchin/engine-kit";

const engine = defineEngine({
  setup(seed) {
    const rng = cap.rng(seed);          // deterministic, seeded RNG
    return { score: 0, targets: spawn(rng), rng };
  },
  tick(state, input) {
    // pure: same (state, input) always yields the same next state
    return applyInput(state, input);
  },
  result(state) {
    return { passed: state.score >= 3, score: state.score, durationMs: state.elapsed };
  },
});

export const run = toRun(engine);       // a conforming RunFn
```

## أوّليات حتمية

تعطيك العدّة الشيئين اللذين يكسران أكثر من غيرهما الحتمية عبر زمني التشغيل، كلاهما مبذور وقابل لإعادة الإنتاج:

- `cap.rng(seed)` (و`cap.rngFromState`) - مولّد PRNG قابل للبذر. استخدمه لكل خيار عشوائي بدل `Math.random()`.
- `cap.math` - متجاوزات حتمية (`sin`، و`cos`، ...) تتّفق عبر زمني التشغيل، بدل `Math` المنصّة التي قد لا تتّفق.

## أغلفة اختيارية

- `applyShim()` - يحيّد المتغيّرات العامة غير الحتمية (ساعة الحائط، و`Math.random`) كي يفشل نداء عرضيّ بصوت عالٍ في التطوير بدل التباعد بصمت عند إعادة التشغيل.
- `applyDomShim()` - DOM بلا واجهة دنيا لمسار إطار العمل، كي يظلّ مُختزِل يلمس سطح DOM صغيرًا قابلًا لإعادة التشغيل في عازل بلا DOM.

## شغّلها محليًّا قبل النشر

هيكل `replay` في العدّة يشغّل أثرًا عبر محرّكك بالطريقة نفسها التي سيشغّلها الخادم، و`selfCheck` يشغّل بطّارية حالات ويبلّغ أي عدم حتمية **قبل** أن تنشر:

```js
import { selfCheck } from "@caputchin/engine-kit";

const report = selfCheck(engine, { cases: myCases });
if (!report.ok) console.error(report.violations);
```

`selfCheck` محلّي نظيف هو أفضل مؤشّر على أن الفحص الذاتي لنشر المتجر سيجتاز (إنه معيار الحتمية نفسه). تشحن العدّة أيضًا CLI لتشغيل هذا من سكربتات `package.json` أو CI.

## ترميز الأثر

`encodeTrace` / `decodeTrace` يعطيانك هيئة أثر مدمجة مؤصدرة كي يكون تدفّق المُدخَلات الذي تبثّه لعبتك الحيّة هو بالضبط ما يفكّ `run` خاصتك ترميزه عند إعادة التشغيل. استخدامهما على الطرفين يبقي الاثنين متزامنين.

## متى تتخطّى العدّة

تخطّاها حين يكون لديك أصلًا منطق حتميّ (محاكاة فاصلة ثابتة، أو وحدة WASM مصرَّفة لفواصل-spec) أو حين تكون لعبتك بسيطةً كفايةً لتكون كتابة `run` يدويًّا تافهةً. لا تعرف المنصّة أبدًا ولا تأبه ما إذا أنتجت العدّة `run` خاصتك؛ تحمّل العقد وتعيد تشغيله فقط.

## انظر أيضًا

- [عقد إعادة التشغيل](/docs/marketplace-game-development/replay-contract): الـ `run` / البذرة / الحُكم الذي تنتجه هذه العدّة.
- [ابنِ لعبة المتجر](/docs/marketplace-game-development/build-a-marketplace-game): اللعبة التي تستطيع هذه العدّة دعم منطقها.
- [بيان caputchin.json](/docs/marketplace-game-development/the-caputchin-json-manifest#the-run-artifact): شحن `run` المنتَج كالأداة.