عدّة engine-kit (اختيارية)

هذه الصفحة اختيارية. كل ما هنا طريقة مريحة واحدة لـإنتاج run مطابق؛ تستطيع تجاهل العدّة كليًّا وشحن run عاريًا كتبته يدويًّا. امتدّ إلى @caputchin/engine-kit حين تؤثر كتابة منطق لعبة عاديّ وأن تُتولّى الحتمية، وحلقة إعادة التشغيل، وترميز الأثر عنك.

تعيد العدّة تصدير سطح عقد إعادة التشغيل كله، فلمستخدمي العدّة موقع استيراد واحد.

npm install @caputchin/engine-kit

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

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

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 يشغّل بطّارية حالات ويبلّغ أي عدم حتمية قبل أن تنشر:

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 خاصتك؛ تحمّل العقد وتعيد تشغيله فقط.

انظر أيضًا

• عقد إعادة التشغيل: الـ run / البذرة / الحُكم الذي تنتجه هذه العدّة.
• ابنِ لعبة المتجر: اللعبة التي تستطيع هذه العدّة دعم منطقها.
• بيان caputchin.json: شحن run المنتَج كالأداة.