دليل · أساسيات البرمجة

TweenService في Roblox: نحرّك القطع وندوّرها ونخفيها

الـ Tween يغيّر خاصية بسلاسة من قيمتها الحالية إلى الهدف خلال وقت محدد: منصة تنزلق، وبلورة تدور، وجدار يتلاشى. يحسب TweenService الخطوات الوسيطة بنفسه، فلا تحتاج إلى كتابة حلقة تحرّك القطعة في كل إطار. في هذا الدليل: الأسطر الثلاثة التي لا يستغني عنها أي Tween، وما تفعله كل إعدادات TweenInfo، وتحريك القطع وتدويرها وإخفاؤها، والتكرار، وانتظار نهاية الـ Tween، وطريقة تحريك نموذج كامل (Model).

آخر تحديث ٢٠ نوفمبر ٢٠٢٦القراءة في 5 دبقلم

باختصار

احصل على الخدمة عبر game:GetService("TweenService")، وصِف الحركة عبر TweenInfo.new(time, easingStyle, easingDirection)، ثم استدعِ TweenService:Create(part, info, { Position = goal }) وشغّل :Play() على الـ Tween الناتج. يمكنك تحريك أي خاصية من نوع number وVector3 وCFrame وColor3 وUDim2 وما يشبهها. لتنتظر النهاية استخدم tween.Completed:Wait()، وللحركة ذهابًا وإيابًا بلا نهاية اجعل عدد التكرار في TweenInfo يساوي -1 وفعّل reverses.

  • شغّل الـ Tween على القطعة في الخادم عندما يجب أن يراها كل اللاعبين، وفي العميل عندما يكون التأثير لهذا اللاعب وحده.
  • ثبّت (Anchored) القطع التي تحرّكها بـ Tween، وإلا فستعرقل الفيزياء الحركة.
  • ليس لدى Model خاصية Position أو CFrame قابلة للتحريك: حرّك NumberValue وانقل النموذج عبر PivotTo.
في هذه الصفحة
  1. طريقة العمل
  2. 1. TweenInfo
  3. 2. التدوير والتلاشي
  4. 3. التكرار
  5. 4. النماذج
  6. الخادم أم العميل
  7. Common errors
  8. مع RoCode
  9. الأسئلة الشائعة
  10. المصادر والقراءات

ثلاثة أسطر يحتاجها كل Tween

أدرج Part في Workspace، وفعّل Anchored، ثم مرّر المؤشر فوقها واضغط + وأدرج Script. هذا السكربت يرفع القطعة 10 ستد خلال ثانيتين:

Script في قطعة في Workspace باسم Rise
-- Script داخل Part.
local TweenService = game:GetService("TweenService")

local part = script.Parent :: BasePart

local info = TweenInfo.new(2) -- ثانيتان، والـ easing الافتراضي
local goal = { Position = part.Position + Vector3.new(0, 10, 0) }

local tween = TweenService:Create(part, info, goal)
tween:Play()

الهدف جدول من أسماء الخصائص والقيم التي يجب أن تنتهي إليها. يمكنك تحريك عدة خصائص معًا: { Position = ..., Transparency = 1, Color = Color3.fromRGB(255, 0, 0) }. يبدأ الـ Tween من القيم الموجودة لحظة استدعاء Play، لذلك تحدد النهاية فقط دائمًا.

ما يمكن تحريكه بـ Tween وما لا يمكن
النوعهل يتحرك بسلاسة؟أمثلة
numberنعمTransparency وReflectance وValue في NumberValue
Vector3, CFrameنعمPosition وSize وCFrame وOrientation
Color3نعمColor
UDim2, Vector2نعمSize وPosition في عناصر GUI
boolean, EnumItemيتبدّل في النهايةCanCollide وMaterial
string, Instanceلايعطي الخطأ cannot be tweened due to type mismatch

الخطوة 1: كل إعدادات TweenInfo

يقبل TweenInfo.new حتى ست قيم بهذا الترتيب. ويمكنك ترك القيم الأخيرة.

TweenInfo.new(time, style, direction, repeatCount, reverses, delayTime)
القيمةالافتراضيماذا تفعل
time1عدد الثواني لتشغيلة واحدة.
easingStyleQuadشكل الحركة: Linear (سرعة ثابتة)، وSine، وQuad، وCubic، وBack (مع تجاوز للهدف)، وBounce، وElastic، وExponential.
easingDirectionOutOut يبدأ سريعًا ثم يتباطأ، وIn يبدأ ببطء، وInOut يجمع الاثنين.
repeatCount0كم مرة تتكرر بعد التشغيلة الأولى. القيمة -1 تكرر بلا نهاية.
reversesfalseالعودة إلى البداية بعد كل تشغيلة.
delayTime0عدد الثواني قبل البدء.
Script في قطعة في Workspace باسم Platform
-- Script داخل Part باسم Platform.
-- يتحرك ذهابًا وإيابًا 12 ستد بلا نهاية، بسلاسة عند الطرفين.
local TweenService = game:GetService("TweenService")

local platform = script.Parent :: BasePart

local info = TweenInfo.new(
	3, -- الثواني في كل اتجاه
	Enum.EasingStyle.Sine,
	Enum.EasingDirection.InOut,
	-1, -- التكرار بلا نهاية
	true -- العودة كل مرة
)

TweenService:Create(platform, info, { Position = platform.Position + Vector3.new(12, 0, 0) }):Play()

إذا كان يجب أن تحمل المنصة اللاعبين الواقفين عليها فانتبه: القطعة المثبتة المتحركة بـ Tween تتحرك تحتهم لكنها لا تأخذهم معها. هذه الحالة مشروحة في دليل المنصة المتحركة.

الخطوة 2: التدوير والحجم والتلاشي

لتدوير قطعة، حرّك CFrame نحو الـ CFrame الحالي مضروبًا في دوران. يعمل تحريك Orientation أيضًا، لكن مع CFrame تدور القطعة في مكانها. هنا يدور الجدار عند تشغيل السكربت، ثم يتلاشى ويصغر، وبعد انتهاء الـ Tween يُحذف:

Script في قطعة في Workspace باسم FadingWall
-- Script داخل Part باسم FadingWall.
local TweenService = game:GetService("TweenService")

local wall = script.Parent :: BasePart

-- ربع دورة حول محوره الرأسي خلال ثانية واحدة
local turn = TweenService:Create(wall, TweenInfo.new(1), {
	CFrame = wall.CFrame * CFrame.Angles(0, math.rad(90), 0),
})
turn:Play()
turn.Completed:Wait() -- نكمل فقط عندما ينتهي الدوران

-- ثم نخفيه ونصغّره في الوقت نفسه
local fade = TweenService:Create(wall, TweenInfo.new(0.8, Enum.EasingStyle.Quad, Enum.EasingDirection.In), {
	Transparency = 1,
	Size = wall.Size * 0.2,
})
fade:Play()
fade.Completed:Wait()
wall:Destroy()

يُطلق Completed مع PlaybackState: القيمة Completed إذا وصل الـ Tween إلى الهدف، أو Cancelled إذا أوقفه tween:Cancel(). لا تنتظر Completed في Tween يتكرر بلا نهاية: فهو لن ينتهي أبدًا.

الخطوة 3: عنصر يطفو ويدور

حركتا Tween متكررتان على خاصيتين مختلفتين تعملان في الوقت نفسه. تحريك دورة كاملة بـ 360 درجة عبر CFrame لا يفعل شيئًا، لأن البداية والنهاية هما الدوران نفسه، لذلك يحرّك الدوران قيمة NumberValue من 0 إلى 360 ويضبط CFrame بحسبها. ضع هذا الـ Script في قطعة مثبتة:

Script في قطعة في Workspace باسم FloatingGem
-- Script داخل Part باسم Gem. يطفو صعودًا وهبوطًا ويدور بلا نهاية.
local TweenService = game:GetService("TweenService")

local FLOAT_HEIGHT = 1.5 -- عدد الستد فوق المكان الذي وضعته فيه
local FLOAT_SECONDS = 1.2 -- في كل اتجاه
local SPIN_SECONDS = 3 -- دورة كاملة واحدة

local gem = script.Parent :: BasePart
gem.Anchored = true
local baseCFrame = gem.CFrame

local height = Instance.new("NumberValue")
local angle = Instance.new("NumberValue")

local function apply()
	gem.CFrame = baseCFrame * CFrame.new(0, height.Value, 0) * CFrame.Angles(0, math.rad(angle.Value), 0)
end
height.Changed:Connect(apply)
angle.Changed:Connect(apply)

TweenService:Create(height, TweenInfo.new(FLOAT_SECONDS, Enum.EasingStyle.Sine, Enum.EasingDirection.InOut, -1, true), {
	Value = FLOAT_HEIGHT,
}):Play()

TweenService:Create(angle, TweenInfo.new(SPIN_SECONDS, Enum.EasingStyle.Linear, Enum.EasingDirection.In, -1), {
	Value = 360,
}):Play()

يستخدم الدوران Linear easing، لذا يدور بسرعة ثابتة، وكل دورة تبدأ من 0 من جديد، وهي الزاوية نفسها مثل 360، فلا توجد قفزة. دليل جمع العملات يدمج عناصر كهذه في اللعبة.

الخطوة 4: تحريك نموذج كامل بـ Tween

ليس لدى Model خاصية Position أو CFrame، لذلك لا يجد TweenService:Create(model, ...) ما يحرّكه. بدلًا من ذلك حرّك NumberValue من 0 إلى 1 وانقل النموذج عبر PivotTo، الذي ينقل كل القطع داخله معًا:

Script في نموذج في Workspace باسم Elevator
-- Script داخل Model باسم Elevator.
-- يحرّك النموذج كله 20 ستد للأعلى ثم يعيده، وكل القطع معًا.
local TweenService = game:GetService("TweenService")

local elevator = script.Parent :: Model
local startPivot = elevator:GetPivot()
local endPivot = startPivot * CFrame.new(0, 20, 0)

local progress = Instance.new("NumberValue")
progress.Changed:Connect(function(alpha: number)
	elevator:PivotTo(startPivot:Lerp(endPivot, alpha))
end)

local info = TweenInfo.new(4, Enum.EasingStyle.Quad, Enum.EasingDirection.InOut, -1, true, 2)
TweenService:Create(progress, info, { Value = 1 }):Play()

ثبّت كل قطع النموذج. الرقم 2 في نهاية TweenInfo هو التأخير قبل كل تشغيلة، لذا يتوقف المصعد في الأعلى وفي الأسفل. دليل الأبواب يفتح الأبواب المكوّنة من عدة قطع بالطريقة نفسها.

الخادم أم العميل؟

الـ Tween الذي يعمل في Script على الخادم يغيّر القطعة في الخادم، وتنتقل القيم الجديدة إلى كل اللاعبين، فيراه الجميع. أما الـ Tween في LocalScript فيغيّر القطعة على شاشة هذا اللاعب فقط.

أين تشغّل الـ Tween
شغّله فيمتىمثال
Script على الخادمعندما يهم التغيير اللعبة أو الجميع.الأبواب، والعوائق المتحركة، والجسر الذي ينفتح
LocalScriptعندما يجب أن يراه هذا اللاعب وحده، أو عندما يكون تأثيرًا بصريًا بحتًا.عنصر يتلاشى عند اللاعب الذي التقطه، والواجهة

ترسل المزامنة التحديثات مرات كثيرة في الثانية، لذا تبدو حركات Tween على الخادم سلسة عند معظم اللاعبين، لكن الحركات السريعة جدًا أو الكثيرة جدًا على الخادم قد تبدو أقل سلاسة مع اتصال بطيء. للكثير من الحركة الزخرفية (مئات العملات الدوّارة) شغّل حركات Tween في LocalScript على كل عميل.

الأخطاء الشائعة وحلولها

افتح نافذة Output (قائمة Window ثم Output) قبل الضغط على Play.

القطعة لا تتحرك إطلاقًا

تأكد أنك استدعيت :Play() على الـ Tween، وأن اسم الخاصية في الهدف مكتوب بدقة (Position لا position)، وأنه Script في مكان تعمل فيه السكربتات (داخل قطعة في Workspace أو في ServerScriptService).

القطعة تسقط أو تهتز أثناء الـ Tween

إنها غير مثبتة، لذا تعرقل الجاذبية والتصادمات الحركة. فعّل Anchored.

TweenService:Create property cannot be tweened due to type mismatch

قيمة الهدف من نوع خاطئ، مثل رقم لخاصية من نوع Vector3. راجع صفحة الخطأ (بالإنجليزية).

Unable to cast to Dictionary أو Unable to cast value to Object

الوسائط بترتيب خاطئ أو من نوع خاطئ. الترتيب دائمًا Create(instance, tweenInfo, goalTable). راجع Unable to cast value to Object (بالإنجليزية).

اصنعه مع RoCode

إذا لم ترغب في كتابة حركات Tween يدويًا، يستطيع RoCode بناءها في المكان المفتوح عندك. RoCode وكيل ذكاء اصطناعي مستقل لـ Roblox Studio ولا يتبع Roblox: تصف التغيير في دردشة الويب، وتنشئ إضافته لـ Studio السكربتات في Explorer عندك، فلا حاجة إلى لصق الكود.

ما تكتبه

اجعل نموذج الجسر في Workspace ينزاح 15 ستد إلى الجانب عندما تبدأ الجولة، عبر Tween على NumberValue وPivotTo، وفي الوقت نفسه أخفِ قطع الحواجز الحمراء خلال ثانية واحدة.

ما يفعله RoCode
  • يمكنه العثور على القطع والنماذج المطلوبة عبر Search Game قبل أن يكتب أي شيء
  • يكتب Script عبر Create Script، وقد أُمر بفحص الترجمة عبر Check Script
  • يضع نقطة تراجع قبل كل مجموعة تغييرات وبعدها، لذا يتراجع Ctrl+Z عن مجموعة واحدة في كل مرة

مع الإضافة 3.9 أو أحدث يستطيع RoCode تشغيل اختبار لعب قصير وقراءة الأخطاء، لكن الحركة يسهل الحكم عليها بعينيك، لذا اضغط Play وشاهد. كيف يتصل RoCode بـ Studio.

الأسئلة الشائعة

كيف أستخدم TweenService في Roblox؟

احصل على الخدمة، وأنشئ TweenInfo، واستدعِ TweenService:Create(object, info, { Property = goal }) وشغّل :Play() على النتيجة. في القسم الأول مثال من ثلاثة أسطر.

كيف أكرر Tween إلى الأبد؟

مرّر -1 كقيمة رابعة في TweenInfo.new (repeatCount)، وtrue كقيمة خامسة إذا كان يجب أن يذهب ويعود.

كيف أنتظر انتهاء الـ Tween؟

استدعِ tween.Completed:Wait() بعد tween:Play()، أو اربط دالة بـ tween.Completed.

هل يمكن تحريك Model بـ Tween؟

ليس مباشرة. حرّك NumberValue من 0 إلى 1 واستدعِ model:PivotTo(start:Lerp(goal, value)) عند كل تغيير، كما في الخطوة 4.

كيف أوقف الـ Tween؟

استدعِ tween:Cancel() لإيقافه وترك القطعة حيث هي، أو tween:Pause() لتكمله لاحقًا عبر Play().

المصادر والقراءات

كيف فُحص الكود: كل سكربت في هذه الصفحة يجتاز الفاحص الصارم للأنواع في Luau مع تعريفات واجهة Roblox البرمجية (luau-lsp، ٢٠ نوفمبر ٢٠٢٦). فحص الأنواع يكشف الأخطاء في أسماء الواجهات البرمجية والأنواع الخاطئة، لا منطق اللعبة، فجرّب الكود في Studio قبل النشر.

جرّب RoCode على لعبتك أنت.

رصيد مجاني كل يوم ودون بطاقة. ثبّت الإضافة، وصف الميزة، وراجع ما يظهر في Studio.