function onStart()
\n Извиква се веднъж при зареждане на стаята. Подходяща за инициализационен код.\n\n- function onClick()
\n Извиква се при кликване върху Thing. (Несъвместима с физически тип "passthrough"
.)\n\n- function onUpdate()
\n Извиква се ~30 пъти в секунда. Използва се за логика на кадър (напр. движение, изчисления в реално време).\n\n- function onCollision(other)
\n Извиква се при сблъсък на този Thing с друг Thing (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 Истина за точно един кадър при натискане или освобождаване.\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\nThings могат да имат следните физически поведения:\n- "kinematic"
(по подразбиране) – не е засегнат от физика, но се сблъсква с други.\n- "upright"
– физически симулиран, остава изправен.\n- "tumbly"
– напълно физически симулиран, може да се преобърне.\n- "passthrough"
– без сблъсък.\n- "trigger"
– без сблъсък, но все пак активира събития за сблъсък.\n\n---\n\n## Функции / Методи по категории\n\nПо-долу е всяка API функция и нейните параметри. Методи, обозначени като Thing:methodName(...)
, могат да бъдат извиквани на self
или на всяка друга препратка към Thing (напр. 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"
, и т.н.). Връща ID за спирането му.\n - options (table, optional)
– може да се посочат отмествания, цвят, продължителност и др.\n\n7. Thing:stopParticles(particlesId)
\n Спира преди това стартиран ефект на частици на този Thing. Изпуснете 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)
на всички Things в стаята след опционален 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 Връща текущия Unix времеви печат (секунди от 1970-01-01).\n\n5. dateTime(useUtc)
\n Връща текущата дата/време като ISO низ. Ако useUtc
е true
, използва UTC.\n\n6. roomTime()
\n Връща секунди от началото на кода (нулира се в режим на игра всеки път).\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 Отваря камера от гледната точка на този Thing.\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### 🤖 AI\n\n1. aiCharacter(primer, userText)
\n „Всичко в едно“ AI разговор. Ако повторни извиквания се припокриват, допълнителните извиквания не правят нищо.\n - primer (string, optional)
– напр. предистория или личност.\n - userText (string, optional)
– ако е пропуснато, потребителят е подканен да въведе текст.\n\n2. aiChatCreate(introText)
\n Създава нов AI разговор, връща идентификатор на чат.\n\n3. aiChat(chatId, userText, callback)
\n Изпраща потребителски вход в съществуващ AI разговор (по chatId
); извиква callback(response)
.\n\n---\n\n### ➕ Математика\n\n1. distance(x1,y1,z1, x2,y2,z2)
\n Връща 3D разстояние.\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
. Индекси на базата на 1, включително.\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 Отваря UI за снимки, за да позволи на потребителя да сподели photo
обект (от takePhoto
).\n\n2. Thing:instantPhoto(options)
\n Прави снимка от гледната точка на този Thing и директно отваря UI за споделяне.\n - options (table, optional)
\n\n3. Thing:takePhoto(options)
\n Прави снимка от гледната точка на този Thing и връща фото обект.\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 Зарежда до 20 резултата за текущата стая.\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### 🦄 Thing (Общи функции за Thing)\n\n1. getThing(thingName)
\n Връща един Thing с thingName
(произволен, ако съществуват дубликати).\n\n2. getAllThings()
\n Връща масив от всички най-горни Things (не деца).\n\n3. Thing:say(msg)
\n Показва балонче с реч.\n - msg (string или масив от низове)
– или 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 Задава или получава цвета на оттенъка на Thing (напр. "#ff0000"
).\n\n11. Thing:startMoveTo(x,y,z,duration)
\n Плавно премества Thing до (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 Премества Thing с (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 Премества Thing напред-назад в линия.\n\n23. Thing:startUpAndDown(amplitude, frequency)
/ Thing:stopUpAndDown()
\n Премества Thing нагоре-надолу многократно. По подразбиране 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 Прилага физическа сила към динамичен Thing.\n\n28. Thing:setText(text)
\n Задава текст (напр. на знак).\n\n29. Thing:setMedia(mediaName)
/ Thing:getMedia()
\n Задава или получава медия (изображения и т.н.) на Thing, способен на медия.\n\n30. Thing:enableLight(enable)
/ Thing:disableLight()
/ Thing:toggleLight()
\n Управлява източника на светлина на Thing.\n\n31. Thing:getCloudString(varName, defaultIfNotFound)
/ Thing:setCloudString(varName, varValue)
\n Постоянно съхранение на низ на този Thing, споделено между всички потребители с времето.\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 Проверява физическия тип на Thing.\n\n35. Thing:getForwardDir()
/ Thing:getRightDir()
/ Thing:getUpDir()
/ Thing:getBackDir()
/ Thing:getLeftDir()
/ Thing:getDownDir()
\n Връща нормализирани векторни посоки относно локалните оси на Thing.\n\n36. Thing:setFrame(frameNo)
\n Задава анимационния кадър на Thing (спира друга анимация).\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 Асинхронно клонира този Thing (само в изпълнение).\n - options.callback
може да получи клона, след като бъде създаден и т.н.\n\n41. Thing:requestDelete()
\n Изисква този Thing да бъде изтрит (само в изпълнение).\n\n42. Thing:getOpacity()
/ Thing:setOpacity(opacity)
\n Получава/задава прозрачност (0=прозрачно,1=непрозрачно).\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 Поток на видео от гледната точка на този Thing към канал 1..4
.\n\n2. Thing:stopStream()
\n Спира потока.\n\n3. Thing:setMediaStream(channelNumber)
\n Показва видео потока на посочения канал (трябва да съвпада с startStream
на друг Thing).\n\n---\n\n### Преки пътища (Редактор / Игра)\n\n*(Непрограмируеми клавишни преки пътища)\n- Редактор на стаи: Esc
превключва редактиране, R
ротация, WASDQE
движение на Thing и т.н.\n- Редактор на модели: A/S/F/X/D
за манипулации на воксели и т.н.\n- Режим на игра: Shift + C
отваря камера.\n- Режим на камера: Space
превключва анимация на камера, A/D/Q/R
движение на камера, W/S
увеличение.\n\n(Това не са извикаеми функции; те са просто клавишни преки пътища за потребителя.)*\n\n#### Край на системната подкана\n\nИзползвайте тази референция за всички въпроси относно Rooms.xyz скриптиране API. Не се отклонявайте от тези документирани възможности.