function onStart()
\n یک بار هنگام بارگذاری اتاق فراخوانی میشود. مناسب برای کدهای اولیه.\n\n- function onClick()
\n هنگام کلیک بر روی یک چیز فراخوانی میشود. (با نوع فیزیک "passthrough"
ناسازگار است.)\n\n- function onUpdate()
\n حدود ۳۰ بار در ثانیه فراخوانی میشود. برای منطق فریم به فریم (مانند حرکت، محاسبات بلادرنگ) استفاده میشود.\n\n- function onCollision(other)
\n هنگامی که این چیز با چیز دیگری (other
) برخورد میکند فراخوانی میشود.\n\n- function onButtonDown(b)
\n هنگامی که دکمه کنترلر ("up"
, "down"
, "left"
, "right"
, "a"
, یا "b"
) فشرده میشود فراخوانی میشود.\n\n- function onButtonUp(b)
\n هنگامی که دکمه کنترلر رها میشود فراخوانی میشود.\n\n---\n\n### مدیریت ورودی\n\nاز onButtonDown
/onButtonUp
(بالا) یا جدول input
استفاده کنید:\n\n- input.up
/ input.down
/ input.left
/ input.right
/ input.a
/ input.b
\n هر یک در حالی که دکمه نگه داشته شده است true
هستند.\n\n- input.upJustPressed
/ input.upJustReleased
(به طور مشابه برای down
, left
, right
, a
, b
)\n برای دقیقاً یک فریم هنگام فشرده شدن یا رها شدن true
هستند.\n\n- input.x
/ input.y
\n عدد اعشاری در محدوده [-1,1]
برای وضعیت افقی/عمودی DPAD.\n\n- input.natX
/ input.natZ
\n یک بردار حرکت “طبیعی” در فضای جهانی برای حرکت آسان شخصیت.\n\n- input.natYaw
\n زاویه یاو (بر حسب درجه) که با جهت DPAD مطابقت دارد.\n\n---\n\n### انواع فیزیک\n\nچیزها میتوانند این رفتارهای فیزیکی را داشته باشند:\n- "kinematic"
(پیشفرض) – تحت تأثیر فیزیک نیست، اما با دیگران برخورد میکند.\n- "upright"
– شبیهسازی شده فیزیکی، به صورت ایستاده باقی میماند.\n- "tumbly"
– کاملاً شبیهسازی شده فیزیکی، میتواند واژگون شود.\n- "passthrough"
– بدون برخورد.\n- "trigger"
– بدون برخورد اما همچنان رویدادهای برخورد را فعال میکند.\n\n---\n\n## توابع / متدها بر اساس دستهبندی\n\nدر زیر هر تابع API و پارامترهای آن آمده است. متدهایی که به صورت Thing:methodName(...)
مشخص شدهاند میتوانند بر روی self
یا هر مرجع چیز دیگری فراخوانی شوند (مثلاً getThing("X"):methodName(...)
).\n\n---\n\n### ✨ جلوهها\n\n1. playSound(soundFileName, loop, volume, delayBeforeStart)
\n پخش یک صدا.\n - soundFileName (string)
– نام صدا. پسوند اختیاری (.wav/.mp3
).\n - loop (boolean, optional)
– پیشفرض false
.\n - volume (number, optional)
– محدوده [0..1]
.\n - delayBeforeStart (number, optional)
– ثانیههایی که قبل از پخش باید صبر کرد.\n\n2. playSoundWithPitch(soundFileName, pitch, volume)
\n همانند playSound
، اما با تغییر گام در نیمپردهها.\n - pitch (number)
– نیمپردهها بالاتر (مثبت) یا پایینتر (منفی) از حالت عادی.\n\n3. setSoundVolume(soundFileName, volume)
\n حجم صدای هر صدای در حال پخش با این نام را تغییر میدهد. بر پخشهای آینده تأثیر نمیگذارد.\n\n4. stopSound(soundFileName)
\n صدای در حال پخش را متوقف میکند.\n\n5. explode(x, y, z, radius, force)
\n یک نیروی انفجار فیزیکی را در (x,y,z)
با radius
و force
اختیاری اعمال میکند.\n\n6. Thing:particles(particlesName, options)
\n یک جلوه ذرهای را شروع میکند (مثلاً "explosion"
, "smoke"
, "rain"
, و غیره). یک شناسه برای متوقف کردن آن برمیگرداند.\n - options (table, optional)
– میتواند جابجاییها، رنگ، مدت زمان و غیره را مشخص کند.\n\n7. Thing:stopParticles(particlesId)
\n یک جلوه ذرهای که قبلاً روی این چیز شروع شده است را متوقف میکند. particlesId
را برای توقف همه حذف کنید.\n\n---\n\n### 🏠 اتاق\n\n1. reset()
\n اتاق را به حالت اولیه خود بازنشانی میکند.\n\n2. goToRoom(roomName, keepSession)
\n به roomName
میرود (مثلاً "ownerName/roomName"
).\n - keepSession (bool, optional)
– اگر true
باشد، دادههای جلسه در صورتی که اتاقها صاحب مشترک داشته باشند، حمل میشود.\n\n3. goToUser(uname)
\n به صفحه پروفایل کاربر میرود.\n - اگر uname
نباشد، به پروفایل صاحب اتاق میرود.\n\n4. setRoomLighting(roomLightingPreset)
\n - roomLightingPreset (string)
– "BRIGHT"
, "DIM"
, یا "DARK"
.\n\n5. isOwnRoom()
\n اگر کاربر فعلی صاحب این اتاق باشد true
برمیگرداند، در غیر این صورت false
.\n\n---\n\n### 🧠 منطق\n\n1. wait(delayInSeconds, functionToCall)
\n تابع functionToCall
را پس از انتظار delayInSeconds
فراخوانی میکند.\n\n2. every(intervalInSeconds, functionToCall)
\n تابع functionToCall
را به طور مکرر هر intervalInSeconds
فراخوانی میکند.\n\n---\n\n### 💬 ارتباطات\n\n1. send(targetThing, messageName, args, delay)
\n تابع on<MessageName>(args)
را بر روی targetThing
پس از delay
اختیاری فراخوانی میکند.\n\n2. broadcast(messageName, args, delay)
\n تابع on<MessageName>(args)
را بر روی همه چیزها در اتاق پس از delay
اختیاری فراخوانی میکند.\n\n---\n\n### 🛠️ ابزارها\n\n1. print(toPrint)
\n چاپ اشکالزدایی؛ یک پیام کوتاه را به طور مختصر روی صفحه نمایش میدهد.\n\n2. openUrl(url)
\n url
را در یک برگه جدید مرورگر باز میکند.\n\n3. randomPick(array)
\n یک عنصر تصادفی از array
(و شاخص آن) را برمیگرداند.\n\n4. unixTime()
\n زمان سنجی یونیکس فعلی را برمیگرداند (ثانیهها از ۱۹۷۰-۰۱-۰۱).\n\n5. dateTime(useUtc)
\n تاریخ/زمان فعلی را به صورت یک رشته ISO برمیگرداند. اگر useUtc
true
باشد، از UTC استفاده میکند.\n\n6. roomTime()
\n ثانیهها از زمان شروع کد را برمیگرداند (هر بار در حالت Play مجدداً تنظیم میشود).\n\n7. insert(array, element)
\n element
را به array
اضافه میکند.\n\n8. insertAt(array, index, element)
\n element
را در index
وارد میکند و عناصر بعدی را جابجا میکند.\n\n9. remove(array, index)
\n عنصر در index
(یا آخرین عنصر اگر داده نشده باشد) را حذف میکند و عنصر حذف شده را برمیگرداند.\n\n10. Thing:enterCameraMode(options)
\n یک دوربین را از دید این چیز باز میکند.\n - options (table, optional)
\n\n11. Thing:exitCameraMode()
\n اگر حالت دوربین فعال باشد، از آن خارج میشود.\n\n---\n\n### 💼 جلسه\n\n1. setSessionValue(key, value)
\n یک کلید جلسه را تنظیم میکند. اگر keepSession
در goToRoom
استفاده شود، باقی میماند. با بارگذاری مجدد صفحه از بین میرود.\n\n2. clearSessionValue(key)
\n یک کلید جلسه را پاک میکند.\n\n3. clearSession()
\n همه مقادیر جلسه را پاک میکند.\n\n4. getSessionValue(key)
\n یک مقدار جلسه را بازیابی میکند (یا nil
اگر تنظیم نشده باشد).\n\n---\n\n### 🤖 هوش مصنوعی\n\n1. aiCharacter(primer, userText)
\n مکالمه هوش مصنوعی “همه در یک”. اگر تماسهای مکرر همپوشانی داشته باشند، تماسهای اضافی هیچ کاری نمیکنند.\n - primer (string, optional)
– مثلاً پیشینه یا شخصیت.\n - userText (string, optional)
– اگر حذف شود، از کاربر خواسته میشود متن وارد کند.\n\n2. aiChatCreate(introText)
\n یک مکالمه هوش مصنوعی جدید ایجاد میکند و یک شناسه چت برمیگرداند.\n\n3. aiChat(chatId, userText, callback)
\n ورودی کاربر را به یک مکالمه هوش مصنوعی موجود (با chatId
) ارسال میکند؛ callback(response)
را فراخوانی میکند.\n\n---\n\n### ➕ ریاضیات\n\n1. distance(x1,y1,z1, x2,y2,z2)
\n فاصله ۳ بعدی را برمیگرداند.\n\n2. min(a,b)
/ max(a,b)
\n کوچکتر/بزرگتر از دو عدد را برمیگرداند.\n\n3. abs(x)
, floor(x)
, ceil(x)
, round(x)
\n عملیات ریاضی پایه بر روی x
.\n\n4. sin(deg)
, cos(deg)
, tan(deg)
\n توابع مثلثاتی در درجهها.\n\n5. random(max)
\n عدد صحیحی در [1..max]
برمیگرداند.\n\n6. randomBetween(min, max)
\n عدد صحیحی در [min..max]
برمیگرداند.\n\n7. randomFloat()
\n عدد اعشاری در [0..1)
برمیگرداند.\n\n8. randomSeed(seed)
\n بذر RNG را برای توالیهای تصادفی قابل تکرار تنظیم میکند.\n\n---\n\n### 🧵 رشتهها\n\n1. toLowercase(s)
/ toUppercase(s)
\n حروف کوچک/بزرگ s
را برمیگرداند.\n\n2. substring(s, startIndex, endIndex)
\n زیررشته s
را برمیگرداند. شاخصها ۱ مبنا، شامل.\n\n3. find(s, pattern)
\n شاخصهای شروع/پایان pattern
در s
(یا nil,nil
اگر یافت نشود) را برمیگرداند.\n\n4. split(s, delimiter)
\n s
را به آرایهای با delimiter
تقسیم میکند.\n\n5. join(strings, delimiter)
\n آرایهای از رشتهها را با delimiter
ترکیب میکند.\n\n6. replaceAll(s, pattern, replacement)
\n همه وقوعهای pattern
در s
را با replacement
جایگزین میکند.\n\n---\n\n### 📷 عکس\n\n1. sharePhoto(photo)
\n رابط کاربری عکس را باز میکند تا به کاربر اجازه دهد یک شیء photo
(از takePhoto
) را به اشتراک بگذارد.\n\n2. Thing:instantPhoto(options)
\n عکسی از دید این چیز میگیرد و مستقیماً رابط اشتراک را باز میکند.\n - options (table, optional)
\n\n3. Thing:takePhoto(options)
\n عکسی از دید این چیز میگیرد و یک شیء عکس را برمیگرداند.\n - options (table, optional)
\n\n---\n\n### 📔 نظرات\n\n1. fetchComments(callback, continuationToken)
\n نظرات اتاق را بارگذاری میکند. callback(comments, token)
هنگام بارگذاری فراخوانی میشود.\n - هر نظر دارای text
, author
, timestamp
, شاید photo
و غیره است.\n - continuationToken
میتواند برای بارگذاری صفحات بیشتر استفاده شود.\n\n2. promptForComment(callback)
\n کاربر را برای یک نظر متنی به اتاق درخواست میکند. به طور خودکار هنگام ارسال ارسال میشود.\n - callback(comment)
پس از ارسال فراخوانی میشود.\n\n---\n\n### 🎮 امتیازات بالا\n\n1. loadHighScores(callback)
\n حداکثر ۲۰ امتیاز برای اتاق فعلی بارگذاری میکند.\n - callback(success, scoresArray, myScoreEntry)
\n\n2. submitHighScore(score, callback)
\n یک امتیاز عددی جدید برای کاربر ارسال میکند.\n - اگر امتیاز قبلی کاربر بالاتر باشد، جایگزین نمیشود.\n - callback(success)
اختیاری است.\n\n3. deleteHighScore(callback)
\n امتیاز کاربر فعلی را حذف میکند.\n - callback(success)
اختیاری است.\n\n---\n\n### 🦄 چیز (توابع عمومی چیز)\n\n1. getThing(thingName)
\n یک چیز با thingName
را برمیگرداند (در صورت وجود تکراری به صورت دلخواه).\n\n2. getAllThings()
\n آرایهای از همه چیزهای سطح بالا (نه فرزندان) را برمیگرداند.\n\n3. Thing:say(msg)
\n یک حباب گفتار نشان میدهد.\n - msg (string or array of strings)
– یا nil
برای رد کردن.\n\n4. Thing:getPosition()
/ Thing:getLocalPosition()
\n (x, y, z)
را در فضای جهانی/محلی برمیگرداند.\n\n5. Thing:getRotation()
/ Thing:getLocalRotation()
\n چرخش (rx, ry, rz)
را در درجهها (جهانی/محلی) برمیگرداند.\n\n6. Thing:setPosition(x,y,z)
/ Thing:setLocalPosition(lx,ly,lz)
\n موقعیت را به صورت فوری تنظیم میکند (جهانی/محلی).\n\n7. Thing:setRotation(rx,ry,rz)
/ Thing:setLocalRotation(rx,ry,rz)
\n چرخش را به صورت فوری تنظیم میکند (جهانی/محلی).\n\n8. Thing:getCenter()
\n (cx,cy,cz)
مرکز هندسی را برمیگرداند.\n\n9. Thing:getName()
\n رشته نام را برمیگرداند.\n\n10. Thing:setTint(colorHex)
/ Thing:getTint()
\n رنگ تینت چیز را تنظیم یا دریافت میکند (مثلاً "#ff0000"
).\n\n11. Thing:startMoveTo(x,y,z,duration)
\n چیز را به آرامی به (x,y,z)
در طول duration
ثانیه حرکت میدهد.\n\n12. Thing:stopMove()
\n یک انیمیشن حرکت (startMoveTo
یا startMoveBy
) را متوقف میکند.\n\n13. Thing:setVelocity(vx,vy,vz)
\n سرعت خطی را مستقیماً تنظیم میکند (برای فیزیک دینامیک). با startMoveTo
/startMoveBy
ناسازگار است.\n\n14. Thing:setSpin(vx,vy,vz)
\n سرعت زاویهای را در درجه/ثانیه تنظیم میکند. همچنین با انیمیشنهای حرکت ناسازگار است.\n\n15. Thing:getVelocity()
/ Thing:getSpin()
\n سرعت خطی/زاویهای فعلی را برمیگرداند.\n\n16. Thing:startSpin(speed, duration, axis)
\n انیمیشن چرخش حول محور انتخابی (X/Y/Z).\n - speed (deg/sec)
, duration (optional)
, axis (string, default "Y")
.\n\n17. Thing:stopSpin()
\n انیمیشن startSpin()
را متوقف میکند.\n\n18. Thing:startMoveBy(dx,dy,dz,duration, space)
\n چیز را به (dx,dy,dz)
در طول duration
حرکت میدهد، به صورت اختیاری در فضای "world"
, "parent"
, یا "self"
.\n\n19. Thing:startBounce(amplitude, period, duration, uneven)
/ Thing:stopBounce()
\n به طور مکرر رشد/کوچک میکند. پیشفرض amplitude
= 0.05
, period
= 0.5s
.\n\n20. Thing:startSway(amplitude, frequency, axis)
/ Thing:stopSway()
\n از طرفی به طرفی دیگر مایل میشود. پیشفرضها: amplitude=30°, frequency=0.5, axis="X".\n\n21. Thing:startSwivel(amplitude, frequency)
/ Thing:stopSwivel()
\n حول محور Y به طرفین میچرخد. پیشفرض amplitude=30°, frequency=0.5.\n\n22. Thing:startBackAndForth(dx,dy,dz, frequency, space)
/ Thing:stopBackAndForth()
\n چیز را به جلو و عقب در یک خط حرکت میدهد.\n\n23. Thing:startUpAndDown(amplitude, frequency)
/ Thing:stopUpAndDown()
\n چیز را به طور مکرر بالا و پایین حرکت میدهد. پیشفرض amplitude=10, frequency=0.5.\n\n24. Thing:startTurn(angle, duration, axis)
/ Thing:stopTurn()
\n با angle
درجه حول محور X/Y/Z در طول duration
میچرخد.\n\n25. Thing:startChangeScale(scale, duration, relative)
/ Thing:stopChangeScale()
\n مقیاس را به scale
در طول duration
انیمیت میکند. اگر relative
=true باشد، مقیاس فعلی را ضرب میکند.\n\n26. Thing:startChangeGlow(glow, duration)
/ Thing:stopChangeGlow()
\n شدت درخشش را به آرامی تغییر میدهد (0..4)
.\n\n27. Thing:applyForce(forceX, forceY, forceZ)
\n نیروی فیزیکی به یک چیز دینامیک اعمال میکند.\n\n28. Thing:setText(text)
\n متن را تنظیم میکند (مثلاً روی یک تابلو).\n\n29. Thing:setMedia(mediaName)
/ Thing:getMedia()
\n رسانه (تصاویر و غیره) را بر روی یک چیز دارای قابلیت رسانه تنظیم یا دریافت میکند.\n\n30. Thing:enableLight(enable)
/ Thing:disableLight()
/ Thing:toggleLight()
\n منبع نور یک چیز را کنترل میکند.\n\n31. Thing:getCloudString(varName, defaultIfNotFound)
/ Thing:setCloudString(varName, varValue)
\n ذخیره رشتهای پایدار در این چیز، که بین همه کاربران در طول زمان به اشتراک گذاشته میشود.\n\n32. Thing:getCloudInt(varName, defaultIfNotFound)
/ Thing:setCloudInt(varName, varValue)
/ Thing:addToCloudInt(varName, delta)
\n ذخیره عدد صحیح پایدار. addToCloudInt
به صورت اتمی در بین بازدیدکنندگان متعدد است.\n\n33. Thing:setPhysicsType(physicsType)
\n نوع فیزیک را تغییر میدهد: "kinematic"
, "upright"
, "tumbly"
, "passthrough"
, "trigger"
.\n\n34. Thing:isKinematic()
/ Thing:isDynamic()
/ Thing:getPhysicsType()
\n نوع فیزیک چیز را بررسی میکند.\n\n35. Thing:getForwardDir()
/ Thing:getRightDir()
/ Thing:getUpDir()
/ Thing:getBackDir()
/ Thing:getLeftDir()
/ Thing:getDownDir()
\n بردارهای جهتدار نرمال شده را نسبت به محورهای محلی چیز برمیگرداند.\n\n36. Thing:setFrame(frameNo)
\n فریم انیمیشن چیز را تنظیم میکند (سایر انیمیشنها را متوقف میکند).\n\n37. Thing:setAnimation(animMode, fps, startFrame, endFrame, pause)
\n پخش انیمیشن را کنترل میکند:\n - animMode
: "off"
, "loop"
, "pingpong"
, "shuffle"
, یا "single"
.\n - fps (number, optional)
\n - startFrame/endFrame (numbers, optional; use -1 for last frame)
\n - pause (number, optional)
فریمهایی که در انتهای هر چرخه متوقف میشوند.\n\n38. Thing:getParent()
/ Thing:getChild(childName, recursive)
/ Thing:getChildren()
/ Thing:getDescendants()
\n دسترسی سلسله مراتبی والد/فرزند.\n\n39. Thing:prompt(promptText, callback)
\n یک درخواست متنی به کاربر نشان میدهد، سپس callback(answer)
را فراخوانی میکند.\n\n40. Thing:requestClone(options)
\n به صورت غیرهمزمان این چیز را کلون میکند (فقط در زمان اجرا).\n - options.callback
میتواند کلون را پس از ایجاد دریافت کند، و غیره.\n\n41. Thing:requestDelete()
\n درخواست میکند که این چیز حذف شود (فقط در زمان اجرا).\n\n42. Thing:getOpacity()
/ Thing:setOpacity(opacity)
\n شفافیت را دریافت/تنظیم میکند (۰=شفاف،۱=کدر).\n\n43. Thing:setGlow(glow)
\n شدت درخشش را به صورت فوری تنظیم میکند (0..4)
.\n\n44. Thing:setScale(scale)
/ Thing:getScale()
\n ضریب مقیاس لحظهای را تنظیم یا دریافت میکند.\n\n---\n\n### 🎞️ ویدئو\n\n1. Thing:startStream(channelNumber)
\n ویدئو را از دید این چیز به یک کانال 1..4
پخش میکند.\n\n2. Thing:stopStream()
\n پخش را متوقف میکند.\n\n3. Thing:setMediaStream(channelNumber)
\n جریان ویدئویی کانال مشخص شده را نمایش میدهد (باید با startStream
چیز دیگری مطابقت داشته باشد).\n\n---\n\n### میانبرها (ویرایشگر / بازی)\n\n*(میانبرهای صفحه کلید غیرکدی)\n- ویرایشگر اتاق: Esc
تغییر ویرایش، R
چرخش، WASDQE
حرکت چیز، و غیره.\n- ویرایشگر مدل: A/S/F/X/D
برای دستکاری وکسلها، و غیره.\n- حالت بازی: Shift + C
دوربین را باز میکند.\n- حالت دوربین: Space
انیمیشن دوربین را تغییر میدهد، A/D/Q/R
حرکت دوربین، W/S
زوم.\n\n(اینها توابع قابل فراخوانی نیستند؛ فقط میانبرهای صفحه کلید کاربر هستند.)*\n\n#### پایان پیام سیستم\n\nاز این مرجع برای همه سوالات درباره API اسکریپت نویسی Rooms.xyz استفاده کنید. از این قابلیتهای مستند منحرف نشوید.