ReplicatedStorage Packages Knit ProfileService Promise Signal TableUtil _Index evaera_promise@4.0.0 promise (), reject: (...: any) -> (), onCancel: (abortHandler?: () -> ()) -> boolean) -> () @return Promise ]=] function Promise.new(executor) return Promise._new(debug.traceback(nil, 2), executor) end function Promise:__tostring() return string.format("Promise(%s)", self._status) end --[=[ The same as [Promise.new](/api/Promise#new), except execution begins after the next `Heartbeat` event. This is a spiritual replacement for `spawn`, but it does not suffer from the same [issues](https://eryn.io/gist/3db84579866c099cdd5bb2ff37947cec) as `spawn`. ```lua local function waitForChild(instance, childName, timeout) return Promise.defer(function(resolve, reject) local child = instance:WaitForChild(childName, timeout) ;(child and resolve or reject)(child) end) end ``` @param executor (resolve: (...: any) -> (), reject: (...: any) -> (), onCancel: (abortHandler?: () -> ()) -> boolean) -> () @return Promise ]=] function Promise.defer(executor) local traceback = debug.traceback(nil, 2) local promise promise = Promise._new(traceback, function(resolve, reject, onCancel) local connection connection = Promise._timeEvent:Connect(function() connection:Disconnect() local ok, _, result = runExecutor(traceback, executor, resolve, reject, onCancel) if not ok then reject(result[1]) end end) end) return promise end -- Backwards compatibility Promise.async = Promise.defer --[=[ Creates an immediately resolved Promise with the given value. ```lua -- Example using Promise.resolve to deliver cached values: function getSomething(name) if cache[name] then return Promise.resolve(cache[name]) else return Promise.new(function(resolve, reject) local thing = getTheThing() cache[name] = thing resolve(thing) end) end end ``` @param ... any @return Promise<...any> ]=] function Promise.resolve(...) local length, values = pack(...) return Promise._new(debug.traceback(nil, 2), function(resolve) resolve(unpack(values, 1, length)) end) end --[=[ Creates an immediately rejected Promise with the given value. :::caution Something needs to consume this rejection (i.e. `:catch()` it), otherwise it will emit an unhandled Promise rejection warning on the next frame. Thus, you should not create and store rejected Promises for later use. Only create them on-demand as needed. ::: @param ... any @return Promise<...any> ]=] function Promise.reject(...) local length, values = pack(...) return Promise._new(debug.traceback(nil, 2), function(_, reject) reject(unpack(values, 1, length)) end) end --[[ Runs a non-promise-returning function as a Promise with the given arguments. ]] function Promise._try(traceback, callback, ...) local valuesLength, values = pack(...) return Promise._new(traceback, function(resolve) resolve(callback(unpack(values, 1, valuesLength))) end) end --[=[ Begins a Promise chain, calling a function and returning a Promise resolving with its return value. If the function errors, the returned Promise will be rejected with the error. You can safely yield within the Promise.try callback. :::info `Promise.try` is similar to [Promise.promisify](#promisify), except the callback is invoked immediately instead of returning a new function. ::: ```lua Promise.try(function() return math.random(1, 2) == 1 and "ok" or error("Oh an error!") end) :andThen(function(text) print(text) end) :catch(function(err) warn("Something went wrong") end) ``` @param callback (...: T...) -> ...any @param ... T... -- Additional arguments passed to `callback` @return Promise ]=] function Promise.try(callback, ...) return Promise._try(debug.traceback(nil, 2), callback, ...) end --[[ Returns a new promise that: * is resolved when all input promises resolve * is rejected if ANY input promises reject ]] function Promise._all(traceback, promises, amount) if type(promises) ~= "table" then error(string.format(ERROR_NON_LIST, "Promise.all"), 3) end -- We need to check that each value is a promise here so that we can produce -- a proper error rather than a rejected promise with our error. for i, promise in pairs(promises) do if not Promise.is(promise) then error(string.format(ERROR_NON_PROMISE_IN_LIST, "Promise.all", tostring(i)), 3) end end -- If there are no values then return an already resolved promise. if #promises == 0 or amount == 0 then return Promise.resolve({}) end return Promise._new(traceback, function(resolve, reject, onCancel) -- An array to contain our resolved values from the given promises. local resolvedValues = {} local newPromises = {} -- Keep a count of resolved promises because just checking the resolved -- values length wouldn't account for promises that resolve with nil. local resolvedCount = 0 local rejectedCount = 0 local done = false local function cancel() for _, promise in ipairs(newPromises) do promise:cancel() end end -- Called when a single value is resolved and resolves if all are done. local function resolveOne(i, ...) if done then return end resolvedCount = resolvedCount + 1 if amount == nil then resolvedValues[i] = ... else resolvedValues[resolvedCount] = ... end if resolvedCount >= (amount or #promises) then done = true resolve(resolvedValues) cancel() end end onCancel(cancel) -- We can assume the values inside `promises` are all promises since we -- checked above. for i, promise in ipairs(promises) do newPromises[i] = promise:andThen(function(...) resolveOne(i, ...) end, function(...) rejectedCount = rejectedCount + 1 if amount == nil or #promises - rejectedCount < amount then cancel() done = true reject(...) end end) end if done then cancel() end end) end --[=[ Accepts an array of Promises and returns a new promise that: * is resolved after all input promises resolve. * is rejected if *any* input promises reject. :::info Only the first return value from each promise will be present in the resulting array. ::: After any input Promise rejects, all other input Promises that are still pending will be cancelled if they have no other consumers. ```lua local promises = { returnsAPromise("example 1"), returnsAPromise("example 2"), returnsAPromise("example 3"), } return Promise.all(promises) ``` @param promises {Promise} @return Promise<{T}> ]=] function Promise.all(promises) return Promise._all(debug.traceback(nil, 2), promises) end --[=[ Folds an array of values or promises into a single value. The array is traversed sequentially. The reducer function can return a promise or value directly. Each iteration receives the resolved value from the previous, and the first receives your defined initial value. The folding will stop at the first rejection encountered. ```lua local basket = {"blueberry", "melon", "pear", "melon"} Promise.fold(basket, function(cost, fruit) if fruit == "blueberry" then return cost -- blueberries are free! else -- call a function that returns a promise with the fruit price return fetchPrice(fruit):andThen(function(fruitCost) return cost + fruitCost end) end end, 0) ``` @since v3.1.0 @param list {T | Promise} @param reducer (accumulator: U, value: T, index: number) -> U | Promise @param initialValue U ]=] function Promise.fold(list, reducer, initialValue) assert(type(list) == "table", "Bad argument #1 to Promise.fold: must be a table") assert(isCallable(reducer), "Bad argument #2 to Promise.fold: must be a function") local accumulator = Promise.resolve(initialValue) return Promise.each(list, function(resolvedElement, i) accumulator = accumulator:andThen(function(previousValueResolved) return reducer(previousValueResolved, resolvedElement, i) end) end):andThen(function() return accumulator end) end --[=[ Accepts an array of Promises and returns a Promise that is resolved as soon as `count` Promises are resolved from the input array. The resolved array values are in the order that the Promises resolved in. When this Promise resolves, all other pending Promises are cancelled if they have no other consumers. `count` 0 results in an empty array. The resultant array will never have more than `count` elements. ```lua local promises = { returnsAPromise("example 1"), returnsAPromise("example 2"), returnsAPromise("example 3"), } return Promise.some(promises, 2) -- Only resolves with first 2 promises to resolve ``` @param promises {Promise} @param count number @return Promise<{T}> ]=] function Promise.some(promises, count) assert(type(count) == "number", "Bad argument #2 to Promise.some: must be a number") return Promise._all(debug.traceback(nil, 2), promises, count) end --[=[ Accepts an array of Promises and returns a Promise that is resolved as soon as *any* of the input Promises resolves. It will reject only if *all* input Promises reject. As soon as one Promises resolves, all other pending Promises are cancelled if they have no other consumers. Resolves directly with the value of the first resolved Promise. This is essentially [[Promise.some]] with `1` count, except the Promise resolves with the value directly instead of an array with one element. ```lua local promises = { returnsAPromise("example 1"), returnsAPromise("example 2"), returnsAPromise("example 3"), } return Promise.any(promises) -- Resolves with first value to resolve (only rejects if all 3 rejected) ``` @param promises {Promise} @return Promise ]=] function Promise.any(promises) return Promise._all(debug.traceback(nil, 2), promises, 1):andThen(function(values) return values[1] end) end --[=[ Accepts an array of Promises and returns a new Promise that resolves with an array of in-place Statuses when all input Promises have settled. This is equivalent to mapping `promise:finally` over the array of Promises. ```lua local promises = { returnsAPromise("example 1"), returnsAPromise("example 2"), returnsAPromise("example 3"), } return Promise.allSettled(promises) ``` @param promises {Promise} @return Promise<{Status}> ]=] function Promise.allSettled(promises) if type(promises) ~= "table" then error(string.format(ERROR_NON_LIST, "Promise.allSettled"), 2) end -- We need to check that each value is a promise here so that we can produce -- a proper error rather than a rejected promise with our error. for i, promise in pairs(promises) do if not Promise.is(promise) then error(string.format(ERROR_NON_PROMISE_IN_LIST, "Promise.allSettled", tostring(i)), 2) end end -- If there are no values then return an already resolved promise. if #promises == 0 then return Promise.resolve({}) end return Promise._new(debug.traceback(nil, 2), function(resolve, _, onCancel) -- An array to contain our resolved values from the given promises. local fates = {} local newPromises = {} -- Keep a count of resolved promises because just checking the resolved -- values length wouldn't account for promises that resolve with nil. local finishedCount = 0 -- Called when a single value is resolved and resolves if all are done. local function resolveOne(i, ...) finishedCount = finishedCount + 1 fates[i] = ... if finishedCount >= #promises then resolve(fates) end end onCancel(function() for _, promise in ipairs(newPromises) do promise:cancel() end end) -- We can assume the values inside `promises` are all promises since we -- checked above. for i, promise in ipairs(promises) do newPromises[i] = promise:finally(function(...) resolveOne(i, ...) end) end end) end --[=[ Accepts an array of Promises and returns a new promise that is resolved or rejected as soon as any Promise in the array resolves or rejects. :::warning If the first Promise to settle from the array settles with a rejection, the resulting Promise from `race` will reject. If you instead want to tolerate rejections, and only care about at least one Promise resolving, you should use [Promise.any](#any) or [Promise.some](#some) instead. ::: All other Promises that don't win the race will be cancelled if they have no other consumers. ```lua local promises = { returnsAPromise("example 1"), returnsAPromise("example 2"), returnsAPromise("example 3"), } return Promise.race(promises) -- Only returns 1st value to resolve or reject ``` @param promises {Promise} @return Promise ]=] function Promise.race(promises) assert(type(promises) == "table", string.format(ERROR_NON_LIST, "Promise.race")) for i, promise in pairs(promises) do assert(Promise.is(promise), string.format(ERROR_NON_PROMISE_IN_LIST, "Promise.race", tostring(i))) end return Promise._new(debug.traceback(nil, 2), function(resolve, reject, onCancel) local newPromises = {} local finished = false local function cancel() for _, promise in ipairs(newPromises) do promise:cancel() end end local function finalize(callback) return function(...) cancel() finished = true return callback(...) end end if onCancel(finalize(reject)) then return end for i, promise in ipairs(promises) do newPromises[i] = promise:andThen(finalize(resolve), finalize(reject)) end if finished then cancel() end end) end --[=[ Iterates serially over the given an array of values, calling the predicate callback on each value before continuing. If the predicate returns a Promise, we wait for that Promise to resolve before moving on to the next item in the array. :::info `Promise.each` is similar to `Promise.all`, except the Promises are ran in order instead of all at once. But because Promises are eager, by the time they are created, they're already running. Thus, we need a way to defer creation of each Promise until a later time. The predicate function exists as a way for us to operate on our data instead of creating a new closure for each Promise. If you would prefer, you can pass in an array of functions, and in the predicate, call the function and return its return value. ::: ```lua Promise.each({ "foo", "bar", "baz", "qux" }, function(value, index) return Promise.delay(1):andThen(function() print(("%d) Got %s!"):format(index, value)) end) end) --[[ (1 second passes) > 1) Got foo! (1 second passes) > 2) Got bar! (1 second passes) > 3) Got baz! (1 second passes) > 4) Got qux! ]] ``` If the Promise a predicate returns rejects, the Promise from `Promise.each` is also rejected with the same value. If the array of values contains a Promise, when we get to that point in the list, we wait for the Promise to resolve before calling the predicate with the value. If a Promise in the array of values is already Rejected when `Promise.each` is called, `Promise.each` rejects with that value immediately (the predicate callback will never be called even once). If a Promise in the list is already Cancelled when `Promise.each` is called, `Promise.each` rejects with `Promise.Error(Promise.Error.Kind.AlreadyCancelled`). If a Promise in the array of values is Started at first, but later rejects, `Promise.each` will reject with that value and iteration will not continue once iteration encounters that value. Returns a Promise containing an array of the returned/resolved values from the predicate for each item in the array of values. If this Promise returned from `Promise.each` rejects or is cancelled for any reason, the following are true: - Iteration will not continue. - Any Promises within the array of values will now be cancelled if they have no other consumers. - The Promise returned from the currently active predicate will be cancelled if it hasn't resolved yet. @since 3.0.0 @param list {T | Promise} @param predicate (value: T, index: number) -> U | Promise @return Promise<{U}> ]=] function Promise.each(list, predicate) assert(type(list) == "table", string.format(ERROR_NON_LIST, "Promise.each")) assert(isCallable(predicate), string.format(ERROR_NON_FUNCTION, "Promise.each")) return Promise._new(debug.traceback(nil, 2), function(resolve, reject, onCancel) local results = {} local promisesToCancel = {} local cancelled = false local function cancel() for _, promiseToCancel in ipairs(promisesToCancel) do promiseToCancel:cancel() end end onCancel(function() cancelled = true cancel() end) -- We need to preprocess the list of values and look for Promises. -- If we find some, we must register our andThen calls now, so that those Promises have a consumer -- from us registered. If we don't do this, those Promises might get cancelled by something else -- before we get to them in the series because it's not possible to tell that we plan to use it -- unless we indicate it here. local preprocessedList = {} for index, value in ipairs(list) do if Promise.is(value) then if value:getStatus() == Promise.Status.Cancelled then cancel() return reject(Error.new({ error = "Promise is cancelled", kind = Error.Kind.AlreadyCancelled, context = string.format( "The Promise that was part of the array at index %d passed into Promise.each was already cancelled when Promise.each began.\n\nThat Promise was created at:\n\n%s", index, value._source ), })) elseif value:getStatus() == Promise.Status.Rejected then cancel() return reject(select(2, value:await())) end -- Chain a new Promise from this one so we only cancel ours local ourPromise = value:andThen(function(...) return ... end) table.insert(promisesToCancel, ourPromise) preprocessedList[index] = ourPromise else preprocessedList[index] = value end end for index, value in ipairs(preprocessedList) do if Promise.is(value) then local success success, value = value:await() if not success then cancel() return reject(value) end end if cancelled then return end local predicatePromise = Promise.resolve(predicate(value, index)) table.insert(promisesToCancel, predicatePromise) local success, result = predicatePromise:await() if not success then cancel() return reject(result) end results[index] = result end resolve(results) end) end --[=[ Checks whether the given object is a Promise via duck typing. This only checks if the object is a table and has an `andThen` method. @param object any @return boolean -- `true` if the given `object` is a Promise. ]=] function Promise.is(object) if type(object) ~= "table" then return false end local objectMetatable = getmetatable(object) if objectMetatable == Promise then -- The Promise came from this library. return true elseif objectMetatable == nil then -- No metatable, but we should still chain onto tables with andThen methods return isCallable(object.andThen) elseif type(objectMetatable) == "table" and type(rawget(objectMetatable, "__index")) == "table" and isCallable(rawget(rawget(objectMetatable, "__index"), "andThen")) then -- Maybe this came from a different or older Promise library. return true end return false end --[=[ Wraps a function that yields into one that returns a Promise. Any errors that occur while executing the function will be turned into rejections. :::info `Promise.promisify` is similar to [Promise.try](#try), except the callback is returned as a callable function instead of being invoked immediately. ::: ```lua local sleep = Promise.promisify(wait) sleep(1):andThen(print) ``` ```lua local isPlayerInGroup = Promise.promisify(function(player, groupId) return player:IsInGroup(groupId) end) ``` @param callback (...: any) -> ...any @return (...: any) -> Promise ]=] function Promise.promisify(callback) return function(...) return Promise._try(debug.traceback(nil, 2), callback, ...) end end --[=[ Returns a Promise that resolves after `seconds` seconds have passed. The Promise resolves with the actual amount of time that was waited. This function is **not** a wrapper around `wait`. `Promise.delay` uses a custom scheduler which provides more accurate timing. As an optimization, cancelling this Promise instantly removes the task from the scheduler. :::warning Passing `NaN`, infinity, or a number less than 1/60 is equivalent to passing 1/60. ::: ```lua Promise.delay(5):andThenCall(print, "This prints after 5 seconds") ``` @function delay @within Promise @param seconds number @return Promise ]=] do -- uses a sorted doubly linked list (queue) to achieve O(1) remove operations and O(n) for insert -- the initial node in the linked list local first local connection function Promise.delay(seconds) assert(type(seconds) == "number", "Bad argument #1 to Promise.delay, must be a number.") -- If seconds is -INF, INF, NaN, or less than 1 / 60, assume seconds is 1 / 60. -- This mirrors the behavior of wait() if not (seconds >= 1 / 60) or seconds == math.huge then seconds = 1 / 60 end return Promise._new(debug.traceback(nil, 2), function(resolve, _, onCancel) local startTime = Promise._getTime() local endTime = startTime + seconds local node = { resolve = resolve, startTime = startTime, endTime = endTime, } if connection == nil then -- first is nil when connection is nil first = node connection = Promise._timeEvent:Connect(function() local threadStart = Promise._getTime() while first ~= nil and first.endTime < threadStart do local current = first first = current.next if first == nil then connection:Disconnect() connection = nil else first.previous = nil end current.resolve(Promise._getTime() - current.startTime) end end) else -- first is non-nil if first.endTime < endTime then -- if `node` should be placed after `first` -- we will insert `node` between `current` and `next` -- (i.e. after `current` if `next` is nil) local current = first local next = current.next while next ~= nil and next.endTime < endTime do current = next next = current.next end -- `current` must be non-nil, but `next` could be `nil` (i.e. last item in list) current.next = node node.previous = current if next ~= nil then node.next = next next.previous = node end else -- set `node` to `first` node.next = first first.previous = node first = node end end onCancel(function() -- remove node from queue local next = node.next if first == node then if next == nil then -- if `node` is the first and last connection:Disconnect() connection = nil else -- if `node` is `first` and not the last next.previous = nil end first = next else local previous = node.previous -- since `node` is not `first`, then we know `previous` is non-nil previous.next = next if next ~= nil then next.previous = previous end end end) end) end end --[=[ Returns a new Promise that resolves if the chained Promise resolves within `seconds` seconds, or rejects if execution time exceeds `seconds`. The chained Promise will be cancelled if the timeout is reached. Rejects with `rejectionValue` if it is non-nil. If a `rejectionValue` is not given, it will reject with a `Promise.Error(Promise.Error.Kind.TimedOut)`. This can be checked with [[Error.isKind]]. ```lua getSomething():timeout(5):andThen(function(something) -- got something and it only took at max 5 seconds end):catch(function(e) -- Either getting something failed or the time was exceeded. if Promise.Error.isKind(e, Promise.Error.Kind.TimedOut) then warn("Operation timed out!") else warn("Operation encountered an error!") end end) ``` Sugar for: ```lua Promise.race({ Promise.delay(seconds):andThen(function() return Promise.reject( rejectionValue == nil and Promise.Error.new({ kind = Promise.Error.Kind.TimedOut }) or rejectionValue ) end), promise }) ``` @param seconds number @param rejectionValue? any -- The value to reject with if the timeout is reached @return Promise ]=] function Promise.prototype:timeout(seconds, rejectionValue) local traceback = debug.traceback(nil, 2) return Promise.race({ Promise.delay(seconds):andThen(function() return Promise.reject(rejectionValue == nil and Error.new({ kind = Error.Kind.TimedOut, error = "Timed out", context = string.format( "Timeout of %d seconds exceeded.\n:timeout() called at:\n\n%s", seconds, traceback ), }) or rejectionValue) end), self, }) end --[=[ Returns the current Promise status. @return Status ]=] function Promise.prototype:getStatus() return self._status end --[[ Creates a new promise that receives the result of this promise. The given callbacks are invoked depending on that result. ]] function Promise.prototype:_andThen(traceback, successHandler, failureHandler) self._unhandledRejection = false -- If we are already cancelled, we return a cancelled Promise if self._status == Promise.Status.Cancelled then local promise = Promise.new(function() end) promise:cancel() return promise end -- Create a new promise to follow this part of the chain return Promise._new(traceback, function(resolve, reject, onCancel) -- Our default callbacks just pass values onto the next promise. -- This lets success and failure cascade correctly! local successCallback = resolve if successHandler then successCallback = createAdvancer(traceback, successHandler, resolve, reject) end local failureCallback = reject if failureHandler then failureCallback = createAdvancer(traceback, failureHandler, resolve, reject) end if self._status == Promise.Status.Started then -- If we haven't resolved yet, put ourselves into the queue table.insert(self._queuedResolve, successCallback) table.insert(self._queuedReject, failureCallback) onCancel(function() -- These are guaranteed to exist because the cancellation handler is guaranteed to only -- be called at most once if self._status == Promise.Status.Started then table.remove(self._queuedResolve, table.find(self._queuedResolve, successCallback)) table.remove(self._queuedReject, table.find(self._queuedReject, failureCallback)) end end) elseif self._status == Promise.Status.Resolved then -- This promise has already resolved! Trigger success immediately. successCallback(unpack(self._values, 1, self._valuesLength)) elseif self._status == Promise.Status.Rejected then -- This promise died a terrible death! Trigger failure immediately. failureCallback(unpack(self._values, 1, self._valuesLength)) end end, self) end --[=[ Chains onto an existing Promise and returns a new Promise. :::warning Within the failure handler, you should never assume that the rejection value is a string. Some rejections within the Promise library are represented by [[Error]] objects. If you want to treat it as a string for debugging, you should call `tostring` on it first. ::: You can return a Promise from the success or failure handler and it will be chained onto. Calling `andThen` on a cancelled Promise returns a cancelled Promise. :::tip If the Promise returned by `andThen` is cancelled, `successHandler` and `failureHandler` will not run. To run code no matter what, use [Promise:finally]. ::: @param successHandler (...: any) -> ...any @param failureHandler? (...: any) -> ...any @return Promise<...any> ]=] function Promise.prototype:andThen(successHandler, failureHandler) assert(successHandler == nil or isCallable(successHandler), string.format(ERROR_NON_FUNCTION, "Promise:andThen")) assert(failureHandler == nil or isCallable(failureHandler), string.format(ERROR_NON_FUNCTION, "Promise:andThen")) return self:_andThen(debug.traceback(nil, 2), successHandler, failureHandler) end --[=[ Shorthand for `Promise:andThen(nil, failureHandler)`. Returns a Promise that resolves if the `failureHandler` worked without encountering an additional error. :::warning Within the failure handler, you should never assume that the rejection value is a string. Some rejections within the Promise library are represented by [[Error]] objects. If you want to treat it as a string for debugging, you should call `tostring` on it first. ::: Calling `catch` on a cancelled Promise returns a cancelled Promise. :::tip If the Promise returned by `catch` is cancelled, `failureHandler` will not run. To run code no matter what, use [Promise:finally]. ::: @param failureHandler (...: any) -> ...any @return Promise<...any> ]=] function Promise.prototype:catch(failureHandler) assert(failureHandler == nil or isCallable(failureHandler), string.format(ERROR_NON_FUNCTION, "Promise:catch")) return self:_andThen(debug.traceback(nil, 2), nil, failureHandler) end --[=[ Similar to [Promise.andThen](#andThen), except the return value is the same as the value passed to the handler. In other words, you can insert a `:tap` into a Promise chain without affecting the value that downstream Promises receive. ```lua getTheValue() :tap(print) :andThen(function(theValue) print("Got", theValue, "even though print returns nil!") end) ``` If you return a Promise from the tap handler callback, its value will be discarded but `tap` will still wait until it resolves before passing the original value through. @param tapHandler (...: any) -> ...any @return Promise<...any> ]=] function Promise.prototype:tap(tapHandler) assert(isCallable(tapHandler), string.format(ERROR_NON_FUNCTION, "Promise:tap")) return self:_andThen(debug.traceback(nil, 2), function(...) local callbackReturn = tapHandler(...) if Promise.is(callbackReturn) then local length, values = pack(...) return callbackReturn:andThen(function() return unpack(values, 1, length) end) end return ... end) end --[=[ Attaches an `andThen` handler to this Promise that calls the given callback with the predefined arguments. The resolved value is discarded. ```lua promise:andThenCall(someFunction, "some", "arguments") ``` This is sugar for ```lua promise:andThen(function() return someFunction("some", "arguments") end) ``` @param callback (...: any) -> any @param ...? any -- Additional arguments which will be passed to `callback` @return Promise ]=] function Promise.prototype:andThenCall(callback, ...) assert(isCallable(callback), string.format(ERROR_NON_FUNCTION, "Promise:andThenCall")) local length, values = pack(...) return self:_andThen(debug.traceback(nil, 2), function() return callback(unpack(values, 1, length)) end) end --[=[ Attaches an `andThen` handler to this Promise that discards the resolved value and returns the given value from it. ```lua promise:andThenReturn("some", "values") ``` This is sugar for ```lua promise:andThen(function() return "some", "values" end) ``` :::caution Promises are eager, so if you pass a Promise to `andThenReturn`, it will begin executing before `andThenReturn` is reached in the chain. Likewise, if you pass a Promise created from [[Promise.reject]] into `andThenReturn`, it's possible that this will trigger the unhandled rejection warning. If you need to return a Promise, it's usually best practice to use [[Promise.andThen]]. ::: @param ... any -- Values to return from the function @return Promise ]=] function Promise.prototype:andThenReturn(...) local length, values = pack(...) return self:_andThen(debug.traceback(nil, 2), function() return unpack(values, 1, length) end) end --[=[ Cancels this promise, preventing the promise from resolving or rejecting. Does not do anything if the promise is already settled. Cancellations will propagate upwards and downwards through chained promises. Promises will only be cancelled if all of their consumers are also cancelled. This is to say that if you call `andThen` twice on the same promise, and you cancel only one of the child promises, it will not cancel the parent promise until the other child promise is also cancelled. ```lua promise:cancel() ``` ]=] function Promise.prototype:cancel() if self._status ~= Promise.Status.Started then return end self._status = Promise.Status.Cancelled if self._cancellationHook then self._cancellationHook() end coroutine.close(self._thread) if self._parent then self._parent:_consumerCancelled(self) end for child in pairs(self._consumers) do child:cancel() end self:_finalize() end --[[ Used to decrease the number of consumers by 1, and if there are no more, cancel this promise. ]] function Promise.prototype:_consumerCancelled(consumer) if self._status ~= Promise.Status.Started then return end self._consumers[consumer] = nil if next(self._consumers) == nil then self:cancel() end end --[[ Used to set a handler for when the promise resolves, rejects, or is cancelled. ]] function Promise.prototype:_finally(traceback, finallyHandler) self._unhandledRejection = false local promise = Promise._new(traceback, function(resolve, reject, onCancel) local handlerPromise onCancel(function() -- The finally Promise is not a proper consumer of self. We don't care about the resolved value. -- All we care about is running at the end. Therefore, if self has no other consumers, it's safe to -- cancel. We don't need to hold out cancelling just because there's a finally handler. self:_consumerCancelled(self) if handlerPromise then handlerPromise:cancel() end end) local finallyCallback = resolve if finallyHandler then finallyCallback = function(...) local callbackReturn = finallyHandler(...) if Promise.is(callbackReturn) then handlerPromise = callbackReturn callbackReturn :finally(function(status) if status ~= Promise.Status.Rejected then resolve(self) end end) :catch(function(...) reject(...) end) else resolve(self) end end end if self._status == Promise.Status.Started then -- The promise is not settled, so queue this. table.insert(self._queuedFinally, finallyCallback) else -- The promise already settled or was cancelled, run the callback now. finallyCallback(self._status) end end) return promise end --[=[ Set a handler that will be called regardless of the promise's fate. The handler is called when the promise is resolved, rejected, *or* cancelled. Returns a new Promise that: - resolves with the same values that this Promise resolves with. - rejects with the same values that this Promise rejects with. - is cancelled if this Promise is cancelled. If the value you return from the handler is a Promise: - We wait for the Promise to resolve, but we ultimately discard the resolved value. - If the returned Promise rejects, the Promise returned from `finally` will reject with the rejected value from the *returned* promise. - If the `finally` Promise is cancelled, and you returned a Promise from the handler, we cancel that Promise too. Otherwise, the return value from the `finally` handler is entirely discarded. :::note Cancellation As of Promise v4, `Promise:finally` does not count as a consumer of the parent Promise for cancellation purposes. This means that if all of a Promise's consumers are cancelled and the only remaining callbacks are finally handlers, the Promise is cancelled and the finally callbacks run then and there. Cancellation still propagates through the `finally` Promise though: if you cancel the `finally` Promise, it can cancel its parent Promise if it had no other consumers. Likewise, if the parent Promise is cancelled, the `finally` Promise will also be cancelled. ::: ```lua local thing = createSomething() doSomethingWith(thing) :andThen(function() print("It worked!") -- do something.. end) :catch(function() warn("Oh no it failed!") end) :finally(function() -- either way, destroy thing thing:Destroy() end) ``` @param finallyHandler (status: Status) -> ...any @return Promise<...any> ]=] function Promise.prototype:finally(finallyHandler) assert(finallyHandler == nil or isCallable(finallyHandler), string.format(ERROR_NON_FUNCTION, "Promise:finally")) return self:_finally(debug.traceback(nil, 2), finallyHandler) end --[=[ Same as `andThenCall`, except for `finally`. Attaches a `finally` handler to this Promise that calls the given callback with the predefined arguments. @param callback (...: any) -> any @param ...? any -- Additional arguments which will be passed to `callback` @return Promise ]=] function Promise.prototype:finallyCall(callback, ...) assert(isCallable(callback), string.format(ERROR_NON_FUNCTION, "Promise:finallyCall")) local length, values = pack(...) return self:_finally(debug.traceback(nil, 2), function() return callback(unpack(values, 1, length)) end) end --[=[ Attaches a `finally` handler to this Promise that discards the resolved value and returns the given value from it. ```lua promise:finallyReturn("some", "values") ``` This is sugar for ```lua promise:finally(function() return "some", "values" end) ``` @param ... any -- Values to return from the function @return Promise ]=] function Promise.prototype:finallyReturn(...) local length, values = pack(...) return self:_finally(debug.traceback(nil, 2), function() return unpack(values, 1, length) end) end --[=[ Yields the current thread until the given Promise completes. Returns the Promise's status, followed by the values that the promise resolved or rejected with. @yields @return Status -- The Status representing the fate of the Promise @return ...any -- The values the Promise resolved or rejected with. ]=] function Promise.prototype:awaitStatus() self._unhandledRejection = false if self._status == Promise.Status.Started then local thread = coroutine.running() self :finally(function() task.spawn(thread) end) -- The finally promise can propagate rejections, so we attach a catch handler to prevent the unhandled -- rejection warning from appearing :catch( function() end ) coroutine.yield() end if self._status == Promise.Status.Resolved then return self._status, unpack(self._values, 1, self._valuesLength) elseif self._status == Promise.Status.Rejected then return self._status, unpack(self._values, 1, self._valuesLength) end return self._status end local function awaitHelper(status, ...) return status == Promise.Status.Resolved, ... end --[=[ Yields the current thread until the given Promise completes. Returns true if the Promise resolved, followed by the values that the promise resolved or rejected with. :::caution If the Promise gets cancelled, this function will return `false`, which is indistinguishable from a rejection. If you need to differentiate, you should use [[Promise.awaitStatus]] instead. ::: ```lua local worked, value = getTheValue():await() if worked then print("got", value) else warn("it failed") end ``` @yields @return boolean -- `true` if the Promise successfully resolved @return ...any -- The values the Promise resolved or rejected with. ]=] function Promise.prototype:await() return awaitHelper(self:awaitStatus()) end local function expectHelper(status, ...) if status ~= Promise.Status.Resolved then error((...) == nil and "Expected Promise rejected with no value." or (...), 3) end return ... end --[=[ Yields the current thread until the given Promise completes. Returns the values that the promise resolved with. ```lua local worked = pcall(function() print("got", getTheValue():expect()) end) if not worked then warn("it failed") end ``` This is essentially sugar for: ```lua select(2, assert(promise:await())) ``` **Errors** if the Promise rejects or gets cancelled. @error any -- Errors with the rejection value if this Promise rejects or gets cancelled. @yields @return ...any -- The values the Promise resolved with. ]=] function Promise.prototype:expect() return expectHelper(self:awaitStatus()) end -- Backwards compatibility Promise.prototype.awaitValue = Promise.prototype.expect --[[ Intended for use in tests. Similar to await(), but instead of yielding if the promise is unresolved, _unwrap will throw. This indicates an assumption that a promise has resolved. ]] function Promise.prototype:_unwrap() if self._status == Promise.Status.Started then error("Promise has not resolved or rejected.", 2) end local success = self._status == Promise.Status.Resolved return success, unpack(self._values, 1, self._valuesLength) end function Promise.prototype:_resolve(...) if self._status ~= Promise.Status.Started then if Promise.is((...)) then (...):_consumerCancelled(self) end return end -- If the resolved value was a Promise, we chain onto it! if Promise.is((...)) then -- Without this warning, arguments sometimes mysteriously disappear if select("#", ...) > 1 then local message = string.format( "When returning a Promise from andThen, extra arguments are " .. "discarded! See:\n\n%s", self._source ) warn(message) end local chainedPromise = ... local promise = chainedPromise:andThen(function(...) self:_resolve(...) end, function(...) local maybeRuntimeError = chainedPromise._values[1] -- Backwards compatibility < v2 if chainedPromise._error then maybeRuntimeError = Error.new({ error = chainedPromise._error, kind = Error.Kind.ExecutionError, context = "[No stack trace available as this Promise originated from an older version of the Promise library (< v2)]", }) end if Error.isKind(maybeRuntimeError, Error.Kind.ExecutionError) then return self:_reject(maybeRuntimeError:extend({ error = "This Promise was chained to a Promise that errored.", trace = "", context = string.format( "The Promise at:\n\n%s\n...Rejected because it was chained to the following Promise, which encountered an error:\n", self._source ), })) end self:_reject(...) end) if promise._status == Promise.Status.Cancelled then self:cancel() elseif promise._status == Promise.Status.Started then -- Adopt ourselves into promise for cancellation propagation. self._parent = promise promise._consumers[self] = true end return end self._status = Promise.Status.Resolved self._valuesLength, self._values = pack(...) -- We assume that these callbacks will not throw errors. for _, callback in ipairs(self._queuedResolve) do coroutine.wrap(callback)(...) end self:_finalize() end function Promise.prototype:_reject(...) if self._status ~= Promise.Status.Started then return end self._status = Promise.Status.Rejected self._valuesLength, self._values = pack(...) -- If there are any rejection handlers, call those! if not isEmpty(self._queuedReject) then -- We assume that these callbacks will not throw errors. for _, callback in ipairs(self._queuedReject) do coroutine.wrap(callback)(...) end else -- At this point, no one was able to observe the error. -- An error handler might still be attached if the error occurred -- synchronously. We'll wait one tick, and if there are still no -- observers, then we should put a message in the console. local err = tostring((...)) coroutine.wrap(function() Promise._timeEvent:Wait() -- Someone observed the error, hooray! if not self._unhandledRejection then return end -- Build a reasonable message local message = string.format("Unhandled Promise rejection:\n\n%s\n\n%s", err, self._source) for _, callback in ipairs(Promise._unhandledRejectionCallbacks) do task.spawn(callback, self, unpack(self._values, 1, self._valuesLength)) end if Promise.TEST then -- Don't spam output when we're running tests. return end warn(message) end)() end self:_finalize() end --[[ Calls any :finally handlers. We need this to be a separate method and queue because we must call all of the finally callbacks upon a success, failure, *and* cancellation. ]] function Promise.prototype:_finalize() for _, callback in ipairs(self._queuedFinally) do -- Purposefully not passing values to callbacks here, as it could be the -- resolved values, or rejected errors. If the developer needs the values, -- they should use :andThen or :catch explicitly. coroutine.wrap(callback)(self._status) end self._queuedFinally = nil self._queuedReject = nil self._queuedResolve = nil -- Clear references to other Promises to allow gc if not Promise.TEST then self._parent = nil self._consumers = nil end task.defer(coroutine.close, self._thread) end --[=[ Chains a Promise from this one that is resolved if this Promise is already resolved, and rejected if it is not resolved at the time of calling `:now()`. This can be used to ensure your `andThen` handler occurs on the same frame as the root Promise execution. ```lua doSomething() :now() :andThen(function(value) print("Got", value, "synchronously.") end) ``` If this Promise is still running, Rejected, or Cancelled, the Promise returned from `:now()` will reject with the `rejectionValue` if passed, otherwise with a `Promise.Error(Promise.Error.Kind.NotResolvedInTime)`. This can be checked with [[Error.isKind]]. @param rejectionValue? any -- The value to reject with if the Promise isn't resolved @return Promise ]=] function Promise.prototype:now(rejectionValue) local traceback = debug.traceback(nil, 2) if self._status == Promise.Status.Resolved then return self:_andThen(traceback, function(...) return ... end) else return Promise.reject(rejectionValue == nil and Error.new({ kind = Error.Kind.NotResolvedInTime, error = "This Promise was not resolved in time for :now()", context = ":now() was called at:\n\n" .. traceback, }) or rejectionValue) end end --[=[ Repeatedly calls a Promise-returning function up to `times` number of times, until the returned Promise resolves. If the amount of retries is exceeded, the function will return the latest rejected Promise. ```lua local function canFail(a, b, c) return Promise.new(function(resolve, reject) -- do something that can fail local failed, thing = doSomethingThatCanFail(a, b, c) if failed then reject("it failed") else resolve(thing) end end) end local MAX_RETRIES = 10 local value = Promise.retry(canFail, MAX_RETRIES, "foo", "bar", "baz") -- args to send to canFail ``` @since 3.0.0 @param callback (...: P) -> Promise @param times number @param ...? P @return Promise ]=] function Promise.retry(callback, times, ...) assert(isCallable(callback), "Parameter #1 to Promise.retry must be a function") assert(type(times) == "number", "Parameter #2 to Promise.retry must be a number") local args, length = { ... }, select("#", ...) return Promise.resolve(callback(...)):catch(function(...) if times > 0 then return Promise.retry(callback, times - 1, unpack(args, 1, length)) else return Promise.reject(...) end end) end --[=[ Repeatedly calls a Promise-returning function up to `times` number of times, waiting `seconds` seconds between each retry, until the returned Promise resolves. If the amount of retries is exceeded, the function will return the latest rejected Promise. @since v3.2.0 @param callback (...: P) -> Promise @param times number @param seconds number @param ...? P @return Promise ]=] function Promise.retryWithDelay(callback, times, seconds, ...) assert(isCallable(callback), "Parameter #1 to Promise.retry must be a function") assert(type(times) == "number", "Parameter #2 (times) to Promise.retry must be a number") assert(type(seconds) == "number", "Parameter #3 (seconds) to Promise.retry must be a number") local args, length = { ... }, select("#", ...) return Promise.resolve(callback(...)):catch(function(...) if times > 0 then Promise.delay(seconds):await() return Promise.retryWithDelay(callback, times - 1, seconds, unpack(args, 1, length)) else return Promise.reject(...) end end) end --[=[ Converts an event into a Promise which resolves the next time the event fires. The optional `predicate` callback, if passed, will receive the event arguments and should return `true` or `false`, based on if this fired event should resolve the Promise or not. If `true`, the Promise resolves. If `false`, nothing happens and the predicate will be rerun the next time the event fires. The Promise will resolve with the event arguments. :::tip This function will work given any object with a `Connect` method. This includes all Roblox events. ::: ```lua -- Creates a Promise which only resolves when `somePart` is touched -- by a part named `"Something specific"`. return Promise.fromEvent(somePart.Touched, function(part) return part.Name == "Something specific" end) ``` @since 3.0.0 @param event Event -- Any object with a `Connect` method. This includes all Roblox events. @param predicate? (...: P) -> boolean -- A function which determines if the Promise should resolve with the given value, or wait for the next event to check again. @return Promise

]=] function Promise.fromEvent(event, predicate) predicate = predicate or function() return true end return Promise._new(debug.traceback(nil, 2), function(resolve, _, onCancel) local connection local shouldDisconnect = false local function disconnect() connection:Disconnect() connection = nil end -- We use shouldDisconnect because if the callback given to Connect is called before -- Connect returns, connection will still be nil. This happens with events that queue up -- events when there's nothing connected, such as RemoteEvents connection = event:Connect(function(...) local callbackValue = predicate(...) if callbackValue == true then resolve(...) if connection then disconnect() else shouldDisconnect = true end elseif type(callbackValue) ~= "boolean" then error("Promise.fromEvent predicate should always return a boolean") end end) if shouldDisconnect and connection then return disconnect() end onCancel(disconnect) end) end --[=[ Registers a callback that runs when an unhandled rejection happens. An unhandled rejection happens when a Promise is rejected, and the rejection is not observed with `:catch`. The callback is called with the actual promise that rejected, followed by the rejection values. @since v3.2.0 @param callback (promise: Promise, ...: any) -- A callback that runs when an unhandled rejection happens. @return () -> () -- Function that unregisters the `callback` when called ]=] function Promise.onUnhandledRejection(callback) table.insert(Promise._unhandledRejectionCallbacks, callback) return function() local index = table.find(Promise._unhandledRejectionCallbacks, callback) if index then table.remove(Promise._unhandledRejectionCallbacks, index) end end end return Promise ]]> init.spec jakebball_profileservice@1.5.0 profileservice -- local Madwork = _G.Madwork --[[ {Madwork} -[ProfileService]--------------------------------------- (STANDALONE VERSION) DataStore profiles - universal session-locked savable table API Official documentation: https://madstudioroblox.github.io/ProfileService/ DevForum discussion: https://devforum.roblox.com/t/ProfileService/667805 WARNINGS FOR "Profile.Data" VALUES: ! Do not create numeric tables with gaps - attempting to replicate such tables will result in an error; ! Do not create mixed tables (some values indexed by number and others by string key), as only the data indexed by number will be replicated. ! Do not index tables by anything other than numbers and strings. ! Do not reference Roblox Instances ! Do not reference userdata (Vector3, Color3, CFrame...) - Serialize userdata before referencing ! Do not reference functions WARNING: Calling ProfileStore:LoadProfileAsync() with a "profile_key" which wasn't released in the SAME SESSION will result in an error! If you want to "ProfileStore:LoadProfileAsync()" instead of using the already loaded profile, :Release() the old Profile object. Members: ProfileService.ServiceLocked [bool] ProfileService.IssueSignal [ScriptSignal] (error_message, profile_store_name, profile_key) ProfileService.CorruptionSignal [ScriptSignal] (profile_store_name, profile_key) ProfileService.CriticalStateSignal [ScriptSignal] (is_critical_state) Functions: ProfileService.GetProfileStore(profile_store_index, profile_template) --> [ProfileStore] profile_store_index [string] -- DataStore name OR profile_store_index [table]: -- Allows the developer to define more GlobalDataStore variables { Name = "StoreName", -- [string] -- DataStore name -- Optional arguments: Scope = "StoreScope", -- [string] -- DataStore scope } profile_template [table] -- Profiles will default to given table (hard-copy) when no data was saved previously ProfileService.IsLive() --> [bool] -- (CAN YIELD!!!) -- Returns true if ProfileService is connected to live Roblox DataStores Members [ProfileStore]: ProfileStore.Mock [ProfileStore] -- Reflection of ProfileStore methods, but the methods will use a mock DataStore Methods [ProfileStore]: ProfileStore:LoadProfileAsync(profile_key, not_released_handler) --> [Profile] or nil -- not_released_handler(place_id, game_job_id) profile_key [string] -- DataStore key not_released_handler nil or []: -- Defaults to "ForceLoad" [string] "ForceLoad" -- Force loads profile on first call OR [string] "Steal" -- Steals the profile ignoring it's session lock OR [function] (place_id, game_job_id) --> [string] "Repeat", "Cancel", "ForceLoad" or "Steal" place_id [number] or nil game_job_id [string] or nil -- not_released_handler [function] will be triggered in cases where the profile is not released by a session. This -- function may yield for as long as desirable and must return one of three string values: ["Repeat"] - ProfileService will repeat the profile loading proccess and may trigger the release handler again ["Cancel"] - ProfileStore:LoadProfileAsync() will immediately return nil ["ForceLoad"] - ProfileService will repeat the profile loading call, but will return Profile object afterwards and release the profile for another session that has loaded the profile ["Steal"] - The profile will usually be loaded immediately, ignoring an existing remote session lock and applying a session lock for this session. ProfileStore:GlobalUpdateProfileAsync(profile_key, update_handler) --> [GlobalUpdates] or nil -- Returns GlobalUpdates object if update was successful, otherwise returns nil profile_key [string] -- DataStore key update_handler [function] (global_updates [GlobalUpdates]) ProfileStore:ViewProfileAsync(profile_key, version) --> [Profile] or nil -- Reads profile without requesting a session lock; Data will not be saved and profile doesn't need to be released profile_key [string] -- DataStore key version nil or [string] -- DataStore key version ProfileStore:ProfileVersionQuery(profile_key, sort_direction, min_date, max_date) --> [ProfileVersionQuery] profile_key [string] sort_direction nil or [Enum.SortDirection] min_date nil or [DateTime] max_date nil or [DateTime] ProfileStore:WipeProfileAsync(profile_key) --> is_wipe_successful [bool] -- Completely wipes out profile data from the DataStore / mock DataStore with no way to recover it. * Parameter description for "ProfileStore:GlobalUpdateProfileAsync()": profile_key [string] -- DataStore key update_handler [function] (GlobalUpdates) -- This function gains access to GlobalUpdates object methods (update_handler can't yield) Methods [ProfileVersionQuery]: ProfileVersionQuery:NextAsync() --> [Profile] or nil -- (Yields) -- Returned profile has the same rules as profile returned by :ViewProfileAsync() Members [Profile]: Profile.Data [table] -- Writable table that gets saved automatically and once the profile is released Profile.MetaData [table] (Read-only) -- Information about this profile Profile.MetaData.ProfileCreateTime [number] (Read-only) -- os.time() timestamp of profile creation Profile.MetaData.SessionLoadCount [number] (Read-only) -- Amount of times the profile was loaded Profile.MetaData.ActiveSession [table] (Read-only) {place_id, game_job_id} / nil -- Set to a session link if a game session is currently having this profile loaded; nil if released Profile.MetaData.MetaTags [table] {["tag_name"] = tag_value, ...} -- Saved and auto-saved just like Profile.Data Profile.MetaData.MetaTagsLatest [table] (Read-only) -- Latest version of MetaData.MetaTags that was definetly saved to DataStore (You can use Profile.MetaData.MetaTagsLatest for product purchase save confirmation, but create a system to clear old tags after they pile up) Profile.MetaTagsUpdated [ScriptSignal] (meta_tags_latest) -- Fires after every auto-save, after -- Profile.MetaData.MetaTagsLatest has been updated with the version that's guaranteed to be saved; -- .MetaTagsUpdated will fire regardless of whether .MetaTagsLatest changed after update; -- .MetaTagsUpdated may fire after the Profile is released - changes to Profile.Data are not saved -- after release. Profile.RobloxMetaData [table] -- Writable table that gets saved automatically and once the profile is released Profile.UserIds [table] -- (Read-only) -- {user_id [number], ...} -- User ids associated with this profile Profile.KeyInfo [DataStoreKeyInfo] Profile.KeyInfoUpdated [ScriptSignal] (key_info [DataStoreKeyInfo]) Profile.GlobalUpdates [GlobalUpdates] Methods [Profile]: -- SAFE METHODS - Will not error after profile expires: Profile:IsActive() --> [bool] -- Returns true while the profile is active and can be written to Profile:GetMetaTag(tag_name) --> value [any] tag_name [string] Profile:Reconcile() -- Fills in missing (nil) [string_key] = [value] pairs to the Profile.Data structure Profile:ListenToRelease(listener) --> [ScriptConnection] (place_id / nil, game_job_id / nil) -- WARNING: Profiles can be released externally if another session force-loads -- this profile - use :ListenToRelease() to handle player leaving cleanup. Profile:Release() -- Call after the session has finished working with this profile e.g., after the player leaves (Profile object will become expired) (Does not yield) Profile:ListenToHopReady(listener) --> [ScriptConnection] () -- Passed listener will be executed after the releasing UpdateAsync call finishes; -- Wrap universe teleport requests with this method AFTER releasing the profile to improve session lock sharing between universe places; -- :ListenToHopReady() will usually call the listener in around a second, but may ocassionally take up to 7 seconds when a release happens -- next to an auto-update in regular usage scenarios. Profile:AddUserId(user_id) -- Associates user_id with profile (GDPR compliance) user_id [number] Profile:RemoveUserId(user_id) -- Unassociates user_id with profile (safe function) user_id [number] Profile:Identify() --> [string] -- Returns a string containing DataStore name, scope and key; Used for debug; -- Example return: "[Store:"GameData";Scope:"Live";Key:"Player_2312310"]" Profile:SetMetaTag(tag_name, value) -- Equivalent of Profile.MetaData.MetaTags[tag_name] = value tag_name [string] value [any] Profile:Save() -- Call to quickly progress global update state or to speed up save validation processes (Does not yield) -- VIEW-MODE ONLY: Profile:ClearGlobalUpdates() -- Clears all global updates data from a profile payload Profile:OverwriteAsync() -- (Yields) Saves the profile payload to the DataStore and removes the session lock Methods [GlobalUpdates]: -- ALWAYS PUBLIC: GlobalUpdates:GetActiveUpdates() --> [table] {{update_id, update_data [table]}, ...} GlobalUpdates:GetLockedUpdates() --> [table] {{update_id, update_data [table]}, ...} -- ONLY WHEN FROM "Profile.GlobalUpdates": GlobalUpdates:ListenToNewActiveUpdate(listener) --> [ScriptConnection] (update_id, update_data) update_data [table] GlobalUpdates:ListenToNewLockedUpdate(listener) --> [ScriptConnection] (update_id, update_data) update_data [table] GlobalUpdates:LockActiveUpdate(update_id) -- WARNING: will error after profile expires GlobalUpdates:ClearLockedUpdate(update_id) -- WARNING: will error after profile expires -- EXPOSED TO "update_handler" DURING ProfileStore:GlobalUpdateProfileAsync() CALL GlobalUpdates:AddActiveUpdate(update_data) update_data [table] GlobalUpdates:ChangeActiveUpdate(update_id, update_data) update_data [table] GlobalUpdates:ClearActiveUpdate(update_id) --]] local SETTINGS = { AutoSaveProfiles = 30, -- Seconds (This value may vary - ProfileService will split the auto save load evenly in the given time) RobloxWriteCooldown = 7, -- Seconds between successive DataStore calls for the same key ForceLoadMaxSteps = 8, -- Steps taken before ForceLoad request steals the active session for a profile AssumeDeadSessionLock = 30 * 60, -- (seconds) If a profile hasn't been updated for 30 minutes, assume the session lock is dead -- As of writing, os.time() is not completely reliable, so we can only assume session locks are dead after a significant amount of time. IssueCountForCriticalState = 5, -- Issues to collect to announce critical state IssueLast = 120, -- Seconds CriticalStateLast = 120, -- Seconds MetaTagsUpdatedValues = { -- Technical stuff - do not alter ProfileCreateTime = true, SessionLoadCount = true, ActiveSession = true, ForceLoadSession = true, LastUpdate = true, }, } local Madwork -- Standalone Madwork reference for portable version of ProfileService do local MadworkScriptSignal = {} local FreeRunnerThread = nil local function AcquireRunnerThreadAndCallEventHandler(fn, ...) local acquired_runner_thread = FreeRunnerThread FreeRunnerThread = nil fn(...) FreeRunnerThread = acquired_runner_thread end local function RunEventHandlerInFreeThread(...) AcquireRunnerThreadAndCallEventHandler(...) while true do AcquireRunnerThreadAndCallEventHandler(coroutine.yield()) end end -- ScriptConnection object: local ScriptConnection = { --[[ _listener = listener, _script_signal = script_signal, _disconnect_listener = disconnect_listener, _disconnect_param = disconnect_param, _next = next_script_connection, _is_connected = is_connected, --]] } ScriptConnection.__index = ScriptConnection function ScriptConnection:Disconnect() if self._is_connected == false then return end self._is_connected = false self._script_signal._listener_count -= 1 if self._script_signal._head == self then self._script_signal._head = self._next else local prev = self._script_signal._head while prev ~= nil and prev._next ~= self do prev = prev._next end if prev ~= nil then prev._next = self._next end end if self._disconnect_listener ~= nil then if not FreeRunnerThread then FreeRunnerThread = coroutine.create(RunEventHandlerInFreeThread) end task.spawn(FreeRunnerThread, self._disconnect_listener, self._disconnect_param) self._disconnect_listener = nil end end -- ScriptSignal object: local ScriptSignal = { --[[ _head = nil, _listener_count = 0, --]] } ScriptSignal.__index = ScriptSignal function ScriptSignal:Connect(listener, disconnect_listener, disconnect_param) --> [ScriptConnection] local script_connection = { _listener = listener, _script_signal = self, _disconnect_listener = disconnect_listener, _disconnect_param = disconnect_param, _next = self._head, _is_connected = true, } setmetatable(script_connection, ScriptConnection) self._head = script_connection self._listener_count += 1 return script_connection end function ScriptSignal:GetListenerCount() --> [number] return self._listener_count end function ScriptSignal:Fire(...) local item = self._head while item ~= nil do if item._is_connected == true then if not FreeRunnerThread then FreeRunnerThread = coroutine.create(RunEventHandlerInFreeThread) end task.spawn(FreeRunnerThread, item._listener, ...) end item = item._next end end function ScriptSignal:FireUntil(continue_callback, ...) local item = self._head while item ~= nil do if item._is_connected == true then item._listener(...) if continue_callback() ~= true then return end end item = item._next end end function MadworkScriptSignal.NewScriptSignal() --> [ScriptSignal] return { _head = nil, _listener_count = 0, Connect = ScriptSignal.Connect, GetListenerCount = ScriptSignal.GetListenerCount, Fire = ScriptSignal.Fire, FireUntil = ScriptSignal.FireUntil, } end -- Madwork framework namespace: Madwork = { NewScriptSignal = MadworkScriptSignal.NewScriptSignal, ConnectToOnClose = function(task, run_in_studio_mode) if game:GetService("RunService"):IsStudio() == false or run_in_studio_mode == true then game:BindToClose(task) end end, } end ----- Service Table ----- local ProfileService = { ServiceLocked = false, -- Set to true once the server is shutting down IssueSignal = Madwork.NewScriptSignal(), -- (error_message, profile_store_name, profile_key) -- Fired when a DataStore API call throws an error CorruptionSignal = Madwork.NewScriptSignal(), -- (profile_store_name, profile_key) -- Fired when DataStore key returns a value that has -- all or some of it's profile components set to invalid data types. E.g., accidentally setting Profile.Data to a noon table value CriticalState = false, -- Set to true while DataStore service is throwing too many errors CriticalStateSignal = Madwork.NewScriptSignal(), -- (is_critical_state) -- Fired when CriticalState is set to true -- (You may alert players with this, or set up analytics) ServiceIssueCount = 0, _active_profile_stores = {}, -- {profile_store, ...} _auto_save_list = {}, -- {profile, ...} -- loaded profile table which will be circularly auto-saved _issue_queue = {}, -- [table] {issue_time, ...} _critical_state_start = 0, -- [number] 0 = no critical state / os.clock() = critical state start -- Debug: _mock_data_store = {}, _user_mock_data_store = {}, _use_mock_data_store = false, } --[[ Saved profile structure: DataStoreProfile = { Data = {}, MetaData = { ProfileCreateTime = 0, SessionLoadCount = 0, ActiveSession = {place_id, game_job_id} / nil, ForceLoadSession = {place_id, game_job_id} / nil, MetaTags = {}, LastUpdate = 0, -- os.time() }, RobloxMetaData = {}, UserIds = {}, GlobalUpdates = { update_index, { {update_id, version_id, update_locked, update_data}, ... } }, } OR DataStoreProfile = { GlobalUpdates = { update_index, { {update_id, version_id, update_locked, update_data}, ... } }, } --]] ----- Private Variables ----- local ActiveProfileStores = ProfileService._active_profile_stores local AutoSaveList = ProfileService._auto_save_list local IssueQueue = ProfileService._issue_queue local DataStoreService = game:GetService("DataStoreService") local RunService = game:GetService("RunService") local PlaceId = game.PlaceId local JobId = game.JobId local AutoSaveIndex = 1 -- Next profile to auto save local LastAutoSave = os.clock() local LoadIndex = 0 local ActiveProfileLoadJobs = 0 -- Number of active threads that are loading in profiles local ActiveProfileSaveJobs = 0 -- Number of active threads that are saving profiles local CriticalStateStart = 0 -- os.clock() local IsStudio = RunService:IsStudio() local IsLiveCheckActive = false local UseMockDataStore = false local MockDataStore = ProfileService._mock_data_store -- Mock data store used when API access is disabled local UserMockDataStore = ProfileService._user_mock_data_store -- Separate mock data store accessed via ProfileStore.Mock local UseMockTag = {} local CustomWriteQueue = { --[[ [store] = { [key] = { LastWrite = os.clock(), Queue = {callback, ...}, CleanupJob = nil, }, ... }, ... --]] } ----- Utils ----- local function DeepCopyTable(t) local copy = {} for key, value in pairs(t) do if type(value) == "table" then copy[key] = DeepCopyTable(value) else copy[key] = value end end return copy end local function ReconcileTable(target, template) for k, v in pairs(template) do if type(k) == "string" then -- Only string keys will be reconciled if target[k] == nil then if type(v) == "table" then target[k] = DeepCopyTable(v) else target[k] = v end elseif type(target[k]) == "table" and type(v) == "table" then ReconcileTable(target[k], v) end end end end ----- Private functions ----- local function IdentifyProfile(store_name, store_scope, key) return string.format( "[Store:\"%s\";%sKey:\"%s\"]", store_name, store_scope ~= nil and string.format("Scope:\"%s\";", store_scope) or "", key ) end local function CustomWriteQueueCleanup(store, key) if CustomWriteQueue[store] ~= nil then CustomWriteQueue[store][key] = nil if next(CustomWriteQueue[store]) == nil then CustomWriteQueue[store] = nil end end end local function CustomWriteQueueMarkForCleanup(store, key) if CustomWriteQueue[store] ~= nil then if CustomWriteQueue[store][key] ~= nil then local queue_data = CustomWriteQueue[store][key] local queue = queue_data.Queue if queue_data.CleanupJob == nil then queue_data.CleanupJob = RunService.Heartbeat:Connect(function() if os.clock() - queue_data.LastWrite > SETTINGS.RobloxWriteCooldown and #queue == 0 then queue_data.CleanupJob:Disconnect() CustomWriteQueueCleanup(store, key) end end) end elseif next(CustomWriteQueue[store]) == nil then CustomWriteQueue[store] = nil end end end local function CustomWriteQueueAsync(callback, store, key) --> ... -- Passed return from callback if CustomWriteQueue[store] == nil then CustomWriteQueue[store] = {} end if CustomWriteQueue[store][key] == nil then CustomWriteQueue[store][key] = {LastWrite = 0, Queue = {}, CleanupJob = nil} end local queue_data = CustomWriteQueue[store][key] local queue = queue_data.Queue -- Cleanup job: if queue_data.CleanupJob ~= nil then queue_data.CleanupJob:Disconnect() queue_data.CleanupJob = nil end -- Queue logic: if os.clock() - queue_data.LastWrite > SETTINGS.RobloxWriteCooldown and #queue == 0 then queue_data.LastWrite = os.clock() return callback() else table.insert(queue, callback) while true do if os.clock() - queue_data.LastWrite > SETTINGS.RobloxWriteCooldown and queue[1] == callback then table.remove(queue, 1) queue_data.LastWrite = os.clock() return callback() end task.wait() end end end local function IsCustomWriteQueueEmptyFor(store, key) --> is_empty [bool] local lookup = CustomWriteQueue[store] if lookup ~= nil then lookup = lookup[key] return lookup == nil or #lookup.Queue == 0 end return true end local function WaitForLiveAccessCheck() -- This function was created to prevent the ProfileService module yielding execution when required while IsLiveCheckActive == true do task.wait() end end local function WaitForPendingProfileStore(profile_store) while profile_store._is_pending == true do task.wait() end end local function RegisterIssue(error_message, store_name, store_scope, profile_key) -- Called when a DataStore API call errors warn("[ProfileService]: DataStore API error " .. IdentifyProfile(store_name, store_scope, profile_key) .. " - \"" .. tostring(error_message) .. "\"") table.insert(IssueQueue, os.clock()) -- Adding issue time to queue ProfileService.IssueSignal:Fire(tostring(error_message), store_name, profile_key) end local function RegisterCorruption(store_name, store_scope, profile_key) -- Called when a corrupted profile is loaded warn("[ProfileService]: Resolved profile corruption " .. IdentifyProfile(store_name, store_scope, profile_key)) ProfileService.CorruptionSignal:Fire(store_name, profile_key) end local function NewMockDataStoreKeyInfo(params) local version_id_string = tostring(params.VersionId or 0) local meta_data = params.MetaData or {} local user_ids = params.UserIds or {} return { CreatedTime = params.CreatedTime, UpdatedTime = params.UpdatedTime, Version = string.rep("0", 16) .. "." .. string.rep("0", 10 - string.len(version_id_string)) .. version_id_string .. "." .. string.rep("0", 16) .. "." .. "01", GetMetadata = function() return DeepCopyTable(meta_data) end, GetUserIds = function() return DeepCopyTable(user_ids) end, } end local function MockUpdateAsync(mock_data_store, profile_store_name, key, transform_function, is_get_call) --> loaded_data, key_info local profile_store = mock_data_store[profile_store_name] if profile_store == nil then profile_store = {} mock_data_store[profile_store_name] = profile_store end local epoch_time = math.floor(os.time() * 1000) local mock_entry = profile_store[key] local mock_entry_was_nil = false if mock_entry == nil then mock_entry_was_nil = true if is_get_call ~= true then mock_entry = { Data = nil, CreatedTime = epoch_time, UpdatedTime = epoch_time, VersionId = 0, UserIds = {}, MetaData = {}, } profile_store[key] = mock_entry end end local mock_key_info = mock_entry_was_nil == false and NewMockDataStoreKeyInfo(mock_entry) or nil local transform, user_ids, roblox_meta_data = transform_function(mock_entry and mock_entry.Data, mock_key_info) if transform == nil then return nil else if mock_entry ~= nil and is_get_call ~= true then mock_entry.Data = transform mock_entry.UserIds = DeepCopyTable(user_ids or {}) mock_entry.MetaData = DeepCopyTable(roblox_meta_data or {}) mock_entry.VersionId += 1 mock_entry.UpdatedTime = epoch_time end return DeepCopyTable(transform), mock_entry ~= nil and NewMockDataStoreKeyInfo(mock_entry) or nil end end local function IsThisSession(session_tag) return session_tag[1] == PlaceId and session_tag[2] == JobId end --[[ update_settings = { ExistingProfileHandle = function(latest_data), MissingProfileHandle = function(latest_data), EditProfile = function(lastest_data), } --]] local function StandardProfileUpdateAsyncDataStore(profile_store, profile_key, update_settings, is_user_mock, is_get_call, version) --> loaded_data, key_info local loaded_data, key_info local success, error_message = pcall(function() local transform_function = function(latest_data) local missing_profile = false local data_corrupted = false local global_updates_data = {0, {}} if latest_data == nil then missing_profile = true elseif type(latest_data) ~= "table" then missing_profile = true data_corrupted = true end if type(latest_data) == "table" then -- Case #1: Profile was loaded if type(latest_data.Data) == "table" and type(latest_data.MetaData) == "table" and type(latest_data.GlobalUpdates) == "table" then latest_data.WasCorrupted = false -- Must be set to false if set previously global_updates_data = latest_data.GlobalUpdates if update_settings.ExistingProfileHandle ~= nil then update_settings.ExistingProfileHandle(latest_data) end -- Case #2: Profile was not loaded but GlobalUpdate data exists elseif latest_data.Data == nil and latest_data.MetaData == nil and type(latest_data.GlobalUpdates) == "table" then latest_data.WasCorrupted = false -- Must be set to false if set previously global_updates_data = latest_data.GlobalUpdates or global_updates_data missing_profile = true else missing_profile = true data_corrupted = true end end -- Case #3: Profile was not created or corrupted and no GlobalUpdate data exists if missing_profile == true then latest_data = { -- Data = nil, -- MetaData = nil, GlobalUpdates = global_updates_data, } if update_settings.MissingProfileHandle ~= nil then update_settings.MissingProfileHandle(latest_data) end end -- Editing profile: if update_settings.EditProfile ~= nil then update_settings.EditProfile(latest_data) end -- Data corruption handling (Silently override with empty profile) (Also run Case #1) if data_corrupted == true then latest_data.WasCorrupted = true -- Temporary tag that will be removed on first save end return latest_data, latest_data.UserIds, latest_data.RobloxMetaData end if is_user_mock == true then -- Used when the profile is accessed through ProfileStore.Mock loaded_data, key_info = MockUpdateAsync(UserMockDataStore, profile_store._profile_store_lookup, profile_key, transform_function, is_get_call) task.wait() -- Simulate API call yield elseif UseMockDataStore == true then -- Used when API access is disabled loaded_data, key_info = MockUpdateAsync(MockDataStore, profile_store._profile_store_lookup, profile_key, transform_function, is_get_call) task.wait() -- Simulate API call yield else loaded_data, key_info = CustomWriteQueueAsync( function() -- Callback if is_get_call == true then local get_data, get_key_info if version ~= nil then local success, error_message = pcall(function() get_data, get_key_info = profile_store._global_data_store:GetVersionAsync(profile_key, version) end) if success == false and type(error_message) == "string" and string.find(error_message, "not valid") ~= nil then warn("[ProfileService]: Passed version argument is not valid; Traceback:\n" .. debug.traceback()) end else get_data, get_key_info = profile_store._global_data_store:GetAsync(profile_key) end get_data = transform_function(get_data) return get_data, get_key_info else return profile_store._global_data_store:UpdateAsync(profile_key, transform_function) end end, profile_store._profile_store_lookup, -- Store profile_key -- Key ) end end) if success == true and type(loaded_data) == "table" then -- Corruption handling: if loaded_data.WasCorrupted == true and is_get_call ~= true then RegisterCorruption( profile_store._profile_store_name, profile_store._profile_store_scope, profile_key ) end -- Return loaded_data: return loaded_data, key_info else RegisterIssue( (error_message ~= nil) and error_message or "Undefined error", profile_store._profile_store_name, profile_store._profile_store_scope, profile_key ) -- Return nothing: return nil end end local function RemoveProfileFromAutoSave(profile) local auto_save_index = table.find(AutoSaveList, profile) if auto_save_index ~= nil then table.remove(AutoSaveList, auto_save_index) if auto_save_index < AutoSaveIndex then AutoSaveIndex = AutoSaveIndex - 1 -- Table contents were moved left before AutoSaveIndex so move AutoSaveIndex left as well end if AutoSaveList[AutoSaveIndex] == nil then -- AutoSaveIndex was at the end of the AutoSaveList - reset to 1 AutoSaveIndex = 1 end end end local function AddProfileToAutoSave(profile) -- Notice: Makes sure this profile isn't auto-saved too soon -- Add at AutoSaveIndex and move AutoSaveIndex right: table.insert(AutoSaveList, AutoSaveIndex, profile) if #AutoSaveList > 1 then AutoSaveIndex = AutoSaveIndex + 1 elseif #AutoSaveList == 1 then -- First profile created - make sure it doesn't get immediately auto saved: LastAutoSave = os.clock() end end local function ReleaseProfileInternally(profile) -- 1) Remove profile object from ProfileService references: -- -- Clear reference in ProfileStore: local profile_store = profile._profile_store local loaded_profiles = profile._is_user_mock == true and profile_store._mock_loaded_profiles or profile_store._loaded_profiles loaded_profiles[profile._profile_key] = nil if next(profile_store._loaded_profiles) == nil and next(profile_store._mock_loaded_profiles) == nil then -- ProfileStore has turned inactive local index = table.find(ActiveProfileStores, profile_store) if index ~= nil then table.remove(ActiveProfileStores, index) end end -- Clear auto update reference: RemoveProfileFromAutoSave(profile) -- 2) Trigger release listeners: -- local place_id local game_job_id local active_session = profile.MetaData.ActiveSession if active_session ~= nil then place_id = active_session[1] game_job_id = active_session[2] end profile._release_listeners:Fire(place_id, game_job_id) end local function CheckForNewGlobalUpdates(profile, old_global_updates_data, new_global_updates_data) local global_updates_object = profile.GlobalUpdates -- [GlobalUpdates] local pending_update_lock = global_updates_object._pending_update_lock -- {update_id, ...} local pending_update_clear = global_updates_object._pending_update_clear -- {update_id, ...} -- "old_" or "new_" global_updates_data = {update_index, {{update_id, version_id, update_locked, update_data}, ...}} for _, new_global_update in ipairs(new_global_updates_data[2]) do -- Find old global update with the same update_id: local old_global_update for _, global_update in ipairs(old_global_updates_data[2]) do if global_update[1] == new_global_update[1] then old_global_update = global_update break end end -- A global update is new when it didn't exist before or its version_id or update_locked state changed: local is_new = false if old_global_update == nil or new_global_update[2] > old_global_update[2] or new_global_update[3] ~= old_global_update[3] then is_new = true end if is_new == true then -- Active global updates: if new_global_update[3] == false then -- Check if update is not pending to be locked: (Preventing firing new active update listeners more than necessary) local is_pending_lock = false for _, update_id in ipairs(pending_update_lock) do if new_global_update[1] == update_id then is_pending_lock = true break end end if is_pending_lock == false then -- Trigger new active update listeners: global_updates_object._new_active_update_listeners:Fire(new_global_update[1], new_global_update[4]) end end -- Locked global updates: if new_global_update[3] == true then -- Check if update is not pending to be cleared: (Preventing firing new locked update listeners after marking a locked update for clearing) local is_pending_clear = false for _, update_id in ipairs(pending_update_clear) do if new_global_update[1] == update_id then is_pending_clear = true break end end if is_pending_clear == false then -- Trigger new locked update listeners: global_updates_object._new_locked_update_listeners:FireUntil( function() -- Check if listener marked the update to be cleared: -- Normally there should be only one listener per profile for new locked global updates, but -- in case several listeners are connected we will not trigger more listeners after one listener -- marks the locked global update to be cleared. return table.find(pending_update_clear, new_global_update[1]) == nil end, new_global_update[1], new_global_update[4] ) end end end end end local function SaveProfileAsync(profile, release_from_session, is_overwriting) if type(profile.Data) ~= "table" then RegisterCorruption( profile._profile_store._profile_store_name, profile._profile_store._profile_store_scope, profile._profile_key ) error("[ProfileService]: PROFILE DATA CORRUPTED DURING RUNTIME! Profile: " .. profile:Identify()) end if release_from_session == true and is_overwriting ~= true then ReleaseProfileInternally(profile) end ActiveProfileSaveJobs = ActiveProfileSaveJobs + 1 local last_session_load_count = profile.MetaData.SessionLoadCount -- Compare "SessionLoadCount" when writing to profile to prevent a rare case of repeat last save when the profile is loaded on the same server again local repeat_save_flag = true -- Released Profile save calls have to repeat until they succeed while repeat_save_flag == true do if release_from_session ~= true then repeat_save_flag = false end local loaded_data, key_info = StandardProfileUpdateAsyncDataStore( profile._profile_store, profile._profile_key, { ExistingProfileHandle = nil, MissingProfileHandle = nil, EditProfile = function(latest_data) local session_owns_profile = false local force_load_pending = false if is_overwriting ~= true then -- 1) Check if this session still owns the profile: -- local active_session = latest_data.MetaData.ActiveSession local force_load_session = latest_data.MetaData.ForceLoadSession local session_load_count = latest_data.MetaData.SessionLoadCount if type(active_session) == "table" then session_owns_profile = IsThisSession(active_session) and session_load_count == last_session_load_count end if type(force_load_session) == "table" then force_load_pending = not IsThisSession(force_load_session) end else session_owns_profile = true end if session_owns_profile == true then -- We may only edit the profile if this session has ownership of the profile if is_overwriting ~= true then -- 2) Manage global updates: -- local latest_global_updates_data = latest_data.GlobalUpdates -- {update_index, {{update_id, version_id, update_locked, update_data}, ...}} local latest_global_updates_list = latest_global_updates_data[2] local global_updates_object = profile.GlobalUpdates -- [GlobalUpdates] local pending_update_lock = global_updates_object._pending_update_lock -- {update_id, ...} local pending_update_clear = global_updates_object._pending_update_clear -- {update_id, ...} -- Active update locking: for i = 1, #latest_global_updates_list do for _, lock_id in ipairs(pending_update_lock) do if latest_global_updates_list[i][1] == lock_id then latest_global_updates_list[i][3] = true break end end end -- Locked update clearing: for _, clear_id in ipairs(pending_update_clear) do for i = 1, #latest_global_updates_list do if latest_global_updates_list[i][1] == clear_id and latest_global_updates_list[i][3] == true then table.remove(latest_global_updates_list, i) break end end end end -- 3) Save profile data: -- latest_data.Data = profile.Data latest_data.RobloxMetaData = profile.RobloxMetaData latest_data.UserIds = profile.UserIds if is_overwriting ~= true then latest_data.MetaData.MetaTags = profile.MetaData.MetaTags -- MetaData.MetaTags is the only actively savable component of MetaData latest_data.MetaData.LastUpdate = os.time() if release_from_session == true or force_load_pending == true then latest_data.MetaData.ActiveSession = nil end else latest_data.MetaData = profile.MetaData latest_data.MetaData.ActiveSession = nil latest_data.MetaData.ForceLoadSession = nil latest_data.GlobalUpdates = profile.GlobalUpdates._updates_latest end end end, }, profile._is_user_mock ) if loaded_data ~= nil and key_info ~= nil then if is_overwriting == true then break end repeat_save_flag = false -- 4) Set latest data in profile: -- -- Updating DataStoreKeyInfo: profile.KeyInfo = key_info -- Setting global updates: local global_updates_object = profile.GlobalUpdates -- [GlobalUpdates] local old_global_updates_data = global_updates_object._updates_latest local new_global_updates_data = loaded_data.GlobalUpdates global_updates_object._updates_latest = new_global_updates_data -- Setting MetaData: local session_meta_data = profile.MetaData local latest_meta_data = loaded_data.MetaData for key in pairs(SETTINGS.MetaTagsUpdatedValues) do session_meta_data[key] = latest_meta_data[key] end session_meta_data.MetaTagsLatest = latest_meta_data.MetaTags -- 5) Check if session still owns the profile: -- local active_session = loaded_data.MetaData.ActiveSession local session_load_count = loaded_data.MetaData.SessionLoadCount local session_owns_profile = false if type(active_session) == "table" then session_owns_profile = IsThisSession(active_session) and session_load_count == last_session_load_count end local is_active = profile:IsActive() if session_owns_profile == true then -- 6) Check for new global updates: -- if is_active == true then -- Profile could've been released before the saving thread finished CheckForNewGlobalUpdates(profile, old_global_updates_data, new_global_updates_data) end else -- Session no longer owns the profile: -- 7) Release profile if it hasn't been released yet: -- if is_active == true then ReleaseProfileInternally(profile) end -- Cleanup reference in custom write queue: CustomWriteQueueMarkForCleanup(profile._profile_store._profile_store_lookup, profile._profile_key) -- Hop ready listeners: if profile._hop_ready == false then profile._hop_ready = true profile._hop_ready_listeners:Fire() end end -- Signaling MetaTagsUpdated listeners after a possible external profile release was handled: profile.MetaTagsUpdated:Fire(profile.MetaData.MetaTagsLatest) -- Signaling KeyInfoUpdated listeners: profile.KeyInfoUpdated:Fire(key_info) elseif repeat_save_flag == true then task.wait() -- Prevent infinite loop in case DataStore API does not yield end end ActiveProfileSaveJobs = ActiveProfileSaveJobs - 1 end ----- Public functions ----- -- GlobalUpdates object: local GlobalUpdates = { --[[ _updates_latest = {}, -- [table] {update_index, {{update_id, version_id, update_locked, update_data}, ...}} _pending_update_lock = {update_id, ...} / nil, -- [table / nil] _pending_update_clear = {update_id, ...} / nil, -- [table / nil] _new_active_update_listeners = [ScriptSignal] / nil, -- [table / nil] _new_locked_update_listeners = [ScriptSignal] / nil, -- [table / nil] _profile = Profile / nil, -- [Profile / nil] _update_handler_mode = true / nil, -- [bool / nil] --]] } GlobalUpdates.__index = GlobalUpdates -- ALWAYS PUBLIC: function GlobalUpdates:GetActiveUpdates() --> [table] {{update_id, update_data}, ...} local query_list = {} for _, global_update in ipairs(self._updates_latest[2]) do if global_update[3] == false then local is_pending_lock = false if self._pending_update_lock ~= nil then for _, update_id in ipairs(self._pending_update_lock) do if global_update[1] == update_id then is_pending_lock = true -- Exclude global updates pending to be locked break end end end if is_pending_lock == false then table.insert(query_list, {global_update[1], global_update[4]}) end end end return query_list end function GlobalUpdates:GetLockedUpdates() --> [table] {{update_id, update_data}, ...} local query_list = {} for _, global_update in ipairs(self._updates_latest[2]) do if global_update[3] == true then local is_pending_clear = false if self._pending_update_clear ~= nil then for _, update_id in ipairs(self._pending_update_clear) do if global_update[1] == update_id then is_pending_clear = true -- Exclude global updates pending to be cleared break end end end if is_pending_clear == false then table.insert(query_list, {global_update[1], global_update[4]}) end end end return query_list end -- ONLY WHEN FROM "Profile.GlobalUpdates": function GlobalUpdates:ListenToNewActiveUpdate(listener) --> [ScriptConnection] listener(update_id, update_data) if type(listener) ~= "function" then error("[ProfileService]: Only a function can be set as listener in GlobalUpdates:ListenToNewActiveUpdate()") end local profile = self._profile if self._update_handler_mode == true then error("[ProfileService]: Can't listen to new global updates in ProfileStore:GlobalUpdateProfileAsync()") elseif self._new_active_update_listeners == nil then error("[ProfileService]: Can't listen to new global updates in view mode") elseif profile:IsActive() == false then -- Check if profile is expired return { -- Do not connect listener if the profile is expired Disconnect = function() end, } end -- Connect listener: return self._new_active_update_listeners:Connect(listener) end function GlobalUpdates:ListenToNewLockedUpdate(listener) --> [ScriptConnection] listener(update_id, update_data) if type(listener) ~= "function" then error("[ProfileService]: Only a function can be set as listener in GlobalUpdates:ListenToNewLockedUpdate()") end local profile = self._profile if self._update_handler_mode == true then error("[ProfileService]: Can't listen to new global updates in ProfileStore:GlobalUpdateProfileAsync()") elseif self._new_locked_update_listeners == nil then error("[ProfileService]: Can't listen to new global updates in view mode") elseif profile:IsActive() == false then -- Check if profile is expired return { -- Do not connect listener if the profile is expired Disconnect = function() end, } end -- Connect listener: return self._new_locked_update_listeners:Connect(listener) end function GlobalUpdates:LockActiveUpdate(update_id) if type(update_id) ~= "number" then error("[ProfileService]: Invalid update_id") end local profile = self._profile if self._update_handler_mode == true then error("[ProfileService]: Can't lock active global updates in ProfileStore:GlobalUpdateProfileAsync()") elseif self._pending_update_lock == nil then error("[ProfileService]: Can't lock active global updates in view mode") elseif profile:IsActive() == false then -- Check if profile is expired error("[ProfileService]: PROFILE EXPIRED - Can't lock active global updates") end -- Check if global update exists with given update_id local global_update_exists = nil for _, global_update in ipairs(self._updates_latest[2]) do if global_update[1] == update_id then global_update_exists = global_update break end end if global_update_exists ~= nil then local is_pending_lock = false for _, lock_update_id in ipairs(self._pending_update_lock) do if update_id == lock_update_id then is_pending_lock = true -- Exclude global updates pending to be locked break end end if is_pending_lock == false and global_update_exists[3] == false then -- Avoid id duplicates in _pending_update_lock table.insert(self._pending_update_lock, update_id) end else error("[ProfileService]: Passed non-existant update_id") end end function GlobalUpdates:ClearLockedUpdate(update_id) if type(update_id) ~= "number" then error("[ProfileService]: Invalid update_id") end local profile = self._profile if self._update_handler_mode == true then error("[ProfileService]: Can't clear locked global updates in ProfileStore:GlobalUpdateProfileAsync()") elseif self._pending_update_clear == nil then error("[ProfileService]: Can't clear locked global updates in view mode") elseif profile:IsActive() == false then -- Check if profile is expired error("[ProfileService]: PROFILE EXPIRED - Can't clear locked global updates") end -- Check if global update exists with given update_id local global_update_exists = nil for _, global_update in ipairs(self._updates_latest[2]) do if global_update[1] == update_id then global_update_exists = global_update break end end if global_update_exists ~= nil then local is_pending_clear = false for _, clear_update_id in ipairs(self._pending_update_clear) do if update_id == clear_update_id then is_pending_clear = true -- Exclude global updates pending to be cleared break end end if is_pending_clear == false and global_update_exists[3] == true then -- Avoid id duplicates in _pending_update_clear table.insert(self._pending_update_clear, update_id) end else error("[ProfileService]: Passed non-existant update_id") end end -- EXPOSED TO "update_handler" DURING ProfileStore:GlobalUpdateProfileAsync() CALL function GlobalUpdates:AddActiveUpdate(update_data) if type(update_data) ~= "table" then error("[ProfileService]: Invalid update_data") end if self._new_active_update_listeners ~= nil then error("[ProfileService]: Can't add active global updates in loaded Profile; Use ProfileStore:GlobalUpdateProfileAsync()") elseif self._update_handler_mode ~= true then error("[ProfileService]: Can't add active global updates in view mode; Use ProfileStore:GlobalUpdateProfileAsync()") end -- self._updates_latest = {}, -- [table] {update_index, {{update_id, version_id, update_locked, update_data}, ...}} local updates_latest = self._updates_latest local update_index = updates_latest[1] + 1 -- Incrementing global update index updates_latest[1] = update_index -- Add new active global update: table.insert(updates_latest[2], {update_index, 1, false, update_data}) end function GlobalUpdates:ChangeActiveUpdate(update_id, update_data) if type(update_id) ~= "number" then error("[ProfileService]: Invalid update_id") end if type(update_data) ~= "table" then error("[ProfileService]: Invalid update_data") end if self._new_active_update_listeners ~= nil then error("[ProfileService]: Can't change active global updates in loaded Profile; Use ProfileStore:GlobalUpdateProfileAsync()") elseif self._update_handler_mode ~= true then error("[ProfileService]: Can't change active global updates in view mode; Use ProfileStore:GlobalUpdateProfileAsync()") end -- self._updates_latest = {}, -- [table] {update_index, {{update_id, version_id, update_locked, update_data}, ...}} local updates_latest = self._updates_latest local get_global_update = nil for _, global_update in ipairs(updates_latest[2]) do if update_id == global_update[1] then get_global_update = global_update break end end if get_global_update ~= nil then if get_global_update[3] == true then error("[ProfileService]: Can't change locked global update") end get_global_update[2] = get_global_update[2] + 1 -- Increment version id get_global_update[4] = update_data -- Set new global update data else error("[ProfileService]: Passed non-existant update_id") end end function GlobalUpdates:ClearActiveUpdate(update_id) if type(update_id) ~= "number" then error("[ProfileService]: Invalid update_id argument") end if self._new_active_update_listeners ~= nil then error("[ProfileService]: Can't clear active global updates in loaded Profile; Use ProfileStore:GlobalUpdateProfileAsync()") elseif self._update_handler_mode ~= true then error("[ProfileService]: Can't clear active global updates in view mode; Use ProfileStore:GlobalUpdateProfileAsync()") end -- self._updates_latest = {}, -- [table] {update_index, {{update_id, version_id, update_locked, update_data}, ...}} local updates_latest = self._updates_latest local get_global_update_index = nil local get_global_update = nil for index, global_update in ipairs(updates_latest[2]) do if update_id == global_update[1] then get_global_update_index = index get_global_update = global_update break end end if get_global_update ~= nil then if get_global_update[3] == true then error("[ProfileService]: Can't clear locked global update") end table.remove(updates_latest[2], get_global_update_index) -- Remove active global update else error("[ProfileService]: Passed non-existant update_id") end end -- Profile object: local Profile = { --[[ Data = {}, -- [table] -- Loaded once after ProfileStore:LoadProfileAsync() finishes MetaData = {}, -- [table] -- Updated with every auto-save GlobalUpdates = GlobalUpdates, -- [GlobalUpdates] _profile_store = ProfileStore, -- [ProfileStore] _profile_key = "", -- [string] _release_listeners = [ScriptSignal] / nil, -- [table / nil] _hop_ready_listeners = [ScriptSignal] / nil, -- [table / nil] _hop_ready = false, _view_mode = true / nil, -- [bool] or nil _load_timestamp = os.clock(), _is_user_mock = false, -- ProfileStore.Mock _mock_key_info = {}, --]] } Profile.__index = Profile function Profile:IsActive() --> [bool] local loaded_profiles = self._is_user_mock == true and self._profile_store._mock_loaded_profiles or self._profile_store._loaded_profiles return loaded_profiles[self._profile_key] == self end function Profile:GetMetaTag(tag_name) --> value local meta_data = self.MetaData if meta_data == nil then return nil -- error("[ProfileService]: This Profile hasn't been loaded before - MetaData not available") end return self.MetaData.MetaTags[tag_name] end function Profile:SetMetaTag(tag_name, value) if type(tag_name) ~= "string" then error("[ProfileService]: tag_name must be a string") elseif string.len(tag_name) == 0 then error("[ProfileService]: Invalid tag_name") end self.MetaData.MetaTags[tag_name] = value end function Profile:Reconcile() ReconcileTable(self.Data, self._profile_store._profile_template) end function Profile:ListenToRelease(listener) --> [ScriptConnection] (place_id / nil, game_job_id / nil) if type(listener) ~= "function" then error("[ProfileService]: Only a function can be set as listener in Profile:ListenToRelease()") end if self._view_mode == true then return {Disconnect = function() end} end if self:IsActive() == false then -- Call release listener immediately if profile is expired local place_id local game_job_id local active_session = self.MetaData.ActiveSession if active_session ~= nil then place_id = active_session[1] game_job_id = active_session[2] end listener(place_id, game_job_id) return {Disconnect = function() end} else return self._release_listeners:Connect(listener) end end function Profile:Save() if self._view_mode == true then error("[ProfileService]: Can't save Profile in view mode - Should you be calling :OverwriteAsync() instead?") end if self:IsActive() == false then warn("[ProfileService]: Attempted saving an inactive profile " .. self:Identify() .. "; Traceback:\n" .. debug.traceback()) return end -- Reject save request if a save is already pending in the queue - this will prevent the user from -- unecessary API request spam which we could not meaningfully execute anyways! if IsCustomWriteQueueEmptyFor(self._profile_store._profile_store_lookup, self._profile_key) == true then -- We don't want auto save to trigger too soon after manual saving - this will reset the auto save timer: RemoveProfileFromAutoSave(self) AddProfileToAutoSave(self) -- Call save function in a new thread: task.spawn(SaveProfileAsync, self) end end function Profile:Release() if self._view_mode == true then return end if self:IsActive() == true then task.spawn(SaveProfileAsync, self, true) -- Call save function in a new thread with release_from_session = true end end function Profile:ListenToHopReady(listener) --> [ScriptConnection] () if type(listener) ~= "function" then error("[ProfileService]: Only a function can be set as listener in Profile:ListenToHopReady()") end if self._view_mode == true then return {Disconnect = function() end} end if self._hop_ready == true then task.spawn(listener) return {Disconnect = function() end} else return self._hop_ready_listeners:Connect(listener) end end function Profile:AddUserId(user_id) -- Associates user_id with profile (GDPR compliance) if type(user_id) ~= "number" or user_id % 1 ~= 0 then warn("[ProfileService]: Invalid UserId argument for :AddUserId() (" .. tostring(user_id) .. "); Traceback:\n" .. debug.traceback()) return end if user_id < 0 and self._is_user_mock ~= true and UseMockDataStore ~= true then return -- Avoid giving real Roblox APIs negative UserId's end if table.find(self.UserIds, user_id) == nil then table.insert(self.UserIds, user_id) end end function Profile:RemoveUserId(user_id) -- Unassociates user_id with profile (safe function) if type(user_id) ~= "number" or user_id % 1 ~= 0 then warn("[ProfileService]: Invalid UserId argument for :RemoveUserId() (" .. tostring(user_id) .. "); Traceback:\n" .. debug.traceback()) return end local index = table.find(self.UserIds, user_id) if index ~= nil then table.remove(self.UserIds, index) end end function Profile:Identify() --> [string] return IdentifyProfile( self._profile_store._profile_store_name, self._profile_store._profile_store_scope, self._profile_key ) end function Profile:ClearGlobalUpdates() -- Clears all global updates data from a profile payload if self._view_mode ~= true then error("[ProfileService]: :ClearGlobalUpdates() can only be used in view mode") end local global_updates_object = { _updates_latest = {0, {}}, _profile = self, } setmetatable(global_updates_object, GlobalUpdates) self.GlobalUpdates = global_updates_object end function Profile:OverwriteAsync() -- Saves the profile to the DataStore and removes the session lock if self._view_mode ~= true then error("[ProfileService]: :OverwriteAsync() can only be used in view mode") end SaveProfileAsync(self, nil, true) end -- ProfileVersionQuery object: local ProfileVersionQuery = { --[[ _profile_store = profile_store, _profile_key = profile_key, _sort_direction = sort_direction, _min_date = min_date, _max_date = max_date, _query_pages = pages, -- [DataStoreVersionPages] _query_index = index, -- [number] _query_failure = false, _is_query_yielded = false, _query_queue = {}, --]] } ProfileVersionQuery.__index = ProfileVersionQuery function ProfileVersionQuery:_MoveQueue() while #self._query_queue > 0 do local queue_entry = table.remove(self._query_queue, 1) task.spawn(queue_entry) if self._is_query_yielded == true then break end end end function ProfileVersionQuery:NextAsync(_is_stacking) --> [Profile] or nil if self._profile_store == nil then return nil end local profile local is_finished = false local function query_job() if self._query_failure == true then is_finished = true return end -- First "next" call loads version pages: if self._query_pages == nil then self._is_query_yielded = true task.spawn(function() profile = self:NextAsync(true) is_finished = true end) local list_success, error_message = pcall(function() self._query_pages = self._profile_store._global_data_store:ListVersionsAsync( self._profile_key, self._sort_direction, self._min_date, self._max_date ) self._query_index = 0 end) if list_success == false or self._query_pages == nil then warn("[ProfileService]: Version query fail - " .. tostring(error_message)) self._query_failure = true end self._is_query_yielded = false self:_MoveQueue() return end local current_page = self._query_pages:GetCurrentPage() local next_item = current_page[self._query_index + 1] -- No more entries: if self._query_pages.IsFinished == true and next_item == nil then is_finished = true return end -- Load next page when this page is over: if next_item == nil then self._is_query_yielded = true task.spawn(function() profile = self:NextAsync(true) is_finished = true end) local success = pcall(function() self._query_pages:AdvanceToNextPageAsync() self._query_index = 0 end) if success == false or #self._query_pages:GetCurrentPage() == 0 then self._query_failure = true end self._is_query_yielded = false self:_MoveQueue() return end -- Next page item: self._query_index += 1 profile = self._profile_store:ViewProfileAsync(self._profile_key, next_item.Version) is_finished = true end if self._is_query_yielded == false then query_job() else if _is_stacking == true then table.insert(self._query_queue, 1, query_job) else table.insert(self._query_queue, query_job) end end while is_finished == false do task.wait() end return profile end -- ProfileStore object: local ProfileStore = { --[[ Mock = {}, _profile_store_name = "", -- [string] -- DataStore name _profile_store_scope = nil, -- [string] or [nil] -- DataStore scope _profile_store_lookup = "", -- [string] -- _profile_store_name .. "\0" .. (_profile_store_scope or "") _profile_template = {}, -- [table] _global_data_store = global_data_store, -- [GlobalDataStore] -- Object returned by DataStoreService:GetDataStore(_profile_store_name) _loaded_profiles = {[profile_key] = Profile, ...}, _profile_load_jobs = {[profile_key] = {load_id, loaded_data}, ...}, _mock_loaded_profiles = {[profile_key] = Profile, ...}, _mock_profile_load_jobs = {[profile_key] = {load_id, loaded_data}, ...}, --]] } ProfileStore.__index = ProfileStore function ProfileStore:LoadProfileAsync(profile_key, not_released_handler, _use_mock) --> [Profile / nil] not_released_handler(place_id, game_job_id) not_released_handler = not_released_handler or "ForceLoad" if self._profile_template == nil then error("[ProfileService]: Profile template not set - ProfileStore:LoadProfileAsync() locked for this ProfileStore") end if type(profile_key) ~= "string" then error("[ProfileService]: profile_key must be a string") elseif string.len(profile_key) == 0 then error("[ProfileService]: Invalid profile_key") end if type(not_released_handler) ~= "function" and not_released_handler ~= "ForceLoad" and not_released_handler ~= "Steal" then error("[ProfileService]: Invalid not_released_handler") end if ProfileService.ServiceLocked == true then return nil end WaitForPendingProfileStore(self) local is_user_mock = _use_mock == UseMockTag -- Check if profile with profile_key isn't already loaded in this session: for _, profile_store in ipairs(ActiveProfileStores) do if profile_store._profile_store_lookup == self._profile_store_lookup then local loaded_profiles = is_user_mock == true and profile_store._mock_loaded_profiles or profile_store._loaded_profiles if loaded_profiles[profile_key] ~= nil then error("[ProfileService]: Profile " .. IdentifyProfile(self._profile_store_name, self._profile_store_scope, profile_key) .. " is already loaded in this session") -- Are you using Profile:Release() properly? end end end ActiveProfileLoadJobs = ActiveProfileLoadJobs + 1 local force_load = not_released_handler == "ForceLoad" local force_load_steps = 0 local request_force_load = force_load -- First step of ForceLoad local steal_session = false -- Second step of ForceLoad local aggressive_steal = not_released_handler == "Steal" -- Developer invoked steal while ProfileService.ServiceLocked == false do -- Load profile: -- SPECIAL CASE - If LoadProfileAsync is called for the same key before another LoadProfileAsync finishes, -- yoink the DataStore return for the new call. The older call will return nil. This would prevent very rare -- game breaking errors where a player rejoins the server super fast. local profile_load_jobs = is_user_mock == true and self._mock_profile_load_jobs or self._profile_load_jobs local loaded_data, key_info local load_id = LoadIndex + 1 LoadIndex = load_id local profile_load_job = profile_load_jobs[profile_key] -- {load_id, {loaded_data, key_info} or nil} if profile_load_job ~= nil then profile_load_job[1] = load_id -- Yoink load job while profile_load_job[2] == nil do -- Wait for job to finish task.wait() end if profile_load_job[1] == load_id then -- Load job hasn't been double-yoinked loaded_data, key_info = table.unpack(profile_load_job[2]) profile_load_jobs[profile_key] = nil else ActiveProfileLoadJobs = ActiveProfileLoadJobs - 1 return nil end else profile_load_job = {load_id, nil} profile_load_jobs[profile_key] = profile_load_job profile_load_job[2] = table.pack(StandardProfileUpdateAsyncDataStore( self, profile_key, { ExistingProfileHandle = function(latest_data) if ProfileService.ServiceLocked == false then local active_session = latest_data.MetaData.ActiveSession local force_load_session = latest_data.MetaData.ForceLoadSession -- IsThisSession(active_session) if active_session == nil then latest_data.MetaData.ActiveSession = {PlaceId, JobId} latest_data.MetaData.ForceLoadSession = nil elseif type(active_session) == "table" then if IsThisSession(active_session) == false then local last_update = latest_data.MetaData.LastUpdate if last_update ~= nil then if os.time() - last_update > SETTINGS.AssumeDeadSessionLock then latest_data.MetaData.ActiveSession = {PlaceId, JobId} latest_data.MetaData.ForceLoadSession = nil return end end if steal_session == true or aggressive_steal == true then local force_load_uninterrupted = false if force_load_session ~= nil then force_load_uninterrupted = IsThisSession(force_load_session) end if force_load_uninterrupted == true or aggressive_steal == true then latest_data.MetaData.ActiveSession = {PlaceId, JobId} latest_data.MetaData.ForceLoadSession = nil end elseif request_force_load == true then latest_data.MetaData.ForceLoadSession = {PlaceId, JobId} end else latest_data.MetaData.ForceLoadSession = nil end end end end, MissingProfileHandle = function(latest_data) latest_data.Data = DeepCopyTable(self._profile_template) latest_data.MetaData = { ProfileCreateTime = os.time(), SessionLoadCount = 0, ActiveSession = {PlaceId, JobId}, ForceLoadSession = nil, MetaTags = {}, } end, EditProfile = function(latest_data) if ProfileService.ServiceLocked == false then local active_session = latest_data.MetaData.ActiveSession if active_session ~= nil and IsThisSession(active_session) == true then latest_data.MetaData.SessionLoadCount = latest_data.MetaData.SessionLoadCount + 1 latest_data.MetaData.LastUpdate = os.time() end end end, }, is_user_mock )) if profile_load_job[1] == load_id then -- Load job hasn't been yoinked loaded_data, key_info = table.unpack(profile_load_job[2]) profile_load_jobs[profile_key] = nil else ActiveProfileLoadJobs = ActiveProfileLoadJobs - 1 return nil -- Load job yoinked end end -- Handle load_data: if loaded_data ~= nil and key_info ~= nil then local active_session = loaded_data.MetaData.ActiveSession if type(active_session) == "table" then if IsThisSession(active_session) == true then -- Special component in MetaTags: loaded_data.MetaData.MetaTagsLatest = DeepCopyTable(loaded_data.MetaData.MetaTags) -- Case #1: Profile is now taken by this session: -- Create Profile object: local global_updates_object = { _updates_latest = loaded_data.GlobalUpdates, _pending_update_lock = {}, _pending_update_clear = {}, _new_active_update_listeners = Madwork.NewScriptSignal(), _new_locked_update_listeners = Madwork.NewScriptSignal(), _profile = nil, } setmetatable(global_updates_object, GlobalUpdates) local profile = { Data = loaded_data.Data, MetaData = loaded_data.MetaData, MetaTagsUpdated = Madwork.NewScriptSignal(), RobloxMetaData = loaded_data.RobloxMetaData or {}, UserIds = loaded_data.UserIds or {}, KeyInfo = key_info, KeyInfoUpdated = Madwork.NewScriptSignal(), GlobalUpdates = global_updates_object, _profile_store = self, _profile_key = profile_key, _release_listeners = Madwork.NewScriptSignal(), _hop_ready_listeners = Madwork.NewScriptSignal(), _hop_ready = false, _load_timestamp = os.clock(), _is_user_mock = is_user_mock, } setmetatable(profile, Profile) global_updates_object._profile = profile -- Referencing Profile object in ProfileStore: if next(self._loaded_profiles) == nil and next(self._mock_loaded_profiles) == nil then -- ProfileStore object was inactive table.insert(ActiveProfileStores, self) end if is_user_mock == true then self._mock_loaded_profiles[profile_key] = profile else self._loaded_profiles[profile_key] = profile end -- Adding profile to AutoSaveList; AddProfileToAutoSave(profile) -- Special case - finished loading profile, but session is shutting down: if ProfileService.ServiceLocked == true then SaveProfileAsync(profile, true) -- Release profile and yield until the DataStore call is finished profile = nil -- nil will be returned by this call end -- Return Profile object: ActiveProfileLoadJobs = ActiveProfileLoadJobs - 1 return profile else -- Case #2: Profile is taken by some other session: if force_load == true then local force_load_session = loaded_data.MetaData.ForceLoadSession local force_load_uninterrupted = false if force_load_session ~= nil then force_load_uninterrupted = IsThisSession(force_load_session) end if force_load_uninterrupted == true then if request_force_load == false then force_load_steps = force_load_steps + 1 if force_load_steps == SETTINGS.ForceLoadMaxSteps then steal_session = true end end task.wait() -- Overload prevention else -- Another session tried to force load this profile: ActiveProfileLoadJobs = ActiveProfileLoadJobs - 1 return nil end request_force_load = false -- Only request a force load once elseif aggressive_steal == true then task.wait() -- Overload prevention else local handler_result = not_released_handler(active_session[1], active_session[2]) if handler_result == "Repeat" then task.wait() -- Overload prevention elseif handler_result == "Cancel" then ActiveProfileLoadJobs = ActiveProfileLoadJobs - 1 return nil elseif handler_result == "ForceLoad" then force_load = true request_force_load = true task.wait() -- Overload prevention elseif handler_result == "Steal" then aggressive_steal = true task.wait() -- Overload prevention else error( "[ProfileService]: Invalid return from not_released_handler (\"" .. tostring(handler_result) .. "\")(" .. type(handler_result) .. ");" .. "\n" .. IdentifyProfile(self._profile_store_name, self._profile_store_scope, profile_key) .. " Traceback:\n" .. debug.traceback() ) end end end else ActiveProfileLoadJobs = ActiveProfileLoadJobs - 1 return nil -- In this scenario it is likely the ProfileService.ServiceLocked flag was raised end else task.wait() -- Overload prevention end end ActiveProfileLoadJobs = ActiveProfileLoadJobs - 1 return nil -- If loop breaks return nothing end function ProfileStore:GlobalUpdateProfileAsync(profile_key, update_handler, _use_mock) --> [GlobalUpdates / nil] (update_handler(GlobalUpdates)) if type(profile_key) ~= "string" or string.len(profile_key) == 0 then error("[ProfileService]: Invalid profile_key") end if type(update_handler) ~= "function" then error("[ProfileService]: Invalid update_handler") end if ProfileService.ServiceLocked == true then return nil end WaitForPendingProfileStore(self) while ProfileService.ServiceLocked == false do -- Updating profile: local loaded_data = StandardProfileUpdateAsyncDataStore( self, profile_key, { ExistingProfileHandle = nil, MissingProfileHandle = nil, EditProfile = function(latest_data) -- Running update_handler: local global_updates_object = { _updates_latest = latest_data.GlobalUpdates, _update_handler_mode = true, } setmetatable(global_updates_object, GlobalUpdates) update_handler(global_updates_object) end, }, _use_mock == UseMockTag ) CustomWriteQueueMarkForCleanup(self._profile_store_lookup, profile_key) -- Handling loaded_data: if loaded_data ~= nil then -- Return GlobalUpdates object (Update successful): local global_updates_object = { _updates_latest = loaded_data.GlobalUpdates, } setmetatable(global_updates_object, GlobalUpdates) return global_updates_object else task.wait() -- Overload prevention end end return nil -- Return nothing (Update unsuccessful) end function ProfileStore:ViewProfileAsync(profile_key, version, _use_mock) --> [Profile / nil] if type(profile_key) ~= "string" or string.len(profile_key) == 0 then error("[ProfileService]: Invalid profile_key") end if ProfileService.ServiceLocked == true then return nil end WaitForPendingProfileStore(self) if version ~= nil and (_use_mock == UseMockTag or UseMockDataStore == true) then return nil -- No version support in mock mode end while ProfileService.ServiceLocked == false do -- Load profile: local loaded_data, key_info = StandardProfileUpdateAsyncDataStore( self, profile_key, { ExistingProfileHandle = nil, MissingProfileHandle = function(latest_data) latest_data.Data = DeepCopyTable(self._profile_template) latest_data.MetaData = { ProfileCreateTime = os.time(), SessionLoadCount = 0, ActiveSession = nil, ForceLoadSession = nil, MetaTags = {}, } end, EditProfile = nil, }, _use_mock == UseMockTag, true, -- Use :GetAsync() version -- DataStore key version ) CustomWriteQueueMarkForCleanup(self._profile_store_lookup, profile_key) -- Handle load_data: if loaded_data ~= nil then if key_info == nil then return nil -- Load was successful, but the key was empty - return no profile object end -- Create Profile object: local global_updates_object = { _updates_latest = loaded_data.GlobalUpdates, -- {0, {}} _profile = nil, } setmetatable(global_updates_object, GlobalUpdates) local profile = { Data = loaded_data.Data, MetaData = loaded_data.MetaData, MetaTagsUpdated = Madwork.NewScriptSignal(), RobloxMetaData = loaded_data.RobloxMetaData or {}, UserIds = loaded_data.UserIds or {}, KeyInfo = key_info, KeyInfoUpdated = Madwork.NewScriptSignal(), GlobalUpdates = global_updates_object, _profile_store = self, _profile_key = profile_key, _view_mode = true, _load_timestamp = os.clock(), } setmetatable(profile, Profile) global_updates_object._profile = profile -- Returning Profile object: return profile else task.wait() -- Overload prevention end end return nil -- If loop breaks return nothing end function ProfileStore:ProfileVersionQuery(profile_key, sort_direction, min_date, max_date, _use_mock) --> [ProfileVersionQuery] if type(profile_key) ~= "string" or string.len(profile_key) == 0 then error("[ProfileService]: Invalid profile_key") end if ProfileService.ServiceLocked == true then return setmetatable({}, ProfileVersionQuery) -- Silently fail :Next() requests end WaitForPendingProfileStore(self) if _use_mock == UseMockTag or UseMockDataStore == true then error("[ProfileService]: :ProfileVersionQuery() is not supported in mock mode") end -- Type check: if sort_direction ~= nil and (typeof(sort_direction) ~= "EnumItem" or sort_direction.EnumType ~= Enum.SortDirection) then error("[ProfileService]: Invalid sort_direction (" .. tostring(sort_direction) .. ")") end if min_date ~= nil and typeof(min_date) ~= "DateTime" and typeof(min_date) ~= "number" then error("[ProfileService]: Invalid min_date (" .. tostring(min_date) .. ")") end if max_date ~= nil and typeof(max_date) ~= "DateTime" and typeof(max_date) ~= "number" then error("[ProfileService]: Invalid max_date (" .. tostring(max_date) .. ")") end min_date = typeof(min_date) == "DateTime" and min_date.UnixTimestampMillis or min_date max_date = typeof(max_date) == "DateTime" and max_date.UnixTimestampMillis or max_date local profile_version_query = { _profile_store = self, _profile_key = profile_key, _sort_direction = sort_direction, _min_date = min_date, _max_date = max_date, _query_pages = nil, _query_index = 0, _query_failure = false, _is_query_yielded = false, _query_queue = {}, } setmetatable(profile_version_query, ProfileVersionQuery) return profile_version_query end function ProfileStore:WipeProfileAsync(profile_key, _use_mock) --> is_wipe_successful [bool] if type(profile_key) ~= "string" or string.len(profile_key) == 0 then error("[ProfileService]: Invalid profile_key") end if ProfileService.ServiceLocked == true then return false end WaitForPendingProfileStore(self) local wipe_status = false if _use_mock == UseMockTag then -- Used when the profile is accessed through ProfileStore.Mock local mock_data_store = UserMockDataStore[self._profile_store_lookup] if mock_data_store ~= nil then mock_data_store[profile_key] = nil end wipe_status = true task.wait() -- Simulate API call yield elseif UseMockDataStore == true then -- Used when API access is disabled local mock_data_store = MockDataStore[self._profile_store_lookup] if mock_data_store ~= nil then mock_data_store[profile_key] = nil end wipe_status = true task.wait() -- Simulate API call yield else wipe_status = pcall(function() self._global_data_store:RemoveAsync(profile_key) end) end CustomWriteQueueMarkForCleanup(self._profile_store_lookup, profile_key) return wipe_status end -- New ProfileStore: function ProfileService.GetProfileStore(profile_store_index, profile_template) --> [ProfileStore] local profile_store_name local profile_store_scope = nil -- Parsing profile_store_index: if type(profile_store_index) == "string" then -- profile_store_index as string: profile_store_name = profile_store_index elseif type(profile_store_index) == "table" then -- profile_store_index as table: profile_store_name = profile_store_index.Name profile_store_scope = profile_store_index.Scope else error("[ProfileService]: Invalid or missing profile_store_index") end -- Type checking: if profile_store_name == nil or type(profile_store_name) ~= "string" then error("[ProfileService]: Missing or invalid \"Name\" parameter") elseif string.len(profile_store_name) == 0 then error("[ProfileService]: ProfileStore name cannot be an empty string") end if profile_store_scope ~= nil and (type(profile_store_scope) ~= "string" or string.len(profile_store_scope) == 0) then error("[ProfileService]: Invalid \"Scope\" parameter") end if type(profile_template) ~= "table" then error("[ProfileService]: Invalid profile_template") end local profile_store profile_store = { Mock = { LoadProfileAsync = function(_, profile_key, not_released_handler) return profile_store:LoadProfileAsync(profile_key, not_released_handler, UseMockTag) end, GlobalUpdateProfileAsync = function(_, profile_key, update_handler) return profile_store:GlobalUpdateProfileAsync(profile_key, update_handler, UseMockTag) end, ViewProfileAsync = function(_, profile_key, version) return profile_store:ViewProfileAsync(profile_key, version, UseMockTag) end, FindProfileVersionAsync = function(_, profile_key, sort_direction, min_date, max_date) return profile_store:FindProfileVersionAsync(profile_key, sort_direction, min_date, max_date, UseMockTag) end, WipeProfileAsync = function(_, profile_key) return profile_store:WipeProfileAsync(profile_key, UseMockTag) end }, _profile_store_name = profile_store_name, _profile_store_scope = profile_store_scope, _profile_store_lookup = profile_store_name .. "\0" .. (profile_store_scope or ""), _profile_template = profile_template, _global_data_store = nil, _loaded_profiles = {}, _profile_load_jobs = {}, _mock_loaded_profiles = {}, _mock_profile_load_jobs = {}, _is_pending = false, } setmetatable(profile_store, ProfileStore) if IsLiveCheckActive == true then profile_store._is_pending = true task.spawn(function() WaitForLiveAccessCheck() if UseMockDataStore == false then profile_store._global_data_store = DataStoreService:GetDataStore(profile_store_name, profile_store_scope) end profile_store._is_pending = false end) else if UseMockDataStore == false then profile_store._global_data_store = DataStoreService:GetDataStore(profile_store_name, profile_store_scope) end end return profile_store end function ProfileService.IsLive() --> [bool] -- (CAN YIELD!!!) WaitForLiveAccessCheck() return UseMockDataStore == false end ----- Initialize ----- if IsStudio == true then IsLiveCheckActive = true task.spawn(function() local status, message = pcall(function() -- This will error if current instance has no Studio API access: DataStoreService:GetDataStore("____PS"):SetAsync("____PS", os.time()) end) local no_internet_access = status == false and string.find(message, "ConnectFail", 1, true) ~= nil if no_internet_access == true then warn("[ProfileService]: No internet access - check your network connection") end if status == false and (string.find(message, "403", 1, true) ~= nil or -- Cannot write to DataStore from studio if API access is not enabled string.find(message, "must publish", 1, true) ~= nil or -- Game must be published to access live keys no_internet_access == true) then -- No internet access UseMockDataStore = true ProfileService._use_mock_data_store = true print("[ProfileService]: Roblox API services unavailable - data will not be saved") else print("[ProfileService]: Roblox API services available - data will be saved") end IsLiveCheckActive = false end) end ----- Connections ----- -- Auto saving and issue queue managing: RunService.Heartbeat:Connect(function() -- 1) Auto saving: -- local auto_save_list_length = #AutoSaveList if auto_save_list_length > 0 then local auto_save_index_speed = SETTINGS.AutoSaveProfiles / auto_save_list_length local os_clock = os.clock() while os_clock - LastAutoSave > auto_save_index_speed do LastAutoSave = LastAutoSave + auto_save_index_speed local profile = AutoSaveList[AutoSaveIndex] if os_clock - profile._load_timestamp < SETTINGS.AutoSaveProfiles then -- This profile is freshly loaded - auto-saving immediately after loading will cause a warning in the log: profile = nil for _ = 1, auto_save_list_length - 1 do -- Move auto save index to the right: AutoSaveIndex = AutoSaveIndex + 1 if AutoSaveIndex > auto_save_list_length then AutoSaveIndex = 1 end profile = AutoSaveList[AutoSaveIndex] if os_clock - profile._load_timestamp >= SETTINGS.AutoSaveProfiles then break else profile = nil end end end -- Move auto save index to the right: AutoSaveIndex = AutoSaveIndex + 1 if AutoSaveIndex > auto_save_list_length then AutoSaveIndex = 1 end -- Perform save call: if profile ~= nil then task.spawn(SaveProfileAsync, profile) -- Auto save profile in new thread end end end -- 2) Issue queue: -- -- Critical state handling: if ProfileService.CriticalState == false then if #IssueQueue >= SETTINGS.IssueCountForCriticalState then ProfileService.CriticalState = true ProfileService.CriticalStateSignal:Fire(true) CriticalStateStart = os.clock() warn("[ProfileService]: Entered critical state") end else if #IssueQueue >= SETTINGS.IssueCountForCriticalState then CriticalStateStart = os.clock() elseif os.clock() - CriticalStateStart > SETTINGS.CriticalStateLast then ProfileService.CriticalState = false ProfileService.CriticalStateSignal:Fire(false) warn("[ProfileService]: Critical state ended") end end -- Issue queue: while true do local issue_time = IssueQueue[1] if issue_time == nil then break elseif os.clock() - issue_time > SETTINGS.IssueLast then table.remove(IssueQueue, 1) else break end end end) -- Release all loaded profiles when the server is shutting down: task.spawn(function() WaitForLiveAccessCheck() Madwork.ConnectToOnClose( function() ProfileService.ServiceLocked = true -- 1) Release all active profiles: -- -- Clone AutoSaveList to a new table because AutoSaveList changes when profiles are released: local on_close_save_job_count = 0 local active_profiles = {} for index, profile in ipairs(AutoSaveList) do active_profiles[index] = profile end -- Release the profiles; Releasing profiles can trigger listeners that release other profiles, so check active state: for _, profile in ipairs(active_profiles) do if profile:IsActive() == true then on_close_save_job_count = on_close_save_job_count + 1 task.spawn(function() -- Save profile on new thread SaveProfileAsync(profile, true) on_close_save_job_count = on_close_save_job_count - 1 end) end end -- 2) Yield until all active profile jobs are finished: -- while on_close_save_job_count > 0 or ActiveProfileLoadJobs > 0 or ActiveProfileSaveJobs > 0 do task.wait() end return -- We're done! end, UseMockDataStore == false -- Always run this OnClose task if using Roblox API services ) end) return ProfileService sleitnick_comm@1.0.1 Option Promise Signal comm Hi ``` ]=] local Comm = { Server = require(script.Server), Client = require(script.Client), ServerComm = require(script.Server.ServerComm), ClientComm = require(script.Client.ClientComm), } return Comm ]]> Client 0 local hasOutbound = type(outboundMiddleware) == "table" and #outboundMiddleware > 0 local function ProcessOutbound(args) for _, middlewareFunc in ipairs(outboundMiddleware) do local middlewareResult = table.pack(middlewareFunc(args)) if not middlewareResult[1] then return table.unpack(middlewareResult, 2, middlewareResult.n) end args.n = #args end return table.unpack(args, 1, args.n) end if hasInbound then if usePromise then return function(...) local args = table.pack(...) return Promise.new(function(resolve, reject) local success, res = pcall(function() if hasOutbound then return table.pack(rf:InvokeServer(ProcessOutbound(args))) else return table.pack(rf:InvokeServer(table.unpack(args, 1, args.n))) end end) if success then for _, middlewareFunc in ipairs(inboundMiddleware) do local middlewareResult = table.pack(middlewareFunc(res)) if not middlewareResult[1] then return table.unpack(middlewareResult, 2, middlewareResult.n) end res.n = #res end resolve(table.unpack(res, 1, res.n)) else reject(res) end end) end else return function(...) local res if hasOutbound then res = table.pack(rf:InvokeServer(ProcessOutbound(table.pack(...)))) else res = table.pack(rf:InvokeServer(...)) end for _, middlewareFunc in ipairs(inboundMiddleware) do local middlewareResult = table.pack(middlewareFunc(res)) if not middlewareResult[1] then return table.unpack(middlewareResult, 2, middlewareResult.n) end res.n = #res end return table.unpack(res, 1, res.n) end end else if usePromise then return function(...) local args = table.pack(...) return Promise.new(function(resolve, reject) local success, res = pcall(function() if hasOutbound then return table.pack(rf:InvokeServer(ProcessOutbound(args))) else return table.pack(rf:InvokeServer(table.unpack(args, 1, args.n))) end end) if success then resolve(table.unpack(res, 1, res.n)) else reject(res) end end) end else if hasOutbound then return function(...) return rf:InvokeServer(ProcessOutbound(table.pack(...))) end else return function(...) return rf:InvokeServer(...) end end end end end function Client.GetSignal( parent: Instance, name: string, inboundMiddleware: Types.ClientMiddleware?, outboundMiddleware: Types.ClientMiddleware? ) assert(not Util.IsServer, "GetSignal must be called from the client") local folder = Util.GetCommSubFolder(parent, "RE"):Expect("Failed to get Comm RE folder") local re = folder:WaitForChild(name, Util.WaitForChildTimeout) assert(re ~= nil, "Failed to find RemoteEvent: " .. name) return ClientRemoteSignal.new(re, inboundMiddleware, outboundMiddleware) end function Client.GetProperty( parent: Instance, name: string, inboundMiddleware: Types.ClientMiddleware?, outboundMiddleware: Types.ClientMiddleware? ) assert(not Util.IsServer, "GetProperty must be called from the client") local folder = Util.GetCommSubFolder(parent, "RP"):Expect("Failed to get Comm RP folder") local re = folder:WaitForChild(name, Util.WaitForChildTimeout) assert(re ~= nil, "Failed to find RemoteEvent for RemoteProperty: " .. name) return ClientRemoteProperty.new(re, inboundMiddleware, outboundMiddleware) end return Client ]]> ClientComm (shouldContinue: boolean, ...: any) The middleware function takes the arguments (as a table array), and should return `true|false` to indicate if the process should continue. If returning `false`, the optional varargs after the `false` are used as the new return values to whatever was calling the middleware. ]=] --[=[ @within ClientComm @type ClientMiddleware {ClientMiddlewareFn} Array of middleware functions. ]=] --[=[ @return ClientComm Constructs a ClientComm object. If `usePromise` is set to `true`, then `GetFunction` will generate a function that returns a Promise that resolves with the server response. If set to `false`, the function will act like a normal call to a RemoteFunction and yield until the function responds. ```lua local clientComm = ClientComm.new(game:GetService("ReplicatedStorage"), true) -- If using a unique namespace with ServerComm, include it as second argument: local clientComm = ClientComm.new(game:GetService("ReplicatedStorage"), true, "MyNamespace") ``` ]=] function ClientComm.new(parent: Instance, usePromise: boolean, namespace: string?) assert(not Util.IsServer, "ClientComm must be constructed from the client") assert(typeof(parent) == "Instance", "Parent must be of type Instance") local ns = Util.DefaultCommFolderName if namespace then ns = namespace end local folder: Instance? = parent:WaitForChild(ns, Util.WaitForChildTimeout) assert(folder ~= nil, "Could not find namespace for ClientComm in parent: " .. ns) local self = setmetatable({}, ClientComm) self._instancesFolder = folder self._usePromise = usePromise return self end --[=[ @param name string @param inboundMiddleware ClientMiddleware? @param outboundMiddleware ClientMiddleware? @return (...: any) -> any Generates a function on the matching RemoteFunction generated with ServerComm. The function can then be called to invoke the server. If this `ClientComm` object was created with the `usePromise` parameter set to `true`, then this generated function will return a Promise when called. ```lua -- Server-side: local serverComm = ServerComm.new(someParent) serverComm:BindFunction("MyFunction", function(player, msg) return msg:upper() end) -- Client-side: local clientComm = ClientComm.new(someParent) local myFunc = clientComm:GetFunction("MyFunction") local uppercase = myFunc("hello world") print(uppercase) --> HELLO WORLD -- Client-side, using promises: local clientComm = ClientComm.new(someParent, true) local myFunc = clientComm:GetFunction("MyFunction") myFunc("hi there"):andThen(function(msg) print(msg) --> HI THERE end):catch(function(err) print("Error:", err) end) ``` ]=] function ClientComm:GetFunction( name: string, inboundMiddleware: Types.ClientMiddleware?, outboundMiddleware: Types.ClientMiddleware? ) return Comm.GetFunction(self._instancesFolder, name, self._usePromise, inboundMiddleware, outboundMiddleware) end --[=[ @param name string @param inboundMiddleware ClientMiddleware? @param outboundMiddleware ClientMiddleware? @return ClientRemoteSignal Returns a new ClientRemoteSignal that mirrors the matching RemoteSignal created by ServerComm with the same matching `name`. ```lua local mySignal = clientComm:GetSignal("MySignal") -- Listen for data from the server: mySignal:Connect(function(message) print("Received message from server:", message) end) -- Send data to the server: mySignal:Fire("Hello!") ``` ]=] function ClientComm:GetSignal( name: string, inboundMiddleware: Types.ClientMiddleware?, outboundMiddleware: Types.ClientMiddleware? ) return Comm.GetSignal(self._instancesFolder, name, inboundMiddleware, outboundMiddleware) end --[=[ @param name string @param inboundMiddleware ClientMiddleware? @param outboundMiddleware ClientMiddleware? @return ClientRemoteProperty Returns a new ClientRemoteProperty that mirrors the matching RemoteProperty created by ServerComm with the same matching `name`. Take a look at the ClientRemoteProperty documentation for more info, such as understanding how to wait for data to be ready. ```lua local mapInfo = clientComm:GetProperty("MapInfo") -- Observe the initial value of mapInfo, and all subsequent changes: mapInfo:Observe(function(info) print("Current map info", info) end) -- Check to see if data is initially ready: if mapInfo:IsReady() then -- Get the data: local info = mapInfo:Get() end -- Get a promise that resolves once the data is ready (resolves immediately if already ready): mapInfo:OnReady():andThen(function(info) print("Map info is ready with info", info) end) -- Same as above, but yields thread: local success, info = mapInfo:OnReady():await() ``` ]=] function ClientComm:GetProperty( name: string, inboundMiddleware: Types.ClientMiddleware?, outboundMiddleware: Types.ClientMiddleware? ) return Comm.GetProperty(self._instancesFolder, name, inboundMiddleware, outboundMiddleware) end --[=[ @param inboundMiddleware ClientMiddleware? @param outboundMiddleware ClientMiddleware? @return table Returns an object which maps RemoteFunctions as methods and RemoteEvents as fields. ```lua -- Server-side: serverComm:BindFunction("Test", function(player) end) serverComm:CreateSignal("MySignal") serverComm:CreateProperty("MyProperty", 10) -- Client-side local obj = clientComm:BuildObject() obj:Test() obj.MySignal:Connect(function(data) end) obj.MyProperty:Observe(function(value) end) ``` ]=] function ClientComm:BuildObject(inboundMiddleware: Types.ClientMiddleware?, outboundMiddleware: Types.ClientMiddleware?) local obj = {} local rfFolder = self._instancesFolder:FindFirstChild("RF") local reFolder = self._instancesFolder:FindFirstChild("RE") local rpFolder = self._instancesFolder:FindFirstChild("RP") if rfFolder then for _, rf in rfFolder:GetChildren() do if not rf:IsA("RemoteFunction") then continue end local f = self:GetFunction(rf.Name, inboundMiddleware, outboundMiddleware) obj[rf.Name] = function(_self, ...) return f(...) end end end if reFolder then for _, re in reFolder:GetChildren() do if (not re:IsA("RemoteEvent")) and (not re:IsA("UnreliableRemoteEvent")) then continue end obj[re.Name] = self:GetSignal(re.Name, inboundMiddleware, outboundMiddleware) end end if rpFolder then for _, re in rpFolder:GetChildren() do if not re:IsA("RemoteEvent") then continue end obj[re.Name] = self:GetProperty(re.Name, inboundMiddleware, outboundMiddleware) end end return obj end --[=[ Destroys the ClientComm object. ]=] function ClientComm:Destroy() end return ClientComm ]]> ClientRemoteProperty Fires when the property receives an updated value from the server. ```lua clientRemoteProperty.Changed:Connect(function(value) print("New value", value) end) ``` ]=] --[=[ @class ClientRemoteProperty @client Created via `ClientComm:GetProperty()`. ]=] local ClientRemoteProperty = {} ClientRemoteProperty.__index = ClientRemoteProperty function ClientRemoteProperty.new( re: RemoteEvent, inboundMiddleware: Types.ClientMiddleware?, outboudMiddleware: Types.ClientMiddleware? ) local self = setmetatable({}, ClientRemoteProperty) self._rs = ClientRemoteSignal.new(re, inboundMiddleware, outboudMiddleware) self._ready = false self._value = nil self.Changed = Signal.new() self._rs:Fire() local resolveOnReadyPromise self._readyPromise = Promise.new(function(resolve) resolveOnReadyPromise = resolve end) self._changed = self._rs:Connect(function(value) local changed = value ~= self._value self._value = value if not self._ready then self._ready = true resolveOnReadyPromise(value) end if changed then self.Changed:Fire(value) end end) return self end --[=[ Gets the value of the property object. :::caution This value might not be ready right away. Use `OnReady()` or `IsReady()` before calling `Get()`. If not ready, this value will return `nil`. ::: ]=] function ClientRemoteProperty:Get(): any return self._value end --[=[ @return Promise Returns a Promise which resolves once the property object is ready to be used. The resolved promise will also contain the value of the property. ```lua -- Use andThen clause: clientRemoteProperty:OnReady():andThen(function(initialValue) print(initialValue) end) -- Use await: local success, initialValue = clientRemoteProperty:OnReady():await() if success then print(initialValue) end ``` ]=] function ClientRemoteProperty:OnReady() return self._readyPromise end --[=[ Returns `true` if the property object is ready to be used. In other words, it has successfully gained connection to the server-side version and has synced in the initial value. ```lua if clientRemoteProperty:IsReady() then local value = clientRemoteProperty:Get() end ``` ]=] function ClientRemoteProperty:IsReady(): boolean return self._ready end --[=[ @param observer (any) -> nil @return Connection Observes the value of the property. The observer will be called right when the value is first ready, and every time the value changes. This is safe to call immediately (i.e. no need to use `IsReady` or `OnReady` before using this method). Observing is essentially listening to `Changed`, but also sends the initial value right away (or at least once `OnReady` is completed). ```lua local function ObserveValue(value) print(value) end clientRemoteProperty:Observe(ObserveValue) ``` ]=] function ClientRemoteProperty:Observe(observer: (any) -> ()) if self._ready then task.defer(observer, self._value) end return self.Changed:Connect(observer) end --[=[ Destroys the ClientRemoteProperty object. ]=] function ClientRemoteProperty:Destroy() self._rs:Destroy() if self._readyPromise then self._readyPromise:cancel() end if self._changed then self._changed:Disconnect() end self.Changed:Destroy() end return ClientRemoteProperty ]]> ClientRemoteSignal () Represents a connection. ]=] function ClientRemoteSignal.new( re: RemoteEvent | UnreliableRemoteEvent, inboundMiddleware: Types.ClientMiddleware?, outboudMiddleware: Types.ClientMiddleware? ) local self = setmetatable({}, ClientRemoteSignal) self._re = re if outboudMiddleware and #outboudMiddleware > 0 then self._hasOutbound = true self._outbound = outboudMiddleware else self._hasOutbound = false end if inboundMiddleware and #inboundMiddleware > 0 then self._directConnect = false self._signal = Signal.new() self._reConn = self._re.OnClientEvent:Connect(function(...) local args = table.pack(...) for _, middlewareFunc in inboundMiddleware do local middlewareResult = table.pack(middlewareFunc(args)) if not middlewareResult[1] then return end args.n = #args end self._signal:Fire(table.unpack(args, 1, args.n)) end) else self._directConnect = true end return self end function ClientRemoteSignal:_processOutboundMiddleware(...: any) local args = table.pack(...) for _, middlewareFunc in self._outbound do local middlewareResult = table.pack(middlewareFunc(args)) if not middlewareResult[1] then return table.unpack(middlewareResult, 2, middlewareResult.n) end args.n = #args end return table.unpack(args, 1, args.n) end --[=[ @param fn (...: any) -> () @return Connection Connects a function to the remote signal. The function will be called anytime the equivalent server-side RemoteSignal is fired at this specific client that created this client signal. ]=] function ClientRemoteSignal:Connect(fn: (...any) -> ()) if self._directConnect then return self._re.OnClientEvent:Connect(fn) else return self._signal:Connect(fn) end end --[=[ Fires the equivalent server-side signal with the given arguments. :::note Outbound Middleware All arguments pass through any outbound middleware before being sent to the server. ::: ]=] function ClientRemoteSignal:Fire(...: any) if self._hasOutbound then self._re:FireServer(self:_processOutboundMiddleware(...)) else self._re:FireServer(...) end end --[=[ Destroys the ClientRemoteSignal object. ]=] function ClientRemoteSignal:Destroy() if self._signal then self._signal:Destroy() end end return ClientRemoteSignal ]]> Server any .GetSignal (parent: Instance, name: string, inboundMiddleware: ClientMiddleware?, outboundMiddleware: ClientMiddleware?): ClientRemoteSignal .GetProperty (parent: Instance, name: string, inboundMiddleware: ClientMiddleware?, outboundMiddleware: ClientMiddleware?): ClientRemoteProperty Client Comm ]=] function Server.BindFunction( parent: Instance, name: string, func: Types.FnBind, inboundMiddleware: Types.ServerMiddleware?, outboundMiddleware: Types.ServerMiddleware? ): RemoteFunction assert(Util.IsServer, "BindFunction must be called from the server") local folder = Util.GetCommSubFolder(parent, "RF"):Expect("Failed to get Comm RF folder") local rf = Instance.new("RemoteFunction") rf.Name = name local hasInbound = type(inboundMiddleware) == "table" and #inboundMiddleware > 0 local hasOutbound = type(outboundMiddleware) == "table" and #outboundMiddleware > 0 local function ProcessOutbound(player, ...) local args = table.pack(...) for _, middlewareFunc in ipairs(outboundMiddleware) do local middlewareResult = table.pack(middlewareFunc(player, args)) if not middlewareResult[1] then return table.unpack(middlewareResult, 2, middlewareResult.n) end args.n = #args end return table.unpack(args, 1, args.n) end if hasInbound and hasOutbound then local function OnServerInvoke(player, ...) local args = table.pack(...) for _, middlewareFunc in ipairs(inboundMiddleware) do local middlewareResult = table.pack(middlewareFunc(player, args)) if not middlewareResult[1] then return table.unpack(middlewareResult, 2, middlewareResult.n) end args.n = #args end return ProcessOutbound(player, func(player, table.unpack(args, 1, args.n))) end rf.OnServerInvoke = OnServerInvoke elseif hasInbound then local function OnServerInvoke(player, ...) local args = table.pack(...) for _, middlewareFunc in ipairs(inboundMiddleware) do local middlewareResult = table.pack(middlewareFunc(player, args)) if not middlewareResult[1] then return table.unpack(middlewareResult, 2, middlewareResult.n) end args.n = #args end return func(player, table.unpack(args, 1, args.n)) end rf.OnServerInvoke = OnServerInvoke elseif hasOutbound then local function OnServerInvoke(player, ...) return ProcessOutbound(player, func(player, ...)) end rf.OnServerInvoke = OnServerInvoke else rf.OnServerInvoke = func end rf.Parent = folder return rf end function Server.WrapMethod( parent: Instance, tbl: {}, name: string, inboundMiddleware: Types.ServerMiddleware?, outboundMiddleware: Types.ServerMiddleware? ): RemoteFunction assert(Util.IsServer, "WrapMethod must be called from the server") local fn = tbl[name] assert(type(fn) == "function", "Value at index " .. name .. " must be a function; got " .. type(fn)) return Server.BindFunction(parent, name, function(...) return fn(tbl, ...) end, inboundMiddleware, outboundMiddleware) end function Server.CreateSignal( parent: Instance, name: string, reliable: boolean?, inboundMiddleware: Types.ServerMiddleware?, outboundMiddleware: Types.ServerMiddleware? ) assert(Util.IsServer, "CreateSignal must be called from the server") local folder = Util.GetCommSubFolder(parent, "RE"):Expect("Failed to get Comm RE folder") local rs = RemoteSignal.new(folder, name, reliable, inboundMiddleware, outboundMiddleware) return rs end function Server.CreateProperty( parent: Instance, name: string, initialValue: any, inboundMiddleware: Types.ServerMiddleware?, outboundMiddleware: Types.ServerMiddleware? ) assert(Util.IsServer, "CreateProperty must be called from the server") local folder = Util.GetCommSubFolder(parent, "RP"):Expect("Failed to get Comm RP folder") local rp = RemoteProperty.new(folder, name, initialValue, inboundMiddleware, outboundMiddleware) return rp end return Server ]]> RemoteProperty "Data" -- Using 'SetTop' does not override: remoteProperty:SetFor(somePlayer, "CustomData") remoteProperty:SetTop("Data") print(remoteProperty:GetFor(somePlayer)) --> "CustomData" ``` ]=] function RemoteProperty:SetTop(value: any) self._value = value for _, player in ipairs(Players:GetPlayers()) do if self._perPlayer[player] == nil then self._rs:Fire(player, value) end end end --[=[ @param value any -- Value to set for the clients (and to the predicate) Sets the value for specific clients that pass the `predicate` function test. This can be used to finely set the values based on more control logic (e.g. setting certain values per team). ```lua -- Set the value of "NewValue" to players with a name longer than 10 characters: remoteProperty:SetFilter(function(player) return #player.Name > 10 end, "NewValue") ``` ]=] function RemoteProperty:SetFilter(predicate: (Player, any) -> boolean, value: any) for _, player in ipairs(Players:GetPlayers()) do if predicate(player, value) then self:SetFor(player, value) end end end --[=[ Set the value of the property for a specific player. This will override the value used by `Set` (and the initial value set for the property when created). This value _can_ be `nil`. In order to reset the value for a given player and let the player use the top-level value held by this property, either use `Set` to set all players' data, or use `ClearFor`. ```lua remoteProperty:SetFor(somePlayer, "CustomData") ``` ]=] function RemoteProperty:SetFor(player: Player, value: any) if player.Parent then self._perPlayer[player] = if value == nil then None else value end self._rs:Fire(player, value) end --[=[ Set the value of the property for specific players. This just loops through the players given and calls `SetFor`. ```lua local players = {player1, player2, player3} remoteProperty:SetForList(players, "CustomData") ``` ]=] function RemoteProperty:SetForList(players: { Player }, value: any) for _, player in ipairs(players) do self:SetFor(player, value) end end --[=[ Clears the custom property value for the given player. When this occurs, the player will reset to use the top-level value held by this property (either the value set when the property was created, or the last value set by `Set`). ```lua remoteProperty:Set("DATA") remoteProperty:SetFor(somePlayer, "CUSTOM_DATA") print(remoteProperty:GetFor(somePlayer)) --> "CUSTOM_DATA" -- DOES NOT CLEAR, JUST SETS CUSTOM DATA TO NIL: remoteProperty:SetFor(somePlayer, nil) print(remoteProperty:GetFor(somePlayer)) --> nil -- CLEAR: remoteProperty:ClearFor(somePlayer) print(remoteProperty:GetFor(somePlayer)) --> "DATA" ``` ]=] function RemoteProperty:ClearFor(player: Player) if self._perPlayer[player] == nil then return end self._perPlayer[player] = nil self._rs:Fire(player, self._value) end --[=[ Clears the custom value for the given players. This just loops through the list of players and calls the `ClearFor` method for each player. ]=] function RemoteProperty:ClearForList(players: { Player }) for _, player in ipairs(players) do self:ClearFor(player) end end --[=[ The same as `SetFiler`, except clears the custom value for any player that passes the predicate. ]=] function RemoteProperty:ClearFilter(predicate: (Player) -> boolean) for _, player in ipairs(Players:GetPlayers()) do if predicate(player) then self:ClearFor(player) end end end --[=[ Returns the top-level value held by the property. This will either be the initial value set, or the last value set with `Set()`. ```lua remoteProperty:Set("Data") print(remoteProperty:Get()) --> "Data" ``` ]=] function RemoteProperty:Get(): any return self._value end --[=[ Returns the current value for the given player. This value will depend on if `SetFor` or `SetFilter` has affected the custom value for the player. If so, that custom value will be returned. Otherwise, the top-level value will be used (e.g. value from `Set`). ```lua -- Set top level data: remoteProperty:Set("Data") print(remoteProperty:GetFor(somePlayer)) --> "Data" -- Set custom data: remoteProperty:SetFor(somePlayer, "CustomData") print(remoteProperty:GetFor(somePlayer)) --> "CustomData" -- Set top level again, overriding custom data: remoteProperty:Set("NewData") print(remoteProperty:GetFor(somePlayer)) --> "NewData" -- Set custom data again, and set top level without overriding: remoteProperty:SetFor(somePlayer, "CustomData") remoteProperty:SetTop("Data") print(remoteProperty:GetFor(somePlayer)) --> "CustomData" -- Clear custom data to use top level data: remoteProperty:ClearFor(somePlayer) print(remoteProperty:GetFor(somePlayer)) --> "Data" ``` ]=] function RemoteProperty:GetFor(player: Player): any local playerValue = self._perPlayer[player] local value = if playerValue == nil then self._value elseif playerValue == None then nil else playerValue return value end --[=[ Destroys the RemoteProperty object. ]=] function RemoteProperty:Destroy() self._rs:Destroy() self._playerRemoving:Disconnect() end return RemoteProperty ]]> RemoteSignal nil .Connected boolean Represents a connection. ]=] function RemoteSignal.new( parent: Instance, name: string, unreliable: boolean?, inboundMiddleware: Types.ServerMiddleware?, outboundMiddleware: Types.ServerMiddleware? ) local self = setmetatable({}, RemoteSignal) self._re = if unreliable == true then Instance.new("UnreliableRemoteEvent") else Instance.new("RemoteEvent") self._re.Name = name self._re.Parent = parent if outboundMiddleware and #outboundMiddleware > 0 then self._hasOutbound = true self._outbound = outboundMiddleware else self._hasOutbound = false end if inboundMiddleware and #inboundMiddleware > 0 then self._directConnect = false self._signal = Signal.new() self._re.OnServerEvent:Connect(function(player, ...) local args = table.pack(...) for _, middlewareFunc in inboundMiddleware do local middlewareResult = table.pack(middlewareFunc(player, args)) if not middlewareResult[1] then return end args.n = #args end self._signal:Fire(player, table.unpack(args, 1, args.n)) end) else self._directConnect = true end return self end --[=[ @return boolean Returns `true` if the underlying RemoteSignal is bound to an UnreliableRemoteEvent object. ]=] function RemoteSignal:IsUnreliable(): boolean return self._re:IsA("UnreliableRemoteEvent") end --[=[ @param fn (player: Player, ...: any) -> nil -- The function to connect @return Connection Connect a function to the signal. Anytime a matching ClientRemoteSignal on a client fires, the connected function will be invoked with the arguments passed by the client. ]=] function RemoteSignal:Connect(fn) if self._directConnect then return self._re.OnServerEvent:Connect(fn) else return self._signal:Connect(fn) end end function RemoteSignal:_processOutboundMiddleware(player: Player?, ...: any) if not self._hasOutbound then return ... end local args = table.pack(...) for _, middlewareFunc in self._outbound do local middlewareResult = table.pack(middlewareFunc(player, args)) if not middlewareResult[1] then return table.unpack(middlewareResult, 2, middlewareResult.n) end args.n = #args end return table.unpack(args, 1, args.n) end --[=[ @param player Player -- The target client @param ... any -- Arguments passed to the client Fires the signal at the specified client with any arguments. :::note Outbound Middleware All arguments pass through any outbound middleware (if any) before being sent to the clients. ::: ]=] function RemoteSignal:Fire(player: Player, ...: any) self._re:FireClient(player, self:_processOutboundMiddleware(player, ...)) end --[=[ @param ... any Fires the signal at _all_ clients with any arguments. :::note Outbound Middleware All arguments pass through any outbound middleware (if any) before being sent to the clients. ::: ]=] function RemoteSignal:FireAll(...: any) self._re:FireAllClients(self:_processOutboundMiddleware(nil, ...)) end --[=[ @param ignorePlayer Player -- The client to ignore @param ... any -- Arguments passed to the other clients Fires the signal to all clients _except_ the specified client. :::note Outbound Middleware All arguments pass through any outbound middleware (if any) before being sent to the clients. ::: ]=] function RemoteSignal:FireExcept(ignorePlayer: Player, ...: any) self:FireFilter(function(plr) return plr ~= ignorePlayer end, ...) end --[=[ @param predicate (player: Player, argsFromFire: ...) -> boolean @param ... any -- Arguments to pass to the clients (and to the predicate) Fires the signal at any clients that pass the `predicate` function test. This can be used to fire signals with much more control logic. :::note Outbound Middleware All arguments pass through any outbound middleware (if any) before being sent to the clients. ::: :::caution Predicate Before Middleware The arguments sent to the predicate are sent _before_ getting transformed by any middleware. ::: ```lua -- Fire signal to players of the same team: remoteSignal:FireFilter(function(player) return player.Team.Name == "Best Team" end) ``` ]=] function RemoteSignal:FireFilter(predicate: (Player, ...any) -> boolean, ...: any) for _, player in Players:GetPlayers() do if predicate(player, ...) then self._re:FireClient(player, self:_processOutboundMiddleware(nil, ...)) end end end --[=[ Fires a signal at the clients within the `players` table. This is useful when signals need to fire for a specific set of players. For more complex firing, see `FireFilter`. :::note Outbound Middleware All arguments pass through any outbound middleware (if any) before being sent to the clients. ::: ```lua local players = {somePlayer1, somePlayer2, somePlayer3} remoteSignal:FireFor(players, "Hello, players!") ``` ]=] function RemoteSignal:FireFor(players: { Player }, ...: any) for _, player in players do self._re:FireClient(player, self:_processOutboundMiddleware(nil, ...)) end end --[=[ Destroys the RemoteSignal object. ]=] function RemoteSignal:Destroy() self._re:Destroy() if self._signal then self._signal:Destroy() end end return RemoteSignal ]]> ServerComm (shouldContinue: boolean, ...: any) The middleware function takes the client player and the arguments (as a table array), and should return `true|false` to indicate if the process should continue. If returning `false`, the optional varargs after the `false` are used as the new return values to whatever was calling the middleware. ]=] --[=[ @within ServerComm @type ServerMiddleware {ServerMiddlewareFn} Array of middleware functions. ]=] --[=[ @return ServerComm Constructs a ServerComm object. The `namespace` parameter is used in cases where more than one ServerComm object may be bound to the same object. Otherwise, a default namespace is used. ```lua local serverComm = ServerComm.new(game:GetService("ReplicatedStorage")) -- If many might exist in the given parent, use a unique namespace: local serverComm = ServerComm.new(game:GetService("ReplicatedStorage"), "MyNamespace") ``` ]=] function ServerComm.new(parent: Instance, namespace: string?) assert(Util.IsServer, "ServerComm must be constructed from the server") assert(typeof(parent) == "Instance", "Parent must be of type Instance") local ns = Util.DefaultCommFolderName if namespace then ns = namespace end assert(not parent:FindFirstChild(ns), "Parent already has another ServerComm bound to namespace " .. ns) local self = setmetatable({}, ServerComm) self._instancesFolder = Instance.new("Folder") self._instancesFolder.Name = ns self._instancesFolder.Parent = parent return self end --[=[ @param name string @param fn (player: Player, ...: any) -> ...: any @param inboundMiddleware ServerMiddleware? @param outboundMiddleware ServerMiddleware? @return RemoteFunction Creates a RemoteFunction and binds the given function to it. Inbound and outbound middleware can be applied if desired. ```lua local function GetSomething(player: Player) return "Something" end serverComm:BindFunction("GetSomething", GetSomething) ``` ]=] function ServerComm:BindFunction( name: string, fn: Types.FnBind, inboundMiddleware: Types.ServerMiddleware?, outboundMiddleware: Types.ServerMiddleware? ): RemoteFunction return Comm.BindFunction(self._instancesFolder, name, fn, inboundMiddleware, outboundMiddleware) end --[=[ @param tbl table @param name string @param inboundMiddleware ServerMiddleware? @param outboundMiddleware ServerMiddleware? @return RemoteFunction Binds a function to a table method. The name must match the name of the method in the table. The same name will be used on the client to access the given function. ```lua local MyObject = { _Data = 10, } function MyObject:GetData(player: Player) return self._Data end serverComm:WrapMethod(MyObject, "GetData") ``` ]=] function ServerComm:WrapMethod( tbl: {}, name: string, inboundMiddleware: Types.ServerMiddleware?, outboundMiddleware: Types.ServerMiddleware? ): RemoteFunction return Comm.WrapMethod(self._instancesFolder, tbl, name, inboundMiddleware, outboundMiddleware) end --[=[ @param name string @param unreliable boolean? @param inboundMiddleware ServerMiddleware? @param outboundMiddleware ServerMiddleware? @return RemoteSignal Creates a signal that can be used to fire data to the clients or receive data from the clients. By default, signals use RemoteEvents internally. However, if the `unreliable` argument is set to `true`, then an UnreliableRemoteEvent will be used instead. ```lua local mySignal = serverComm:CreateSignal("MySignal") -- Examples of firing in different ways (see docs for RemoteSignal for further info): mySignal:Fire(somePlayer, "Hello world") mySignal:FireAll("Hi there") mySignal:FireExcept(somePlayer, "Hello everyone except " .. somePlayer.Name) mySignal:FireFilter(function(player) return player.Team == someCoolTeam end, "Hello cool team") -- Example of listening for clients to send data: mySignal:Connect(function(player, message) print("Got a message from " .. player.Name .. ":", message) end) ``` ]=] function ServerComm:CreateSignal( name: string, unreliable: boolean?, inboundMiddleware: Types.ServerMiddleware?, outboundMiddleware: Types.ServerMiddleware? ) return Comm.CreateSignal(self._instancesFolder, name, unreliable, inboundMiddleware, outboundMiddleware) end --[=[ @param name string @param initialValue any @param inboundMiddleware ServerMiddleware? @param outboundMiddleware ServerMiddleware? @return RemoteProperty Create a property object which will replicate its property value to the clients. Optionally, specific clients can be targeted with different property values. ```lua local comm = Comm.ServerComm.new(game:GetService("ReplicatedStorage")) local mapInfo = comm:CreateProperty("MapInfo", { MapName = "TheAwesomeMap", MapDuration = 60, }) -- Change the data: mapInfo:Set({ MapName = "AnotherMap", MapDuration = 30, }) -- Change the data for one player: mapInfo:SetFor(somePlayer, { MapName = "ASpecialMapForYou", MapDuration = 90, }) -- Change data based on a predicate function: mapInfo:SetFilter(function(player) return player.Team == game.Teams.SomeSpecialTeam end, { MapName = "TeamMap", MapDuration = 20, }) ``` ]=] function ServerComm:CreateProperty( name: string, initialValue: any, inboundMiddleware: Types.ServerMiddleware?, outboundMiddleware: Types.ServerMiddleware? ) return Comm.CreateProperty(self._instancesFolder, name, initialValue, inboundMiddleware, outboundMiddleware) end --[=[ Destroy the ServerComm object. ]=] function ServerComm:Destroy() self._instancesFolder:Destroy() end return ServerComm ]]> Types ...any export type ServerMiddlewareFn = (Instance, Args) -> (boolean, ...any) export type ServerMiddleware = { ServerMiddlewareFn } export type ClientMiddlewareFn = (Args) -> (boolean, ...any) export type ClientMiddleware = { ClientMiddlewareFn } return nil ]]> Util wally return { dependencies = { Option = "sleitnick/option@1", Promise = "evaera/promise@4", Signal = "sleitnick/signal@2", }, package = { authors = {"Stephen Leitnick"}, description = "Comm library for remote communication", license = "MIT", name = "sleitnick/comm", realm = "shared", registry = "https://github.com/UpliftGames/wally-index", version = "1.0.1", }, } sleitnick_knit@1.7.0 Comm Promise knit KnitClient (shouldContinue: boolean, ...: any) @within KnitClient For more info, see [ClientComm](https://sleitnick.github.io/RbxUtil/api/ClientComm/) documentation. ]=] type ClientMiddlewareFn = (args: { any }) -> (boolean, ...any) --[=[ @type ClientMiddleware {ClientMiddlewareFn} @within KnitClient An array of client middleware functions. ]=] type ClientMiddleware = { ClientMiddlewareFn } --[=[ @type PerServiceMiddleware {[string]: Middleware} @within KnitClient ]=] type PerServiceMiddleware = { [string]: Middleware } --[=[ @interface ControllerDef .Name string .[any] any @within KnitClient Used to define a controller when creating it in `CreateController`. ]=] type ControllerDef = { Name: string, [any]: any, } --[=[ @interface Controller .Name string .[any] any @within KnitClient ]=] type Controller = { Name: string, [any]: any, } --[=[ @interface Service .[any] any @within KnitClient ]=] type Service = { [any]: any, } --[=[ @interface KnitOptions .ServicePromises boolean? .Middleware Middleware? .PerServiceMiddleware PerServiceMiddleware? @within KnitClient - `ServicePromises` defaults to `true` and indicates if service methods use promises. - Each service will go through the defined middleware, unless the service has middleware defined in `PerServiceMiddleware`. ]=] type KnitOptions = { ServicePromises: boolean, Middleware: Middleware?, PerServiceMiddleware: PerServiceMiddleware?, } local defaultOptions: KnitOptions = { ServicePromises = true, Middleware = nil, PerServiceMiddleware = {}, } local selectedOptions = nil --[=[ @class KnitClient @client ]=] local KnitClient = {} --[=[ @prop Player Player @within KnitClient @readonly Reference to the LocalPlayer. ]=] KnitClient.Player = game:GetService("Players").LocalPlayer --[=[ @prop Util Folder @within KnitClient @readonly References the Util folder. Should only be accessed when using Knit as a standalone module. If using Knit from Wally, modules should just be pulled in via Wally instead of relying on Knit's Util folder, as this folder only contains what is necessary for Knit to run in Wally mode. ]=] KnitClient.Util = (script.Parent :: Instance).Parent local Promise = require(KnitClient.Util.Promise) local Comm = require(KnitClient.Util.Comm) local ClientComm = Comm.ClientComm local controllers: { [string]: Controller } = {} local services: { [string]: Service } = {} local servicesFolder = nil local started = false local startedComplete = false local onStartedComplete = Instance.new("BindableEvent") local function DoesControllerExist(controllerName: string): boolean local controller: Controller? = controllers[controllerName] return controller ~= nil end local function GetServicesFolder() if not servicesFolder then servicesFolder = (script.Parent :: Instance):WaitForChild("Services") end return servicesFolder end local function GetMiddlewareForService(serviceName: string) local knitMiddleware = if selectedOptions.Middleware ~= nil then selectedOptions.Middleware else {} local serviceMiddleware = selectedOptions.PerServiceMiddleware[serviceName] return if serviceMiddleware ~= nil then serviceMiddleware else knitMiddleware end local function BuildService(serviceName: string) local folder = GetServicesFolder() local middleware = GetMiddlewareForService(serviceName) local clientComm = ClientComm.new(folder, selectedOptions.ServicePromises, serviceName) local service = clientComm:BuildObject(middleware.Inbound, middleware.Outbound) services[serviceName] = service return service end --[=[ Creates a new controller. :::caution Controllers must be created _before_ calling `Knit.Start()`. ::: ```lua -- Create a controller local MyController = Knit.CreateController { Name = "MyController", } function MyController:KnitStart() print("MyController started") end function MyController:KnitInit() print("MyController initialized") end ``` ]=] function KnitClient.CreateController(controllerDef: ControllerDef): Controller assert(type(controllerDef) == "table", `Controller must be a table; got {type(controllerDef)}`) assert(type(controllerDef.Name) == "string", `Controller.Name must be a string; got {type(controllerDef.Name)}`) assert(#controllerDef.Name > 0, "Controller.Name must be a non-empty string") assert(not DoesControllerExist(controllerDef.Name), `Controller {controllerDef.Name} already exists`) assert(not started, `Controllers cannot be created after calling "Knit.Start()"`) local controller = controllerDef :: Controller controllers[controller.Name] = controller return controller end --[=[ Requires all the modules that are children of the given parent. This is an easy way to quickly load all controllers that might be in a folder. ```lua Knit.AddControllers(somewhere.Controllers) ``` ]=] function KnitClient.AddControllers(parent: Instance): { Controller } assert(not started, `Controllers cannot be added after calling "Knit.Start()"`) local addedControllers = {} for _, v in parent:GetChildren() do if not v:IsA("ModuleScript") then continue end table.insert(addedControllers, require(v)) end return addedControllers end --[=[ Requires all the modules that are descendants of the given parent. ]=] function KnitClient.AddControllersDeep(parent: Instance): { Controller } assert(not started, `Controllers cannot be added after calling "Knit.Start()"`) local addedControllers = {} for _, v in parent:GetDescendants() do if not v:IsA("ModuleScript") then continue end table.insert(addedControllers, require(v)) end return addedControllers end --[=[ Returns a Service object which is a reflection of the remote objects within the Client table of the given service. Throws an error if the service is not found. If a service's Client table contains RemoteSignals and/or RemoteProperties, these values are reflected as [ClientRemoteSignals](https://sleitnick.github.io/RbxUtil/api/ClientRemoteSignal) and [ClientRemoteProperties](https://sleitnick.github.io/RbxUtil/api/ClientRemoteProperty). ```lua -- Server-side service creation: local MyService = Knit.CreateService { Name = "MyService", Client = { MySignal = Knit.CreateSignal(), MyProperty = Knit.CreateProperty("Hello"), }, } function MyService:AddOne(player, number) return number + 1 end ------------------------------------------------- -- Client-side service reflection: local MyService = Knit.GetService("MyService") -- Call a method: local num = MyService:AddOne(5) --> 6 -- Fire a signal to the server: MyService.MySignal:Fire("Hello") -- Listen for signals from the server: MyService.MySignal:Connect(function(message) print(message) end) -- Observe the initial value and changes to properties: MyService.MyProperty:Observe(function(value) print(value) end) ``` :::caution Services are only exposed to the client if the service has remote-based content in the Client table. If not, the service will not be visible to the client. `KnitClient.GetService` will only work on services that expose remote-based content on their Client tables. ::: ]=] function KnitClient.GetService(serviceName: string): Service local service = services[serviceName] if service then return service end assert(started, "Cannot call GetService until Knit has been started") assert(type(serviceName) == "string", `ServiceName must be a string; got {type(serviceName)}`) return BuildService(serviceName) end --[=[ Gets the controller by name. Throws an error if the controller is not found. ]=] function KnitClient.GetController(controllerName: string): Controller local controller = controllers[controllerName] if controller then return controller end assert(started, "Cannot call GetController until Knit has been started") assert(type(controllerName) == "string", `ControllerName must be a string; got {type(controllerName)}`) error(`Could not find controller "{controllerName}". Check to verify a controller with this name exists.`, 2) end --[=[ Gets a table of all controllers. ]=] function KnitClient.GetControllers(): { [string]: Controller } assert(started, "Cannot call GetControllers until Knit has been started") return controllers end --[=[ @return Promise Starts Knit. Should only be called once per client. ```lua Knit.Start():andThen(function() print("Knit started!") end):catch(warn) ``` By default, service methods exposed to the client will return promises. To change this behavior, set the `ServicePromises` option to `false`: ```lua Knit.Start({ServicePromises = false}):andThen(function() print("Knit started!") end):catch(warn) ``` ]=] function KnitClient.Start(options: KnitOptions?) if started then return Promise.reject("Knit already started") end started = true table.freeze(controllers) if options == nil then selectedOptions = defaultOptions else assert(typeof(options) == "table", `KnitOptions should be a table or nil; got {typeof(options)}`) selectedOptions = options for k, v in defaultOptions do if selectedOptions[k] == nil then selectedOptions[k] = v end end end if type(selectedOptions.PerServiceMiddleware) ~= "table" then selectedOptions.PerServiceMiddleware = {} end return Promise.new(function(resolve) -- Init: local promisesStartControllers = {} for _, controller in controllers do if type(controller.KnitInit) == "function" then table.insert( promisesStartControllers, Promise.new(function(r) debug.setmemorycategory(controller.Name) controller:KnitInit() r() end) ) end end resolve(Promise.all(promisesStartControllers)) end):andThen(function() -- Start: for _, controller in controllers do if type(controller.KnitStart) == "function" then task.spawn(function() debug.setmemorycategory(controller.Name) controller:KnitStart() end) end end startedComplete = true onStartedComplete:Fire() task.defer(function() onStartedComplete:Destroy() end) end) end --[=[ @return Promise Returns a promise that is resolved once Knit has started. This is useful for any code that needs to tie into Knit controllers but is not the script that called `Start`. ```lua Knit.OnStart():andThen(function() local MyController = Knit.GetController("MyController") MyController:DoSomething() end):catch(warn) ``` ]=] function KnitClient.OnStart() if startedComplete then return Promise.resolve() else return Promise.fromEvent(onStartedComplete.Event) end end return KnitClient ]]> KnitServer (shouldContinue: boolean, ...: any) @within KnitServer For more info, see [ServerComm](https://sleitnick.github.io/RbxUtil/api/ServerComm/) documentation. ]=] type ServerMiddlewareFn = (player: Player, args: { any }) -> (boolean, ...any) --[=[ @type ServerMiddleware {ServerMiddlewareFn} @within KnitServer An array of server middleware functions. ]=] type ServerMiddleware = { ServerMiddlewareFn } --[=[ @interface ServiceDef .Name string .Client table? .Middleware Middleware? .[any] any @within KnitServer Used to define a service when creating it in `CreateService`. The middleware tables provided will be used instead of the Knit-level middleware (if any). This allows fine-tuning each service's middleware. These can also be left out or `nil` to not include middleware. ]=] type ServiceDef = { Name: string, Client: { [any]: any }?, Middleware: Middleware?, [any]: any, } --[=[ @interface Service .Name string .Client ServiceClient .KnitComm Comm .[any] any @within KnitServer ]=] type Service = { Name: string, Client: ServiceClient, KnitComm: any, [any]: any, } --[=[ @interface ServiceClient .Server Service .[any] any @within KnitServer ]=] type ServiceClient = { Server: Service, [any]: any, } --[=[ @interface KnitOptions .Middleware Middleware? @within KnitServer - Middleware will apply to all services _except_ ones that define their own middleware. ]=] type KnitOptions = { Middleware: Middleware?, } local defaultOptions: KnitOptions = { Middleware = nil, } local selectedOptions = nil --[=[ @class KnitServer @server Knit server-side lets developers create services and expose methods and signals to the clients. ```lua local Knit = require(somewhere.Knit) -- Load service modules within some folder: Knit.AddServices(somewhere.Services) -- Start Knit: Knit.Start():andThen(function() print("Knit started") end):catch(warn) ``` ]=] local KnitServer = {} --[=[ @prop Util Folder @within KnitServer @readonly References the Util folder. Should only be accessed when using Knit as a standalone module. If using Knit from Wally, modules should just be pulled in via Wally instead of relying on Knit's Util folder, as this folder only contains what is necessary for Knit to run in Wally mode. ]=] KnitServer.Util = (script.Parent :: Instance).Parent local SIGNAL_MARKER = newproxy(true) getmetatable(SIGNAL_MARKER).__tostring = function() return "SIGNAL_MARKER" end local UNRELIABLE_SIGNAL_MARKER = newproxy(true) getmetatable(UNRELIABLE_SIGNAL_MARKER).__tostring = function() return "UNRELIABLE_SIGNAL_MARKER" end local PROPERTY_MARKER = newproxy(true) getmetatable(PROPERTY_MARKER).__tostring = function() return "PROPERTY_MARKER" end local knitRepServiceFolder = Instance.new("Folder") knitRepServiceFolder.Name = "Services" local Promise = require(KnitServer.Util.Promise) local Comm = require(KnitServer.Util.Comm) local ServerComm = Comm.ServerComm local services: { [string]: Service } = {} local started = false local startedComplete = false local onStartedComplete = Instance.new("BindableEvent") local function DoesServiceExist(serviceName: string): boolean local service: Service? = services[serviceName] return service ~= nil end --[=[ Constructs a new service. :::caution Services must be created _before_ calling `Knit.Start()`. ::: ```lua -- Create a service local MyService = Knit.CreateService { Name = "MyService", Client = {}, } -- Expose a ToAllCaps remote function to the clients function MyService.Client:ToAllCaps(player, msg) return msg:upper() end -- Knit will call KnitStart after all services have been initialized function MyService:KnitStart() print("MyService started") end -- Knit will call KnitInit when Knit is first started function MyService:KnitInit() print("MyService initialize") end ``` ]=] function KnitServer.CreateService(serviceDef: ServiceDef): Service assert(type(serviceDef) == "table", `Service must be a table; got {type(serviceDef)}`) assert(type(serviceDef.Name) == "string", `Service.Name must be a string; got {type(serviceDef.Name)}`) assert(#serviceDef.Name > 0, "Service.Name must be a non-empty string") assert(not DoesServiceExist(serviceDef.Name), `Service "{serviceDef.Name}" already exists`) assert(not started, `Services cannot be created after calling "Knit.Start()"`) local service = serviceDef service.KnitComm = ServerComm.new(knitRepServiceFolder, serviceDef.Name) if type(service.Client) ~= "table" then service.Client = { Server = service } else if service.Client.Server ~= service then service.Client.Server = service end end services[service.Name] = service return service end --[=[ Requires all the modules that are children of the given parent. This is an easy way to quickly load all services that might be in a folder. ```lua Knit.AddServices(somewhere.Services) ``` ]=] function KnitServer.AddServices(parent: Instance): { Service } assert(not started, `Services cannot be added after calling "Knit.Start()"`) local addedServices = {} for _, v in parent:GetChildren() do if not v:IsA("ModuleScript") then continue end table.insert(addedServices, require(v)) end return addedServices end --[=[ Requires all the modules that are descendants of the given parent. ]=] function KnitServer.AddServicesDeep(parent: Instance): { Service } assert(not started, `Services cannot be added after calling "Knit.Start()"`) local addedServices = {} for _, v in parent:GetDescendants() do if not v:IsA("ModuleScript") then continue end table.insert(addedServices, require(v)) end return addedServices end --[=[ Gets the service by name. Throws an error if the service is not found. ]=] function KnitServer.GetService(serviceName: string): Service assert(started, "Cannot call GetService until Knit has been started") assert(type(serviceName) == "string", `ServiceName must be a string; got {type(serviceName)}`) return assert(services[serviceName], `Could not find service "{serviceName}"`) :: Service end --[=[ Gets a table of all services. ]=] function KnitServer.GetServices(): { [string]: Service } assert(started, "Cannot call GetServices until Knit has been started") return services end --[=[ @return SIGNAL_MARKER Returns a marker that will transform the current key into a RemoteSignal once the service is created. Should only be called within the Client table of a service. See [RemoteSignal](https://sleitnick.github.io/RbxUtil/api/RemoteSignal) documentation for more info. ```lua local MyService = Knit.CreateService { Name = "MyService", Client = { -- Create the signal marker, which will turn into a -- RemoteSignal when Knit.Start() is called: MySignal = Knit.CreateSignal(), }, } function MyService:KnitInit() -- Connect to the signal: self.Client.MySignal:Connect(function(player, ...) end) end ``` ]=] function KnitServer.CreateSignal() return SIGNAL_MARKER end --[=[ @return UNRELIABLE_SIGNAL_MARKER Returns a marker that will transform the current key into an unreliable RemoteSignal once the service is created. Should only be called within the Client table of a service. See [RemoteSignal](https://sleitnick.github.io/RbxUtil/api/RemoteSignal) documentation for more info. :::info Unreliable Events Internally, this uses UnreliableRemoteEvents, which allows for network communication that is unreliable and unordered. This is useful for events that are not crucial for gameplay, since the delivery of the events may occur out of order or not at all. See the documentation for [UnreliableRemoteEvents](https://create.roblox.com/docs/reference/engine/classes/UnreliableRemoteEvent) for more info. ]=] function KnitServer.CreateUnreliableSignal() return UNRELIABLE_SIGNAL_MARKER end --[=[ @return PROPERTY_MARKER Returns a marker that will transform the current key into a RemoteProperty once the service is created. Should only be called within the Client table of a service. An initial value can be passed along as well. RemoteProperties are great for replicating data to all of the clients. Different data can also be set per client. See [RemoteProperty](https://sleitnick.github.io/RbxUtil/api/RemoteProperty) documentation for more info. ```lua local MyService = Knit.CreateService { Name = "MyService", Client = { -- Create the property marker, which will turn into a -- RemoteProperty when Knit.Start() is called: MyProperty = Knit.CreateProperty("HelloWorld"), }, } function MyService:KnitInit() -- Change the value of the property: self.Client.MyProperty:Set("HelloWorldAgain") end ``` ]=] function KnitServer.CreateProperty(initialValue: any) return { PROPERTY_MARKER, initialValue } end --[=[ @return Promise Starts Knit. Should only be called once. Optionally, `KnitOptions` can be passed in order to set Knit's custom configurations. :::caution Be sure that all services have been created _before_ calling `Start`. Services cannot be added later. ::: ```lua Knit.Start():andThen(function() print("Knit started!") end):catch(warn) ``` Example of Knit started with options: ```lua Knit.Start({ Middleware = { Inbound = { function(player, args) print("Player is giving following args to server:", args) return true end }, }, }):andThen(function() print("Knit started!") end):catch(warn) ``` ]=] function KnitServer.Start(options: KnitOptions?) if started then return Promise.reject("Knit already started") end started = true table.freeze(services) if options == nil then selectedOptions = defaultOptions else assert(typeof(options) == "table", `KnitOptions should be a table or nil; got {typeof(options)}`) selectedOptions = options for k, v in defaultOptions do if selectedOptions[k] == nil then selectedOptions[k] = v end end end return Promise.new(function(resolve) local knitMiddleware = if selectedOptions.Middleware ~= nil then selectedOptions.Middleware else {} -- Bind remotes: for _, service in services do local middleware = if service.Middleware ~= nil then service.Middleware else {} local inbound = if middleware.Inbound ~= nil then middleware.Inbound else knitMiddleware.Inbound local outbound = if middleware.Outbound ~= nil then middleware.Outbound else knitMiddleware.Outbound service.Middleware = nil for k, v in service.Client do if type(v) == "function" then service.KnitComm:WrapMethod(service.Client, k, inbound, outbound) elseif v == SIGNAL_MARKER then service.Client[k] = service.KnitComm:CreateSignal(k, false, inbound, outbound) elseif v == UNRELIABLE_SIGNAL_MARKER then service.Client[k] = service.KnitComm:CreateSignal(k, true, inbound, outbound) elseif type(v) == "table" and v[1] == PROPERTY_MARKER then service.Client[k] = service.KnitComm:CreateProperty(k, v[2], inbound, outbound) end end end -- Init: local promisesInitServices = {} for _, service in services do if type(service.KnitInit) == "function" then table.insert( promisesInitServices, Promise.new(function(r) debug.setmemorycategory(service.Name) service:KnitInit() r() end) ) end end resolve(Promise.all(promisesInitServices)) end):andThen(function() -- Start: for _, service in services do if type(service.KnitStart) == "function" then task.spawn(function() debug.setmemorycategory(service.Name) service:KnitStart() end) end end startedComplete = true onStartedComplete:Fire() task.defer(function() onStartedComplete:Destroy() end) -- Expose service remotes to everyone: knitRepServiceFolder.Parent = script.Parent end) end --[=[ @return Promise Returns a promise that is resolved once Knit has started. This is useful for any code that needs to tie into Knit services but is not the script that called `Start`. ```lua Knit.OnStart():andThen(function() local MyService = Knit.Services.MyService MyService:DoSomething() end):catch(warn) ``` ]=] function KnitServer.OnStart() if startedComplete then return Promise.resolve() else return Promise.fromEvent(onStartedComplete.Event) end end return KnitServer ]]> wally return { dependencies = { Comm = "sleitnick/comm@^1", Promise = "evaera/promise@^4", }, package = { description = "Knit is a lightweight game framework", license = "MIT", name = "sleitnick/knit", realm = "shared", registry = "https://github.com/UpliftGames/wally-index", version = "1.7.0", }, } wally_bundle return { dependencies = { Comm = "sleitnick/comm@^1", Component = "sleitnick/component@^2", EnumList = "sleitnick/enum-list@^2", Input = "sleitnick/input@^2", Option = "sleitnick/option@^1", Promise = "evaera/promise@^4", Signal = "sleitnick/signal@^2", Streamable = "sleitnick/streamable@^1", TableUtil = "sleitnick/table-util@^1", Timer = "sleitnick/timer@^1", Trove = "sleitnick/trove@^1", }, package = { name = "sleitnick/knit-bundle", realm = "shared", registry = "https://github.com/UpliftGames/wally-index", version = "0.1.0", }, } sleitnick_option@1.0.5 option any None: () -> any } CONSTRUCTORS: Option.Some(anyNonNilValue): Option Option.Wrap(anyValue): Option STATIC FIELDS: Option.None: Option STATIC METHODS: Option.Is(obj): boolean METHODS: opt:Match(): (matches: MatchTable) -> any opt:IsSome(): boolean opt:IsNone(): boolean opt:Unwrap(): any opt:Expect(errMsg: string): any opt:ExpectNone(errMsg: string): void opt:UnwrapOr(default: any): any opt:UnwrapOrElse(default: () -> any): any opt:And(opt2: Option): Option opt:AndThen(predicate: (unwrapped: any) -> Option): Option opt:Or(opt2: Option): Option opt:OrElse(orElseFunc: () -> Option): Option opt:XOr(opt2: Option): Option opt:Contains(value: any): boolean -------------------------------------------------------------------- Options are useful for handling nil-value cases. Any time that an operation might return nil, it is useful to instead return an Option, which will indicate that the value might be nil, and should be explicitly checked before using the value. This will help prevent common bugs caused by nil values that can fail silently. Example: local result1 = Option.Some(32) local result2 = Option.Some(nil) local result3 = Option.Some("Hi") local result4 = Option.Some(nil) local result5 = Option.None -- Use 'Match' to match if the value is Some or None: result1:Match { Some = function(value) print(value) end; None = function() print("No value") end; } -- Raw check: if result2:IsSome() then local value = result2:Unwrap() -- Explicitly call Unwrap print("Value of result2:", value) end if result3:IsNone() then print("No result for result3") end -- Bad, will throw error bc result4 is none: local value = result4:Unwrap() --]] export type MatchTable = { Some: (value: T) -> any, None: () -> any, } export type MatchFn = (matches: MatchTable) -> any export type DefaultFn = () -> T export type AndThenFn = (value: T) -> Option export type OrElseFn = () -> Option export type Option = typeof(setmetatable( {} :: { Match: (self: Option) -> MatchFn, IsSome: (self: Option) -> boolean, IsNone: (self: Option) -> boolean, Contains: (self: Option, value: T) -> boolean, Unwrap: (self: Option) -> T, Expect: (self: Option, errMsg: string) -> T, ExpectNone: (self: Option, errMsg: string) -> nil, UnwrapOr: (self: Option, default: T) -> T, UnwrapOrElse: (self: Option, defaultFn: DefaultFn) -> T, And: (self: Option, opt2: Option) -> Option, AndThen: (self: Option, predicate: AndThenFn) -> Option, Or: (self: Option, opt2: Option) -> Option, OrElse: (self: Option, orElseFunc: OrElseFn) -> Option, XOr: (self: Option, opt2: Option) -> Option, }, {} :: { __index: Option, } )) local CLASSNAME = "Option" --[=[ @class Option Represents an optional value in Lua. This is useful to avoid `nil` bugs, which can go silently undetected within code and cause hidden or hard-to-find bugs. ]=] local Option = {} Option.__index = Option function Option._new(value) local self = setmetatable({ ClassName = CLASSNAME, _v = value, _s = (value ~= nil), }, Option) return self end --[=[ @param value T @return Option Creates an Option instance with the given value. Throws an error if the given value is `nil`. ]=] function Option.Some(value) assert(value ~= nil, "Option.Some() value cannot be nil") return Option._new(value) end --[=[ @param value T @return Option | Option Safely wraps the given value as an option. If the value is `nil`, returns `Option.None`, otherwise returns `Option.Some(value)`. ]=] function Option.Wrap(value) if value == nil then return Option.None else return Option.Some(value) end end --[=[ @param obj any @return boolean Returns `true` if `obj` is an Option. ]=] function Option.Is(obj) return type(obj) == "table" and getmetatable(obj) == Option end --[=[ @param obj any Throws an error if `obj` is not an Option. ]=] function Option.Assert(obj) assert(Option.Is(obj), "Result was not of type Option") end --[=[ @param data table @return Option Deserializes the data into an Option. This data should have come from the `option:Serialize()` method. ]=] function Option.Deserialize(data) -- type data = {ClassName: string, Value: any} assert(type(data) == "table" and data.ClassName == CLASSNAME, "Invalid data for deserializing Option") return data.Value == nil and Option.None or Option.Some(data.Value) end --[=[ @return table Returns a serialized version of the option. ]=] function Option:Serialize() return { ClassName = self.ClassName, Value = self._v, } end --[=[ @param matches {Some: (value: any) -> any, None: () -> any} @return any Matches against the option. ```lua local opt = Option.Some(32) opt:Match { Some = function(num) print("Number", num) end, None = function() print("No value") end, } ``` ]=] function Option:Match(matches) local onSome = matches.Some local onNone = matches.None assert(type(onSome) == "function", "Missing 'Some' match") assert(type(onNone) == "function", "Missing 'None' match") if self:IsSome() then return onSome(self:Unwrap()) else return onNone() end end --[=[ @return boolean Returns `true` if the option has a value. ]=] function Option:IsSome() return self._s end --[=[ @return boolean Returns `true` if the option is None. ]=] function Option:IsNone() return not self._s end --[=[ @param msg string @return value: any Unwraps the value in the option, otherwise throws an error with `msg` as the error message. ```lua local opt = Option.Some(10) print(opt:Expect("No number")) -> 10 print(Option.None:Expect("No number")) -- Throws an error "No number" ``` ]=] function Option:Expect(msg) assert(self:IsSome(), msg) return self._v end --[=[ @param msg string Throws an error with `msg` as the error message if the value is _not_ None. ]=] function Option:ExpectNone(msg) assert(self:IsNone(), msg) end --[=[ @return value: any Returns the value in the option, or throws an error if the option is None. ]=] function Option:Unwrap() return self:Expect("Cannot unwrap option of None type") end --[=[ @param default any @return value: any If the option holds a value, returns the value. Otherwise, returns `default`. ]=] function Option:UnwrapOr(default) if self:IsSome() then return self:Unwrap() else return default end end --[=[ @param defaultFn () -> any @return value: any If the option holds a value, returns the value. Otherwise, returns the result of the `defaultFn` function. ]=] function Option:UnwrapOrElse(defaultFn) if self:IsSome() then return self:Unwrap() else return defaultFn() end end --[=[ @param optionB Option @return Option Returns `optionB` if the calling option has a value, otherwise returns None. ```lua local optionA = Option.Some(32) local optionB = Option.Some(64) local opt = optionA:And(optionB) -- opt == optionB local optionA = Option.None local optionB = Option.Some(64) local opt = optionA:And(optionB) -- opt == Option.None ``` ]=] function Option:And(optionB) if self:IsSome() then return optionB else return Option.None end end --[=[ @param andThenFn (value: any) -> Option @return value: Option If the option holds a value, then the `andThenFn` function is called with the held value of the option, and then the resultant Option returned by the `andThenFn` is returned. Otherwise, None is returned. ```lua local optA = Option.Some(32) local optB = optA:AndThen(function(num) return Option.Some(num * 2) end) print(optB:Expect("Expected number")) --> 64 ``` ]=] function Option:AndThen(andThenFn) if self:IsSome() then local result = andThenFn(self:Unwrap()) Option.Assert(result) return result else return Option.None end end --[=[ @param optionB Option @return Option If caller has a value, returns itself. Otherwise, returns `optionB`. ]=] function Option:Or(optionB) if self:IsSome() then return self else return optionB end end --[=[ @param orElseFn () -> Option @return Option If caller has a value, returns itself. Otherwise, returns the option generated by the `orElseFn` function. ]=] function Option:OrElse(orElseFn) if self:IsSome() then return self else local result = orElseFn() Option.Assert(result) return result end end --[=[ @param optionB Option @return Option If both `self` and `optionB` have values _or_ both don't have a value, then this returns None. Otherwise, it returns the option that does have a value. ]=] function Option:XOr(optionB) local someOptA = self:IsSome() local someOptB = optionB:IsSome() if someOptA == someOptB then return Option.None elseif someOptA then return self else return optionB end end --[=[ @param predicate (value: any) -> boolean @return Option Returns `self` if this option has a value and the predicate returns `true. Otherwise, returns None. ]=] function Option:Filter(predicate) if self:IsNone() or not predicate(self._v) then return Option.None else return self end end --[=[ @param value any @return boolean Returns `true` if this option contains `value`. ]=] function Option:Contains(value) return self:IsSome() and self._v == value end --[=[ @return string Metamethod to transform the option into a string. ```lua local optA = Option.Some(64) local optB = Option.None print(optA) --> Option print(optB) --> Option ``` ]=] function Option:__tostring() if self:IsSome() then return ("Option<" .. typeof(self._v) .. ">") else return "Option" end end --[=[ @return boolean @param opt Option Metamethod to check equality between two options. Returns `true` if both options hold the same value _or_ both options are None. ```lua local o1 = Option.Some(32) local o2 = Option.Some(32) local o3 = Option.Some(64) local o4 = Option.None local o5 = Option.None print(o1 == o2) --> true print(o1 == o3) --> false print(o1 == o4) --> false print(o4 == o5) --> true ``` ]=] function Option:__eq(opt) if Option.Is(opt) then if self:IsSome() and opt:IsSome() then return (self:Unwrap() == opt:Unwrap()) elseif self:IsNone() and opt:IsNone() then return true end end return false end --[=[ @prop None Option @within Option Represents no value. ]=] Option.None = Option._new() return (Option :: any) :: { Some: (value: T) -> Option, Wrap: (value: T) -> Option, Is: (obj: any) -> boolean, None: Option, } ]]> init.spec ") end) it("should return string of some option with type", function() local values = { 10, true, false, "test", {}, function() end, coroutine.create(function() end), workspace } for _, value in ipairs(values) do local expectedString = ("Option<%s>"):format(typeof(value)) expect(tostring(Option.Some(value))).to.equal(expectedString) end end) end) end ]]> wally return { package = { authors = {"Stephen Leitnick"}, description = "Represent optional values in Lua", license = "MIT", name = "sleitnick/option", realm = "shared", registry = "https://github.com/UpliftGames/wally-index", version = "1.0.5", }, } sleitnick_signal@2.0.3 signal (), Destroy: (self: Connection) -> (), Connected: boolean, } export type Signal = { Fire: (self: Signal, T...) -> (), FireDeferred: (self: Signal, T...) -> (), Connect: (self: Signal, fn: (T...) -> ()) -> Connection, Once: (self: Signal, fn: (T...) -> ()) -> Connection, DisconnectAll: (self: Signal) -> (), GetConnections: (self: Signal) -> { Connection }, Destroy: (self: Signal) -> (), Wait: (self: Signal) -> T..., } -- The currently idle thread to run the next handler on local freeRunnerThread = nil -- Function which acquires the currently idle handler runner thread, runs the -- function fn on it, and then releases the thread, returning it to being the -- currently idle one. -- If there was a currently idle runner thread already, that's okay, that old -- one will just get thrown and eventually GCed. local function acquireRunnerThreadAndCallEventHandler(fn, ...) local acquiredRunnerThread = freeRunnerThread freeRunnerThread = nil fn(...) -- The handler finished running, this runner thread is free again. freeRunnerThread = acquiredRunnerThread end -- Coroutine runner that we create coroutines of. The coroutine can be -- repeatedly resumed with functions to run followed by the argument to run -- them with. local function runEventHandlerInFreeThread(...) acquireRunnerThreadAndCallEventHandler(...) while true do acquireRunnerThreadAndCallEventHandler(coroutine.yield()) end end --[=[ @within Signal @interface SignalConnection .Connected boolean .Disconnect (SignalConnection) -> () Represents a connection to a signal. ```lua local connection = signal:Connect(function() end) print(connection.Connected) --> true connection:Disconnect() print(connection.Connected) --> false ``` ]=] -- Connection class local Connection = {} Connection.__index = Connection function Connection:Disconnect() if not self.Connected then return end self.Connected = false -- Unhook the node, but DON'T clear it. That way any fire calls that are -- currently sitting on this node will be able to iterate forwards off of -- it, but any subsequent fire calls will not hit it, and it will be GCed -- when no more fire calls are sitting on it. if self._signal._handlerListHead == self then self._signal._handlerListHead = self._next else local prev = self._signal._handlerListHead while prev and prev._next ~= self do prev = prev._next end if prev then prev._next = self._next end end end Connection.Destroy = Connection.Disconnect -- Make Connection strict setmetatable(Connection, { __index = function(_tb, key) error(("Attempt to get Connection::%s (not a valid member)"):format(tostring(key)), 2) end, __newindex = function(_tb, key, _value) error(("Attempt to set Connection::%s (not a valid member)"):format(tostring(key)), 2) end, }) --[=[ @within Signal @type ConnectionFn (...any) -> () A function connected to a signal. ]=] --[=[ @class Signal A Signal is a data structure that allows events to be dispatched and observed. This implementation is a direct copy of the de facto standard, [GoodSignal](https://devforum.roblox.com/t/lua-signal-class-comparison-optimal-goodsignal-class/1387063), with some added methods and typings. For example: ```lua local signal = Signal.new() -- Subscribe to a signal: signal:Connect(function(msg) print("Got message:", msg) end) -- Dispatch an event: signal:Fire("Hello world!") ``` ]=] local Signal = {} Signal.__index = Signal --[=[ Constructs a new Signal @return Signal ]=] function Signal.new(): Signal local self = setmetatable({ _handlerListHead = false, _proxyHandler = nil, _yieldedThreads = nil, }, Signal) return self end --[=[ Constructs a new Signal that wraps around an RBXScriptSignal. @param rbxScriptSignal RBXScriptSignal -- Existing RBXScriptSignal to wrap @return Signal For example: ```lua local signal = Signal.Wrap(workspace.ChildAdded) signal:Connect(function(part) print(part.Name .. " added") end) Instance.new("Part").Parent = workspace ``` ]=] function Signal.Wrap(rbxScriptSignal: RBXScriptSignal): Signal assert( typeof(rbxScriptSignal) == "RBXScriptSignal", "Argument #1 to Signal.Wrap must be a RBXScriptSignal; got " .. typeof(rbxScriptSignal) ) local signal = Signal.new() signal._proxyHandler = rbxScriptSignal:Connect(function(...) signal:Fire(...) end) return signal end --[=[ Checks if the given object is a Signal. @param obj any -- Object to check @return boolean -- `true` if the object is a Signal. ]=] function Signal.Is(obj: any): boolean return type(obj) == "table" and getmetatable(obj) == Signal end --[=[ @param fn ConnectionFn @return SignalConnection Connects a function to the signal, which will be called anytime the signal is fired. ```lua signal:Connect(function(msg, num) print(msg, num) end) signal:Fire("Hello", 25) ``` ]=] function Signal:Connect(fn) local connection = setmetatable({ Connected = true, _signal = self, _fn = fn, _next = false, }, Connection) if self._handlerListHead then connection._next = self._handlerListHead self._handlerListHead = connection else self._handlerListHead = connection end return connection end --[=[ @deprecated v1.3.0 -- Use `Signal:Once` instead. @param fn ConnectionFn @return SignalConnection ]=] function Signal:ConnectOnce(fn) return self:Once(fn) end --[=[ @param fn ConnectionFn @return SignalConnection Connects a function to the signal, which will be called the next time the signal fires. Once the connection is triggered, it will disconnect itself. ```lua signal:Once(function(msg, num) print(msg, num) end) signal:Fire("Hello", 25) signal:Fire("This message will not go through", 10) ``` ]=] function Signal:Once(fn) local connection local done = false connection = self:Connect(function(...) if done then return end done = true connection:Disconnect() fn(...) end) return connection end function Signal:GetConnections() local items = {} local item = self._handlerListHead while item do table.insert(items, item) item = item._next end return items end -- Disconnect all handlers. Since we use a linked list it suffices to clear the -- reference to the head handler. --[=[ Disconnects all connections from the signal. ```lua signal:DisconnectAll() ``` ]=] function Signal:DisconnectAll() local item = self._handlerListHead while item do item.Connected = false item = item._next end self._handlerListHead = false local yieldedThreads = rawget(self, "_yieldedThreads") if yieldedThreads then for thread in yieldedThreads do if coroutine.status(thread) == "suspended" then warn(debug.traceback(thread, "signal disconnected; yielded thread cancelled", 2)) task.cancel(thread) end end table.clear(self._yieldedThreads) end end -- Signal:Fire(...) implemented by running the handler functions on the -- coRunnerThread, and any time the resulting thread yielded without returning -- to us, that means that it yielded to the Roblox scheduler and has been taken -- over by Roblox scheduling, meaning we have to make a new coroutine runner. --[=[ @param ... any Fire the signal, which will call all of the connected functions with the given arguments. ```lua signal:Fire("Hello") -- Any number of arguments can be fired: signal:Fire("Hello", 32, {Test = "Test"}, true) ``` ]=] function Signal:Fire(...) local item = self._handlerListHead while item do if item.Connected then if not freeRunnerThread then freeRunnerThread = coroutine.create(runEventHandlerInFreeThread) end task.spawn(freeRunnerThread, item._fn, ...) end item = item._next end end --[=[ @param ... any Same as `Fire`, but uses `task.defer` internally & doesn't take advantage of thread reuse. ```lua signal:FireDeferred("Hello") ``` ]=] function Signal:FireDeferred(...) local item = self._handlerListHead while item do local conn = item task.defer(function(...) if conn.Connected then conn._fn(...) end end, ...) item = item._next end end --[=[ @return ... any @yields Yields the current thread until the signal is fired, and returns the arguments fired from the signal. Yielding the current thread is not always desirable. If the desire is to only capture the next event fired, using `Once` might be a better solution. ```lua task.spawn(function() local msg, num = signal:Wait() print(msg, num) --> "Hello", 32 end) signal:Fire("Hello", 32) ``` ]=] function Signal:Wait() local yieldedThreads = rawget(self, "_yieldedThreads") if not yieldedThreads then yieldedThreads = {} rawset(self, "_yieldedThreads", yieldedThreads) end local thread = coroutine.running() yieldedThreads[thread] = true self:Once(function(...) yieldedThreads[thread] = nil if coroutine.status(thread) == "suspended" then task.spawn(thread, ...) end end) return coroutine.yield() end --[=[ Cleans up the signal. Technically, this is only necessary if the signal is created using `Signal.Wrap`. Connections should be properly GC'd once the signal is no longer referenced anywhere. However, it is still good practice to include ways to strictly clean up resources. Calling `Destroy` on a signal will also disconnect all connections immediately. ```lua signal:Destroy() ``` ]=] function Signal:Destroy() self:DisconnectAll() local proxyHandler = rawget(self, "_proxyHandler") if proxyHandler then proxyHandler:Disconnect() end end -- Make signal strict setmetatable(Signal, { __index = function(_tb, key) error(("Attempt to get Signal::%s (not a valid member)"):format(tostring(key)), 2) end, __newindex = function(_tb, key, _value) error(("Attempt to set Signal::%s (not a valid member)"):format(tostring(key)), 2) end, }) return table.freeze({ new = Signal.new, Wrap = Signal.Wrap, Is = Signal.Is, }) ]]> init.test boolean, timeout: number?) local start = os.clock() timeout = (timeout or 10) while true do if predicate() then return true end if (os.clock() - start) > timeout then return false end task.wait() end end return function(ctx: Test.TestContext) local Signal = require(script.Parent) local signal local function NumConns(sig) sig = sig or signal return #sig:GetConnections() end ctx:BeforeEach(function() signal = Signal.new() end) ctx:AfterEach(function() signal:Destroy() end) ctx:Describe("Constructor", function() ctx:Test("should create a new signal and fire it", function() ctx:Expect(Signal.Is(signal)):ToBe(true) task.defer(function() signal:Fire(10, 20) end) local n1, n2 = signal:Wait() ctx:Expect(n1):ToBe(10) ctx:Expect(n2):ToBe(20) end) ctx:Test("should create a proxy signal and connect to it", function() local signalWrap = Signal.Wrap(game:GetService("RunService").Heartbeat) ctx:Expect(Signal.Is(signalWrap)):ToBe(true) local fired = false signalWrap:Connect(function() fired = true end) ctx:Expect(AwaitCondition(function() return fired end, 2)):ToBe(true) signalWrap:Destroy() end) end) ctx:Describe("FireDeferred", function() ctx:Test("should be able to fire primitive argument", function() local send = 10 local value signal:Connect(function(v) value = v end) signal:FireDeferred(send) ctx:Expect(AwaitCondition(function() return (send == value) end, 1)):ToBe(true) end) ctx:Test("should be able to fire a reference based argument", function() local send = { 10, 20 } local value signal:Connect(function(v) value = v end) signal:FireDeferred(send) ctx:Expect(AwaitCondition(function() return (send == value) end, 1)):ToBe(true) end) end) ctx:Describe("Fire", function() ctx:Test("should be able to fire primitive argument", function() local send = 10 local value signal:Connect(function(v) value = v end) signal:Fire(send) ctx:Expect(value):ToBe(send) end) ctx:Test("should be able to fire a reference based argument", function() local send = { 10, 20 } local value signal:Connect(function(v) value = v end) signal:Fire(send) ctx:Expect(value):ToBe(send) end) end) ctx:Describe("ConnectOnce", function() ctx:Test("should only capture first fire", function() local value local c = signal:ConnectOnce(function(v) value = v end) ctx:Expect(c.Connected):ToBe(true) signal:Fire(10) ctx:Expect(c.Connected):ToBe(false) signal:Fire(20) ctx:Expect(value):ToBe(10) end) end) ctx:Describe("Wait", function() ctx:Test("should be able to wait for a signal to fire", function() task.defer(function() signal:Fire(10, 20, 30) end) local n1, n2, n3 = signal:Wait() ctx:Expect(n1):ToBe(10) ctx:Expect(n2):ToBe(20) ctx:Expect(n3):ToBe(30) end) end) ctx:Describe("DisconnectAll", function() ctx:Test("should disconnect all connections", function() signal:Connect(function() end) signal:Connect(function() end) ctx:Expect(NumConns()):ToBe(2) signal:DisconnectAll() ctx:Expect(NumConns()):ToBe(0) end) end) ctx:Describe("Disconnect", function() ctx:Test("should disconnect connection", function() local con = signal:Connect(function() end) ctx:Expect(NumConns()):ToBe(1) con:Disconnect() ctx:Expect(NumConns()):ToBe(0) end) ctx:Test("should still work if connections disconnected while firing", function() local a = 0 local c signal:Connect(function() a += 1 end) c = signal:Connect(function() c:Disconnect() a += 1 end) signal:Connect(function() a += 1 end) signal:Fire() ctx:Expect(a):ToBe(3) end) ctx:Test("should still work if connections disconnected while firing deferred", function() local a = 0 local c signal:Connect(function() a += 1 end) c = signal:Connect(function() c:Disconnect() a += 1 end) signal:Connect(function() a += 1 end) signal:FireDeferred() ctx:Expect(AwaitCondition(function() return a == 3 end)):ToBe(true) end) end) end ]]> wally return { package = { authors = {"Stephen Leitnick"}, description = "Signal class", exclude = {"node_modules", "package.json", "**/*.ts"}, license = "MIT", name = "sleitnick/signal", realm = "shared", registry = "https://github.com/UpliftGames/wally-index", version = "2.0.3", }, } sleitnick_table-util@1.2.1 table-util (t: T, deep: boolean?): T if not deep then return (table.clone(t :: any) :: any) :: T end local function DeepCopy(tbl: { any }) local tCopy = table.clone(tbl) for k, v in tCopy do if type(v) == "table" then tCopy[k] = DeepCopy(v) end end return tCopy end return DeepCopy(t :: any) :: T end --[=[ @within TableUtil @function Sync @param srcTbl table -- Source table @param templateTbl table -- Template table @return table Synchronizes the `srcTbl` based on the `templateTbl`. This will make sure that `srcTbl` has all of the same keys as `templateTbl`, including removing keys in `srcTbl` that are not present in `templateTbl`. This is a _deep_ operation, so any nested tables will be synchronized as well. ```lua local template = {kills = 0, deaths = 0, xp = 0} local data = {kills = 10, experience = 12} data = TableUtil.Sync(data, template) print(data) --> {kills = 10, deaths = 0, xp = 0} ``` :::caution Data Loss Warning This is a two-way sync, so the source table will have data _removed_ that isn't found in the template table. This can be problematic if used for player data, where there might be dynamic data added that isn't in the template. For player data, use `TableUtil.Reconcile` instead. ]=] local function Sync(srcTbl: S, templateTbl: T): T assert(type(srcTbl) == "table", "First argument must be a table") assert(type(templateTbl) == "table", "Second argument must be a table") local tbl = table.clone(srcTbl) -- If 'tbl' has something 'templateTbl' doesn't, then remove it from 'tbl' -- If 'tbl' has something of a different type than 'templateTbl', copy from 'templateTbl' -- If 'templateTbl' has something 'tbl' doesn't, then add it to 'tbl' for k, v in pairs(tbl) do local vTemplate = templateTbl[k] -- Remove keys not within template: if vTemplate == nil then tbl[k] = nil -- Synchronize data types: elseif type(v) ~= type(vTemplate) then if type(vTemplate) == "table" then tbl[k] = Copy(vTemplate, true) else tbl[k] = vTemplate end -- Synchronize sub-tables: elseif type(v) == "table" then tbl[k] = Sync(v, vTemplate) end end -- Add any missing keys: for k, vTemplate in pairs(templateTbl) do local v = tbl[k] if v == nil then if type(vTemplate) == "table" then tbl[k] = Copy(vTemplate, true) else tbl[k] = vTemplate end end end return (tbl :: any) :: T end --[=[ @within TableUtil @function Reconcile @param source table @param template table @return table Performs a one-way sync on the `source` table against the `template` table. Any keys found in `template` that are not found in `source` will be added to `source`. This is useful for syncing player data against data template tables to ensure players have all the necessary keys, while maintaining existing keys that may no longer be in the template. This is a deep operation, so nested tables will also be properly reconciled. ```lua local template = {kills = 0, deaths = 0, xp = 0} local data = {kills = 10, abc = 20} local correctedData = TableUtil.Reconcile(data, template) print(correctedData) --> {kills = 10, deaths = 0, xp = 0, abc = 20} ``` ]=] local function Reconcile(src: S, template: T): S & T assert(type(src) == "table", "First argument must be a table") assert(type(template) == "table", "Second argument must be a table") local tbl = table.clone(src) for k, v in template do local sv = src[k] if sv == nil then if type(v) == "table" then tbl[k] = Copy(v, true) else tbl[k] = v end elseif type(sv) == "table" then if type(v) == "table" then tbl[k] = Reconcile(sv, v) else tbl[k] = Copy(sv, true) end end end return (tbl :: any) :: S & T end --[=[ @within TableUtil @function SwapRemove @param tbl table -- Array @param i number -- Index Removes index `i` in the table by swapping the value at `i` with the last value in the array, and then trimming off the last value from the array. This allows removal of the value at `i` in `O(1)` time, but does not preserve array ordering. If a value needs to be removed from an array, but ordering of the array does not matter, using `SwapRemove` is always preferred over `table.remove`. In the following example, we remove "B" at index 2. SwapRemove does this by moving the last value "E" over top of "B", and then trimming off "E" at the end of the array: ```lua local t = {"A", "B", "C", "D", "E"} TableUtil.SwapRemove(t, 2) -- Remove "B" print(t) --> {"A", "E", "C", "D"} ``` :::note Arrays only This function works on arrays, but not dictionaries. ]=] local function SwapRemove(t: { T }, i: number) local n = #t t[i] = t[n] t[n] = nil end --[=[ @within TableUtil @function SwapRemoveFirstValue @param tbl table -- Array @param v any -- Value to find @return number? Performs `table.find(tbl, v)` to find the index of the given value, and then performs `TableUtil.SwapRemove` on that index. ```lua local t = {"A", "B", "C", "D", "E"} TableUtil.SwapRemoveFirstValue(t, "C") print(t) --> {"A", "B", "E", "D"} ``` :::note Arrays only This function works on arrays, but not dictionaries. ]=] local function SwapRemoveFirstValue(t: { T }, v: T): number? local index: number? = table.find(t, v) if index then SwapRemove(t, index) end return index end --[=[ @within TableUtil @function Map @param tbl table @param predicate (value: any, key: any, tbl: table) -> newValue: any @return table Performs a map operation against the given table, which can be used to map new values based on the old values at given keys/indices. For example: ```lua local t = {A = 10, B = 20, C = 30} local t2 = TableUtil.Map(t, function(value) return value * 2 end) print(t2) --> {A = 20, B = 40, C = 60} ``` ]=] local function Map(t: { T }, f: (T, number, { T }) -> M): { M } assert(type(t) == "table", "First argument must be a table") assert(type(f) == "function", "Second argument must be a function") local newT = table.create(#t) for k, v in t do newT[k] = f(v, k, t) end return newT end --[=[ @within TableUtil @function Filter @param tbl table @param predicate (value: any, key: any, tbl: table) -> keep: boolean @return table Performs a filter operation against the given table, which can be used to filter out unwanted values from the table. For example: ```lua local t = {A = 10, B = 20, C = 30} local t2 = TableUtil.Filter(t, function(value, key) return value > 15 end) print(t2) --> {B = 40, C = 60} ``` ]=] local function Filter(t: { T }, predicate: (T, any, { T }) -> boolean): { T } assert(type(t) == "table", "First argument must be a table") assert(type(predicate) == "function", "Second argument must be a function") local newT = table.create(#t) if #t > 0 then local n = 0 for i, v in t do if predicate(v, i, t) then n += 1 newT[n] = v end end else for k, v in t do if predicate(v, k, t) then newT[k] = v end end end return newT end --[=[ @within TableUtil @function Reduce @param tbl table @param predicate (accumulator: any, value: any, index: any, tbl: table) -> result: any @return table Performs a reduce operation against the given table, which can be used to reduce the table into a single value. This could be used to sum up a table or transform all the values into a compound value of any kind. For example: ```lua local t = {10, 20, 30, 40} local result = TableUtil.Reduce(t, function(accum, value) return accum + value end) print(result) --> 100 ``` ]=] local function Reduce(t: { T }, predicate: (R, T, any, { T }) -> R, init: R): R assert(type(t) == "table", "First argument must be a table") assert(type(predicate) == "function", "Second argument must be a function") local result = init :: R if #t > 0 then local start = 1 if init == nil then result = (t[1] :: any) :: R start = 2 end for i = start, #t do result = predicate(result, t[i], i, t) end else local start = nil if init == nil then result = (next(t) :: any) :: R start = result end for k, v in next, t, start :: any? do result = predicate(result, v, k, t) end end return result end --[=[ @within TableUtil @function Assign @param target table @param ... table @return table Copies all values of the given tables into the `target` table. ```lua local t = {A = 10} local t2 = {B = 20} local t3 = {C = 30, D = 40} local newT = TableUtil.Assign(t, t2, t3) print(newT) --> {A = 10, B = 20, C = 30, D = 40} ``` ]=] local function Assign(target: { T }, ...: { any }): { T } & { any } local tbl = table.clone(target) for _, src in { ... } do for k, v in src do tbl[k] = v end end return tbl end --[=[ @within TableUtil @function Extend @param target table @param extension table @return table Extends the target array with the extension array. ```lua local t = {10, 20, 30} local t2 = {30, 40, 50} local tNew = TableUtil.Extend(t, t2) print(tNew) --> {10, 20, 30, 30, 40, 50} ``` :::note Arrays only This function works on arrays, but not dictionaries. ]=] local function Extend(target: { T }, extension: { E }): { T } & { E } local tbl = table.clone(target) :: { any } for _, v in extension do table.insert(tbl, v) end return tbl end --[=[ @within TableUtil @function Reverse @param tbl table @return table Reverses the array. ```lua local t = {1, 5, 10} local tReverse = TableUtil.Reverse(t) print(tReverse) --> {10, 5, 1} ``` :::note Arrays only This function works on arrays, but not dictionaries. ]=] local function Reverse(tbl: { T }): { T } local n = #tbl local tblRev = table.create(n) for i = 1, n do tblRev[i] = tbl[n - i + 1] end return tblRev end --[=[ @within TableUtil @function Shuffle @param tbl table @param rngOverride Random? @return table Shuffles the table. ```lua local t = {1, 2, 3, 4, 5, 6, 7, 8, 9} local shuffled = TableUtil.Shuffle(t) print(shuffled) --> e.g. {9, 4, 6, 7, 3, 1, 5, 8, 2} ``` :::note Arrays only This function works on arrays, but not dictionaries. ]=] local function Shuffle(tbl: { T }, rngOverride: Random?): { T } assert(type(tbl) == "table", "First argument must be a table") local shuffled = table.clone(tbl) local random = if typeof(rngOverride) == "Random" then rngOverride else rng for i = #tbl, 2, -1 do local j = random:NextInteger(1, i) shuffled[i], shuffled[j] = shuffled[j], shuffled[i] end return shuffled end --[=[ @within TableUtil @function Sample @param tbl table @param sampleSize number @param rngOverride Random? @return table Returns a random sample of the table. ```lua local t = {1, 2, 3, 4, 5, 6, 7, 8, 9} local sample = TableUtil.Sample(t, 3) print(sample) --> e.g. {6, 2, 5} ``` :::note Arrays only This function works on arrays, but not dictionaries. ]=] local function Sample(tbl: { T }, size: number, rngOverride: Random?): { T } assert(type(tbl) == "table", "First argument must be a table") assert(type(size) == "number", "Second argument must be a number") -- If given table is empty, just return a new empty table: local len = #tbl if len == 0 then return {} end local shuffled = table.clone(tbl) local sample = table.create(size) local random = if typeof(rngOverride) == "Random" then rngOverride else rng -- Clamp sample size to be no larger than the given table size: size = math.clamp(size, 1, len) for i = 1, size do local j = random:NextInteger(i, len) shuffled[i], shuffled[j] = shuffled[j], shuffled[i] end table.move(shuffled, 1, size, 1, sample) return sample end --[=[ @within TableUtil @function Flat @param tbl table @param depth number? @return table Returns a new table where all sub-arrays have been bubbled up to the top. The depth at which the scan is performed is dictated by the `depth` parameter, which is set to `1` by default. ```lua local t = {{10, 20}, {90, 100}, {30, 15}} local flat = TableUtil.Flat(t) print(flat) --> {10, 20, 90, 100, 30, 15} ``` :::note Arrays only This function works on arrays, but not dictionaries. ]=] local function Flat(tbl: { T }, depth: number?): { T } local maxDepth: number = if type(depth) == "number" then depth else 1 local flatTbl = table.create(#tbl) local function Scan(t: { any }, d: number) for _, v in t do if type(v) == "table" and d < maxDepth then Scan(v, d + 1) else table.insert(flatTbl, v) end end end Scan(tbl, 0) return flatTbl end --[=[ @within TableUtil @function FlatMap @param tbl table @param predicate (key: any, value: any, tbl: table) -> newValue: any @return table Calls `TableUtil.Map` on the given table and predicate, and then calls `TableUtil.Flat` on the result from the map operation. ```lua local t = {10, 20, 30} local result = TableUtil.FlatMap(t, function(value) return {value, value * 2} end) print(result) --> {10, 20, 20, 40, 30, 60} ``` :::note Arrays only This function works on arrays, but not dictionaries. ]=] local function FlatMap(tbl: { T }, callback: (T, number, { T }) -> M): { M } return Flat(Map(tbl, callback)) end --[=[ @within TableUtil @function Keys @param tbl table @return table Returns an array with all the keys in the table. ```lua local t = {A = 10, B = 20, C = 30} local keys = TableUtil.Keys(t) print(keys) --> {"A", "B", "C"} ``` :::caution Ordering The ordering of the keys is never guaranteed. If order is imperative, call `table.sort` on the resulting `keys` array. ```lua local keys = TableUtil.Keys(t) table.sort(keys) ``` ]=] local function Keys(tbl: { [K]: V }): { K } local keys = table.create(#tbl) for k in tbl do table.insert(keys, k) end return keys end --[=[ @within TableUtil @function Values @param tbl table @return table Returns an array with all the values in the table. ```lua local t = {A = 10, B = 20, C = 30} local values = TableUtil.Values(t) print(values) --> {10, 20, 30} ``` :::caution Ordering The ordering of the values is never guaranteed. If order is imperative, call `table.sort` on the resulting `values` array. ```lua local values = TableUtil.Values(t) table.sort(values) ``` ]=] local function Values(tbl: { [K]: V }): { V } local values = table.create(#tbl) for _, v in tbl do table.insert(values, v) end return values end --[=[ @within TableUtil @function Find @param tbl table @param callback (value: any, index: any, tbl: table) -> boolean @return (value: any?, key: any?) Performs a linear scan across the table and calls `callback` on each item in the array. Returns the value and key of the first pair in which the callback returns `true`. ```lua local t = { {Name = "Bob", Age = 20}; {Name = "Jill", Age = 30}; {Name = "Ann", Age = 25}; } -- Find first person who has a name starting with J: local firstPersonWithJ = TableUtil.Find(t, function(person) return person.Name:sub(1, 1):lower() == "j" end) print(firstPersonWithJ) --> {Name = "Jill", Age = 30} ``` :::caution Dictionary Ordering While `Find` can also be used with dictionaries, dictionary ordering is never guaranteed, and thus the result could be different if there are more than one possible matches given the data and callback function. ]=] local function Find(tbl: { [K]: V }, callback: (V, K, { [K]: V }) -> boolean): (V?, K?) for k, v in tbl do if callback(v, k, tbl) then return v, k end end return nil, nil end --[=[ @within TableUtil @function Every @param tbl table @param callback (value: any, index: any, tbl: table) -> boolean @return boolean Returns `true` if the `callback` also returns `true` for _every_ item in the table. ```lua local t = {10, 20, 40, 50, 60} local allAboveZero = TableUtil.Every(t, function(value) return value > 0 end) print("All above zero:", allAboveZero) --> All above zero: true ``` ]=] local function Every(tbl: { [K]: V }, callback: (V, K, { [K]: V }) -> boolean): boolean for k, v in tbl do if not callback(v, k, tbl) then return false end end return true end --[=[ @within TableUtil @function Some @param tbl table @param callback (value: any, index: any, tbl: table) -> boolean @return boolean Returns `true` if the `callback` also returns `true` for _at least one_ of the items in the table. ```lua local t = {10, 20, 40, 50, 60} local someBelowTwenty = TableUtil.Some(t, function(value) return value < 20 end) print("Some below twenty:", someBelowTwenty) --> Some below twenty: true ``` ]=] local function Some(tbl: { [K]: V }, callback: (V, K, { [K]: V }) -> boolean): boolean for k, v in tbl do if callback(v, k, tbl) then return true end end return false end --[=[ @within TableUtil @function Truncate @param tbl table @param length number @return table Returns a new table truncated to the length of `length`. Any length equal or greater than the current length will simply return a shallow copy of the table. ```lua local t = {10, 20, 30, 40, 50, 60, 70, 80} local tTruncated = TableUtil.Truncate(t, 3) print(tTruncated) --> {10, 20, 30} ``` ]=] local function Truncate(tbl: { T }, len: number): { T } local n = #tbl len = math.clamp(len, 1, n) return if len == n then table.clone(tbl) else table.move(tbl, 1, len, 1, table.create(len)) end --[=[ @within TableUtil @function Zip @param ... table @return (iter: (t: table, k: any) -> (key: any?, values: table?), tbl: table, startIndex: any?) Returns an iterator that can scan through multiple tables at the same time side-by-side, matching against shared keys/indices. ```lua local t1 = {10, 20, 30, 40, 50} local t2 = {60, 70, 80, 90, 100} for key,values in TableUtil.Zip(t1, t2) do print(key, values) end --[[ Outputs: 1 {10, 60} 2 {20, 70} 3 {30, 80} 4 {40, 90} 5 {50, 100} --]] ``` ]=] local function Zip(...: { [any]: any }): ((t: { any }, k: any) -> (any, any), { any }, any) assert(select("#", ...) > 0, "Must supply at least 1 table") local function ZipIteratorArray(all: { any }, k: number): (number?, { any }?) k += 1 local values = {} for i, t in all do local v = t[k] if v ~= nil then values[i] = v else return nil, nil end end return k, values end local function ZipIteratorMap(all: { [any]: any }, k: any): (number?, { any }?) local values = {} for i, t in all do local v = next(t, k) if v ~= nil then values[i] = v else return nil, nil end end return k, values end local all = { ... } if #all[1] > 0 then return ZipIteratorArray, all, 0 else return ZipIteratorMap, all, nil end end --[=[ @within TableUtil @function Lock @param tbl table @return table Locks the table using `table.freeze`, as well as any nested tables within the given table. This will lock the whole deep structure of the table, disallowing any further modifications. ```lua local tbl = {xyz = {abc = 32}} tbl.xyz.abc = 28 -- Works fine TableUtil.Lock(tbl) tbl.xyz.abc = 64 -- Will throw an error (cannot modify readonly table) ``` ]=] local function Lock(tbl: T): T local function Freeze(t: { [any]: any }) for k, v in pairs(t) do if type(v) == "table" then t[k] = Freeze(v) end end return table.freeze(t) end return Freeze(tbl :: any) end --[=[ @within TableUtil @function IsEmpty @param tbl table @return boolean Returns `true` if the given table is empty. This is simply performed by checking if `next(tbl)` is `nil` and works for both arrays and dictionaries. This is useful when needing to check if a table is empty but not knowing if it is an array or dictionary. ```lua TableUtil.IsEmpty({}) -- true TableUtil.IsEmpty({"abc"}) -- false TableUtil.IsEmpty({abc = 32}) -- false ``` ]=] local function IsEmpty(tbl: { any }): boolean return next(tbl) == nil end --[=[ @within TableUtil @function EncodeJSON @param value any @return string Proxy for [`HttpService:JSONEncode`](https://developer.roblox.com/en-us/api-reference/function/HttpService/JSONEncode). ]=] local function EncodeJSON(value: any): string return HttpService:JSONEncode(value) end --[=[ @within TableUtil @function DecodeJSON @param value any @return string Proxy for [`HttpService:JSONDecode`](https://developer.roblox.com/en-us/api-reference/function/HttpService/JSONDecode). ]=] local function DecodeJSON(str: string): any return HttpService:JSONDecode(str) end TableUtil.Copy = Copy TableUtil.Sync = Sync TableUtil.Reconcile = Reconcile TableUtil.SwapRemove = SwapRemove TableUtil.SwapRemoveFirstValue = SwapRemoveFirstValue TableUtil.Map = Map TableUtil.Filter = Filter TableUtil.Reduce = Reduce TableUtil.Assign = Assign TableUtil.Extend = Extend TableUtil.Reverse = Reverse TableUtil.Shuffle = Shuffle TableUtil.Sample = Sample TableUtil.Flat = Flat TableUtil.FlatMap = FlatMap TableUtil.Keys = Keys TableUtil.Values = Values TableUtil.Find = Find TableUtil.Every = Every TableUtil.Some = Some TableUtil.Truncate = Truncate TableUtil.Zip = Zip TableUtil.Lock = Lock TableUtil.IsEmpty = IsEmpty TableUtil.EncodeJSON = EncodeJSON TableUtil.DecodeJSON = DecodeJSON return TableUtil ]]> init.spec = 30 and n <= 60) end) expect(#tblFiltered).to.equal(4) expect(tblFiltered[1]).to.equal(30) expect(tblFiltered[#tblFiltered]).to.equal(60) end) end) describe("Reduce", function() it("should reduce table with numbers", function() local tbl = { 1, 2, 3, 4, 5 } local reduced = TableUtil.Reduce(tbl, function(accum, value) return accum + value end) expect(reduced).to.equal(15) end) it("should reduce table", function() local tbl = { { Score = 10 }, { Score = 20 }, { Score = 30 } } local reduced = TableUtil.Reduce(tbl, function(accum, value) return accum + value.Score end, 0) expect(reduced).to.equal(60) end) it("should reduce table with initial value", function() local tbl = { { Score = 10 }, { Score = 20 }, { Score = 30 } } local reduced = TableUtil.Reduce(tbl, function(accum, value) return accum + value.Score end, 40) expect(reduced).to.equal(100) end) it("should reduce functions", function() local function Square(x) return x * x end local function Double(x) return x * 2 end local Func = TableUtil.Reduce({ Square, Double }, function(a, b) return function(x) return a(b(x)) end end) local result = Func(10) expect(result).to.equal(400) end) end) describe("Assign", function() it("should assign tables", function() local target = { a = 32, x = 100 } local t1 = { b = 64, c = 128 } local t2 = { a = 10, c = 100, d = 200 } local tbl = TableUtil.Assign(target, t1, t2) expect(tbl.a).to.equal(10) expect(tbl.b).to.equal(64) expect(tbl.c).to.equal(100) expect(tbl.d).to.equal(200) expect(tbl.x).to.equal(100) end) end) describe("Extend", function() it("should extend tables", function() local tbl = { "a", "b", "c" } local extension = { "d", "e", "f" } local extended = TableUtil.Extend(tbl, extension) expect(table.concat(extended)).to.equal("abcdef") end) end) describe("Reverse", function() it("should create a table in reverse", function() local tbl = { 1, 2, 3 } local tblRev = TableUtil.Reverse(tbl) expect(table.concat(tblRev)).to.equal("321") end) end) describe("Shuffle", function() it("should shuffle a table", function() local tbl = { 1, 2, 3, 4, 5 } expect(function() TableUtil.Shuffle(tbl) end).never.to.throw() end) end) describe("Sample", function() it("should sample a table", function() local tbl = { 1, 2, 3, 4, 5 } local sample = TableUtil.Sample(tbl, 3) expect(#sample).to.equal(3) end) end) describe("Flat", function() it("should flatten table", function() local tbl = { 1, 2, 3, { 4, 5, { 6, 7 } } } local tblFlat = TableUtil.Flat(tbl, 3) expect(table.concat(tblFlat)).to.equal("1234567") end) end) describe("FlatMap", function() it("should map and flatten table", function() local tbl = { 1, 2, 3, 4, 5, 6, 7 } local tblFlat = TableUtil.FlatMap(tbl, function(n) return { n, n * 2 } end) expect(table.concat(tblFlat)).to.equal("12243648510612714") end) end) describe("Keys", function() it("should give all keys of table", function() local tbl = { a = 1, b = 2, c = 3 } local keys = TableUtil.Keys(tbl) expect(#keys).to.equal(3) expect(table.find(keys, "a")).to.be.ok() expect(table.find(keys, "b")).to.be.ok() expect(table.find(keys, "c")).to.be.ok() end) end) describe("Values", function() it("should give all values of table", function() local tbl = { a = 1, b = 2, c = 3 } local values = TableUtil.Values(tbl) expect(#values).to.equal(3) expect(table.find(values, 1)).to.be.ok() expect(table.find(values, 2)).to.be.ok() expect(table.find(values, 3)).to.be.ok() end) end) describe("Find", function() it("should find item in array", function() local tbl = { 10, 20, 30 } local item, index = TableUtil.Find(tbl, function(value) return (value == 20) end) expect(item).to.be.ok() expect(index).to.equal(2) expect(item).to.equal(20) end) it("should find item in dictionary", function() local tbl = { { Score = 10 }, { Score = 20 }, { Score = 30 } } local item, index = TableUtil.Find(tbl, function(value) return (value.Score == 20) end) expect(item).to.be.ok() expect(index).to.equal(2) expect(item.Score).to.equal(20) end) end) describe("Every", function() it("should see every value is above 20", function() local tbl = { 21, 40, 200 } local every = TableUtil.Every(tbl, function(n) return (n > 20) end) expect(every).to.equal(true) end) it("should see every value is not above 20", function() local tbl = { 20, 40, 200 } local every = TableUtil.Every(tbl, function(n) return (n > 20) end) expect(every).never.to.equal(true) end) end) describe("Some", function() it("should see some value is above 20", function() local tbl = { 5, 40, 1 } local every = TableUtil.Some(tbl, function(n) return (n > 20) end) expect(every).to.equal(true) end) it("should see some value is not above 20", function() local tbl = { 5, 15, 1 } local every = TableUtil.Some(tbl, function(n) return (n > 20) end) expect(every).never.to.equal(true) end) end) describe("Truncate", function() it("should truncate an array", function() local t1 = { 1, 2, 3, 4, 5 } local t2 = TableUtil.Truncate(t1, 3) expect(#t2).to.equal(3) expect(t2[1]).to.equal(t1[1]) expect(t2[2]).to.equal(t1[2]) expect(t2[3]).to.equal(t1[3]) end) it("should truncate an array with out of bounds sizes", function() local t1 = { 1, 2, 3, 4, 5 } expect(function() TableUtil.Truncate(t1, -1) end).to.never.throw() expect(function() TableUtil.Truncate(t1, #t1 + 1) end).to.never.throw() local t2 = TableUtil.Truncate(t1, #t1 + 10) expect(#t2).to.equal(#t1) expect(t2).to.never.equal(t1) end) end) describe("Lock", function() it("should lock a table", function() local t = { abc = { xyz = { num = 32 } } } expect(function() t.abc.xyz.num = 64 end).never.to.throw() local t2 = TableUtil.Lock(t) expect(t.abc.xyz.num).to.equal(64) expect(t).to.equal(t2) expect(function() t.abc.xyz.num = 10 end).to.throw() end) end) describe("Zip", function() it("should zip arrays together", function() local t1 = { 1, 2, 3, 4, 5 } local t2 = { 9, 8, 7, 6, 5 } local t3 = { 1, 1, 1, 1, 1 } local lastIndex = 0 for i, v in TableUtil.Zip(t1, t2, t3) do lastIndex = i expect(v[1]).to.equal(t1[i]) expect(v[2]).to.equal(t2[i]) expect(v[3]).to.equal(t3[i]) end expect(lastIndex).to.equal(math.min(#t1, #t2, #t3)) end) it("should zip arrays of different lengths together", function() local t1 = { 1, 2, 3, 4, 5 } local t2 = { 9, 8, 7, 6 } local t3 = { 1, 1, 1 } local lastIndex = 0 for i, v in TableUtil.Zip(t1, t2, t3) do lastIndex = i expect(v[1]).to.equal(t1[i]) expect(v[2]).to.equal(t2[i]) expect(v[3]).to.equal(t3[i]) end expect(lastIndex).to.equal(math.min(#t1, #t2, #t3)) end) it("should zip maps together", function() local t1 = { a = 10, b = 20, c = 30 } local t2 = { a = 100, b = 200, c = 300 } local t3 = { a = 3000, b = 2000, c = 3000 } for k, v in TableUtil.Zip(t1, t2, t3) do expect(v[1]).to.equal(t1[k]) expect(v[2]).to.equal(t2[k]) expect(v[3]).to.equal(t3[k]) end end) it("should zip maps of different keys together", function() local t1 = { a = 10, b = 20, c = 30, d = 40 } local t2 = { a = 100, b = 200, c = 300, z = 10 } local t3 = { a = 3000, b = 2000, c = 3000, x = 0 } for k, v in TableUtil.Zip(t1, t2, t3) do expect(v[1]).to.equal(t1[k]) expect(v[2]).to.equal(t2[k]) expect(v[3]).to.equal(t3[k]) end end) end) describe("IsEmpty", function() it("should detect that table is empty", function() local tbl = {} local isEmpty = TableUtil.IsEmpty(tbl) expect(isEmpty).to.equal(true) end) it("should detect that array is not empty", function() local tbl = { 10, 20, 30 } local isEmpty = TableUtil.IsEmpty(tbl) expect(isEmpty).to.equal(false) end) it("should detect that dictionary is not empty", function() local tbl = { a = 10, b = 20, c = 30 } local isEmpty = TableUtil.IsEmpty(tbl) expect(isEmpty).to.equal(false) end) end) describe("JSON", function() it("should encode json", function() local tbl = { hello = "world" } local json = TableUtil.EncodeJSON(tbl) expect(json).to.equal('{"hello":"world"}') end) it("should decode json", function() local json = '{"hello":"world"}' local tbl = TableUtil.DecodeJSON(json) expect(tbl).to.be.a("table") expect(tbl.hello).to.equal("world") end) end) end ]]> wally return { package = { authors = {"Stephen Leitnick"}, description = "Table utility functions", license = "MIT", name = "sleitnick/table-util", realm = "shared", registry = "https://github.com/UpliftGames/wally-index", version = "1.2.1", }, } Shared Constants Moves Races Sagas = saga.levelRequirement and not completedSet[saga.id] then table.insert(available, saga) end end return available end return Sagas ]]> Settings Stats Transformations Zones = zone.levelRequirement then table.insert(accessible, zone) end end return accessible end return Zones ]]> Network Remotes Server: attack type, target CombatResult = "RemoteEvent", -- Server -> Client: damage, knockback, state BeamStruggleInput = "RemoteEvent", -- Client -> Server: tap events during beam struggle BeamStruggleSync = "RemoteEvent", -- Server -> Client: beam struggle state -- Transformation RequestTransform = "RemoteEvent", -- Client -> Server: requested form ID RequestRevert = "RemoteEvent", -- Client -> Server: revert to base TransformSync = "RemoteEvent", -- Server -> All Clients: player transformed -- Data / Stats StatAllocation = "RemoteEvent", -- Client -> Server: stat point spending RequestPlayerData = "RemoteFunction", -- Client -> Server: get own profile data PlayerDataUpdate = "RemoteEvent", -- Server -> Client: profile data changed -- Character Creation SubmitCharacterCreation = "RemoteFunction", -- Client -> Server: race + appearance -- Quest QuestAccept = "RemoteEvent", -- Client -> Server: accept quest ID QuestAbandon = "RemoteEvent", -- Client -> Server: abandon quest ID QuestUpdate = "RemoteEvent", -- Server -> Client: quest progress update QuestComplete = "RemoteEvent", -- Server -> Client: quest completed -- NPC / Dialogue NPCInteract = "RemoteEvent", -- Client -> Server: interact with NPC DialogueResponse = "RemoteEvent", -- Client -> Server: dialogue choice -- PvP PvpQueueJoin = "RemoteEvent", -- Client -> Server: join queue (mode) PvpQueueLeave = "RemoteEvent", -- Client -> Server: leave queue PvpMatchStart = "RemoteEvent", -- Server -> Client: match starting PvpMatchEnd = "RemoteEvent", -- Server -> Client: match results -- Shop RequestShop = "RemoteFunction", -- Client -> Server: get shop inventory PurchaseItem = "RemoteFunction", -- Client -> Server: buy item -- Move Loadout UpdateLoadout = "RemoteEvent", -- Client -> Server: new loadout config -- Rebirth RequestRebirth = "RemoteFunction", -- Client -> Server: attempt rebirth } -- Folder to hold all remotes local remotesFolder = ReplicatedStorage:FindFirstChild("Remotes") if not remotesFolder then remotesFolder = Instance.new("Folder") remotesFolder.Name = "Remotes" remotesFolder.Parent = ReplicatedStorage end -- Create or find remotes for name, remoteType in pairs(REMOTE_DEFINITIONS) do local existing = remotesFolder:FindFirstChild(name) if not existing then local remote = Instance.new(remoteType) remote.Name = name remote.Parent = remotesFolder end end -- Access helper function Remotes:Get(name: string): RemoteEvent | RemoteFunction local remote = remotesFolder:FindFirstChild(name) if not remote then -- Wait briefly in case of race condition on startup remote = remotesFolder:WaitForChild(name, 5) end assert(remote, "Remote not found: " .. name) return remote end return Remotes ]]> Types GameTypes Utils AnimationUtil CombatUtil = score2 then return 1 else return 2 end end return CombatUtil ]]> MathUtil ServerScriptService Server 0 Modules CharacterBuilder 0 and math.rad(20) or math.rad(-20)) end end -- Head tentacle (Majin) if config.hasHeadTentacle then local tentacle = Instance.new("Part") tentacle.Name = "RaceFeature" tentacle.Size = Vector3.new(0.3, 0.3, 1.5) tentacle.Color = skinColor tentacle.Material = Enum.Material.SmoothPlastic tentacle.CanCollide = false tentacle.Anchored = false tentacle.Parent = character local weld = Instance.new("WeldConstraint") weld.Part0 = head weld.Part1 = tentacle weld.Parent = tentacle tentacle.CFrame = head.CFrame * CFrame.new(0, 0.5, -0.5) * CFrame.Angles(math.rad(-60), 0, 0) end end function CharacterBuilder.ApplyOutfit(character: Model, data: any) -- Remove existing outfit parts for _, child in ipairs(character:GetDescendants()) do if child.Name == "OutfitPart" then child:Destroy() end end local torso = character:FindFirstChild("UpperTorso") or character:FindFirstChild("Torso") if not torso then return end local outfitColor = Color3.fromRGB(100, 100, 200) -- default blue gi if data.Appearance and data.Appearance.OutfitColor then local oc = data.Appearance.OutfitColor outfitColor = Color3.fromRGB(oc.R or 100, oc.G or 100, oc.B or 200) end -- Gi top (slightly larger than torso) local gi = Instance.new("Part") gi.Name = "OutfitPart" gi.Size = torso.Size + Vector3.new(0.1, 0.1, 0.1) gi.Color = outfitColor gi.Material = Enum.Material.Fabric gi.CanCollide = false gi.Anchored = false gi.Transparency = 0 gi.Parent = character local weld = Instance.new("WeldConstraint") weld.Part0 = torso weld.Part1 = gi weld.Parent = gi gi.CFrame = torso.CFrame -- Belt local belt = Instance.new("Part") belt.Name = "OutfitPart" belt.Size = Vector3.new(torso.Size.X + 0.15, 0.3, torso.Size.Z + 0.15) belt.Color = Color3.fromRGB(40, 40, 40) belt.Material = Enum.Material.Fabric belt.CanCollide = false belt.Anchored = false belt.Parent = character local beltWeld = Instance.new("WeldConstraint") beltWeld.Part0 = torso beltWeld.Part1 = belt beltWeld.Parent = belt belt.CFrame = torso.CFrame * CFrame.new(0, -torso.Size.Y / 2 + 0.15, 0) -- Boots (on feet) for _, legName in ipairs({ "LeftFoot", "RightFoot", "Left Leg", "Right Leg" }) do local leg = character:FindFirstChild(legName) if leg then local boot = Instance.new("Part") boot.Name = "OutfitPart" boot.Size = leg.Size + Vector3.new(0.1, 0.1, 0.1) boot.Color = Color3.fromRGB(40, 40, 80) boot.Material = Enum.Material.Fabric boot.CanCollide = false boot.Anchored = false boot.Parent = character local bootWeld = Instance.new("WeldConstraint") bootWeld.Part0 = leg bootWeld.Part1 = boot bootWeld.Parent = boot boot.CFrame = leg.CFrame end end end -- Apply transformation visual changes function CharacterBuilder.ApplyTransformation(player: Player, formId: string, data: any) local character = player.Character if not character then return end -- Re-apply hair with transformation override data.CurrentTransformation = formId CharacterBuilder.ApplyHair(character, data) -- Body color changes for certain forms local form = Transformations:Get(formId) if not form then return end if form.bodyChange then local head = character:FindFirstChild("Head") if form.bodyChange == "Kaioken_Glow" or form.bodyChange == "UI_Glow" or form.bodyChange == "PU_Glow" or form.bodyChange == "MaxPower_Glow" then -- Red/white tint on skin for _, part in ipairs(character:GetDescendants()) do if part:IsA("BasePart") and part.Name ~= "HumanoidRootPart" and part.Name ~= "OutfitPart" then if part.Name == "Head" or part.Name:find("Arm") or part.Name:find("Hand") then -- Don't change skin for glow, add a surface light instead end end end end if form.bodyChange == "Giant_Scale" then -- Scale up the character local humanoid = character:FindFirstChildOfClass("Humanoid") if humanoid then local bodyScale = humanoid:FindFirstChild("BodyHeightScale") if bodyScale then bodyScale.Value = 3 end local bodyWidth = humanoid:FindFirstChild("BodyWidthScale") if bodyWidth then bodyWidth.Value = 2 end local bodyDepth = humanoid:FindFirstChild("BodyDepthScale") if bodyDepth then bodyDepth.Value = 2 end end end if form.bodyChange == "Frieza_Golden" then -- Turn body gold for _, part in ipairs(character:GetDescendants()) do if part:IsA("BasePart") and part.Name ~= "HumanoidRootPart" and part.Name ~= "OutfitPart" and part.Name ~= "Hair" then if part.Name == "Head" or part.Name == "UpperTorso" or part.Name == "LowerTorso" or part.Name:find("Arm") or part.Name:find("Leg") or part.Name:find("Hand") or part.Name:find("Foot") then part.Color = Color3.fromRGB(255, 215, 0) part.Material = Enum.Material.Neon end end end end if form.bodyChange == "Frieza_Black" then for _, part in ipairs(character:GetDescendants()) do if part:IsA("BasePart") and part.Name ~= "HumanoidRootPart" and part.Name ~= "OutfitPart" then if part.Name == "Head" or part.Name == "UpperTorso" or part.Name == "LowerTorso" or part.Name:find("Arm") or part.Name:find("Leg") or part.Name:find("Hand") or part.Name:find("Foot") then part.Color = Color3.fromRGB(30, 30, 30) part.Material = Enum.Material.Metal end end end end if form.bodyChange == "Orange_Body" then for _, part in ipairs(character:GetDescendants()) do if part:IsA("BasePart") and part.Name ~= "HumanoidRootPart" and part.Name ~= "OutfitPart" then if part.Name == "Head" or part.Name == "UpperTorso" or part.Name == "LowerTorso" or part.Name:find("Arm") or part.Name:find("Leg") then part.Color = Color3.fromRGB(255, 165, 50) end end end end end end return CharacterBuilder ]]> DamageResolver EloCalculator HitValidator = move.cooldown end -- Record that a move was used function HitValidator.RecordUse(player: Player, moveId: string) if cooldowns[player] then cooldowns[player][moveId] = tick() end end -- Validate a melee attack function HitValidator.ValidateMelee( attackerCharacter: Model, targetCharacter: Model, moveId: string, attackerState: string ): (boolean, string?) -- State check local validStates = { Idle = true, Attacking = true } if not validStates[attackerState] then return false, "Invalid state for melee: " .. attackerState end -- Range check local attackerPos = attackerCharacter:GetPivot().Position local targetPos = targetCharacter:GetPivot().Position local move = Moves:Get(moveId) local range = if move then move.range else Settings.Combat.BASE_MELEE_RANGE if not CombatUtil.IsInRange(attackerPos, targetPos, range + 2) then -- +2 tolerance return false, "Out of range" end -- Cooldown check if not HitValidator.IsOffCooldown(attackerCharacter:FindFirstChild("Player") and game.Players:GetPlayerFromCharacter(attackerCharacter), moveId) then return false, "Move on cooldown" end return true, nil end -- Validate a ki blast function HitValidator.ValidateKiBlast( player: Player, moveId: string, attackerState: string, currentKi: number ): (boolean, string?) local validStates = { Idle = true } if not validStates[attackerState] then return false, "Invalid state for ki blast: " .. attackerState end local move = Moves:Get(moveId) if not move then return false, "Unknown move" end local kiCost = move.kiCost or move.kiCostBase or 0 if currentKi < kiCost then return false, "Not enough ki" end if not HitValidator.IsOffCooldown(player, moveId) then return false, "Move on cooldown" end return true, nil end -- Validate stamina usage (block, dodge) function HitValidator.ValidateStaminaAction( attackerState: string, actionType: string, currentStamina: number ): (boolean, string?) if actionType == "Vanish" then if currentStamina < Settings.Combat.VANISH_STAMINA_COST then return false, "Not enough stamina" end local validStates = { Idle = true, Blocking = true, Stunned = true } if not validStates[attackerState] then return false, "Cannot vanish from state: " .. attackerState end elseif actionType == "Block" then local validStates = { Idle = true } if not validStates[attackerState] then return false, "Cannot block from state: " .. attackerState end end return true, nil end -- Speed/position sanity check function HitValidator.ValidatePosition( character: Model, lastKnownPosition: Vector3, deltaTime: number, maxSpeed: number ): boolean local currentPos = character:GetPivot().Position local distance = (currentPos - lastKnownPosition).Magnitude local maxDistance = maxSpeed * deltaTime * 1.5 -- 1.5x tolerance return distance <= maxDistance end return HitValidator ]]> LootTable NPCModelBuilder StatCalculator 0 then local rebirthMult = 1 + (rebirths * Stats.REBIRTH_BONUS_PERCENT) for _, statName in ipairs(Stats.Names) do effective[statName] = effective[statName] * rebirthMult end end -- Apply transformation multipliers if currentTransformation ~= "Base" then local form = Transformations:Get(currentTransformation) if form and form.statMultipliers then for statName, mult in pairs(form.statMultipliers) do if effective[statName] then effective[statName] = effective[statName] * mult end end end end -- Floor all values for statName, value in pairs(effective) do effective[statName] = math.floor(value) end return effective end -- Calculate max HP from effective Health stat function StatCalculator.GetMaxHP(effectiveHealth: number): number return effectiveHealth end -- Calculate max Ki (base 100 + KiPower scaling) function StatCalculator.GetMaxKi(effectiveKiPower: number): number return 100 + math.floor(effectiveKiPower * 2) end -- Calculate max Stamina function StatCalculator.GetMaxStamina(effectiveStamina: number): number return effectiveStamina end -- Calculate movement speed multiplier function StatCalculator.GetSpeedMultiplier(effectiveSpeed: number): number return 1.0 + (effectiveSpeed / 200) -- Diminishing scaling end return StatCalculator ]]> Services CharacterService CombatService Client only -- Main game loop: regen + sync + beam struggles RunService.Heartbeat:Connect(function(dt) self:_tickRegeneration(dt) self:_tickKiCharging(dt) self:_tickBeamStruggles(dt) self:_syncCombatStateToClients() self:_syncHumanoidHealth() end) end function CombatService:_initCombatState(player: Player, data: any) HitValidator.InitPlayer(player) local effectiveStats = StatCalculator.Calculate( data.Stats, data.Level, data.Stats, data.CurrentTransformation, data.Race, data.Rebirths ) combatStates[player] = { state = "Idle", hp = StatCalculator.GetMaxHP(effectiveStats.Health), maxHp = StatCalculator.GetMaxHP(effectiveStats.Health), ki = StatCalculator.GetMaxKi(effectiveStats.KiPower), maxKi = StatCalculator.GetMaxKi(effectiveStats.KiPower), stamina = StatCalculator.GetMaxStamina(effectiveStats.Stamina), maxStamina = StatCalculator.GetMaxStamina(effectiveStats.Stamina), effectiveStats = effectiveStats, comboCount = 0, lastCombatTime = 0, lastPosition = Vector3.zero, } end function CombatService:_cleanupPlayer(player: Player) combatStates[player] = nil HitValidator.CleanupPlayer(player) end function CombatService:_tickRegeneration(dt: number) local now = tick() for player, combat in pairs(combatStates) do local outOfCombat = (now - combat.lastCombatTime) > Settings.Combat.COMBAT_TIMEOUT -- Stamina regen: slow in combat (3/sec), fast out of combat (15/sec) if combat.stamina < combat.maxStamina then local regenRate = outOfCombat and 15 or 3 combat.stamina = math.min(combat.maxStamina, combat.stamina + regenRate * dt) end -- HP regen: only out of combat, slow (1% per sec) — and Namekian passive if outOfCombat and combat.hp < combat.maxHp then local hpRegen = 0 local DataService = Knit.GetService("DataService") local data = DataService:GetData(player) if data then local Races = require(ReplicatedStorage.Shared.Constants.Races) local race = Races:Get(data.Race) if race and race.passive.id == "Regeneration" then hpRegen = combat.maxHp * race.passive.regenPercent * dt end end -- Base small HP regen out of combat for everyone hpRegen = hpRegen + combat.maxHp * 0.005 * dt combat.hp = math.min(combat.maxHp, combat.hp + hpRegen) end -- Ki auto-regen for Androids local DataService = Knit.GetService("DataService") local data = DataService:GetData(player) if data and data.Race == "Android" then local Races = require(ReplicatedStorage.Shared.Constants.Races) local race = Races:Get("Android") if race then combat.ki = math.min(combat.maxKi, combat.ki + combat.maxKi * race.passive.kiRegenPercent * dt) end end end end -- Ki charging: when state is "Charging", add ki per tick function CombatService:_tickKiCharging(dt: number) for player, combat in pairs(combatStates) do if combat.state == "Charging" and combat.ki < combat.maxKi then combat.ki = math.min(combat.maxKi, combat.ki + Settings.Combat.KI_CHARGE_RATE * dt) end end end -- Sync combat HP/Ki/Stamina to each player's client every frame function CombatService:_syncCombatStateToClients() for player, combat in pairs(combatStates) do if player and player.Parent then self.Client.CombatResult:Fire(player, { type = "state_sync", hp = combat.hp, maxHp = combat.maxHp, ki = combat.ki, maxKi = combat.maxKi, stamina = combat.stamina, maxStamina = combat.maxStamina, state = combat.state, }) end end end -- Keep Humanoid.Health in sync so the character actually dies/respawns properly function CombatService:_syncHumanoidHealth() for player, combat in pairs(combatStates) do local character = player.Character if not character then continue end local humanoid = character:FindFirstChildOfClass("Humanoid") if not humanoid then continue end -- Scale our HP to Humanoid's 100-based system local hpPercent = if combat.maxHp > 0 then combat.hp / combat.maxHp else 0 humanoid.MaxHealth = combat.maxHp humanoid.Health = combat.hp -- If humanoid dies externally (fell off map, etc.), sync back if humanoid.Health <= 0 and combat.hp > 0 then combat.hp = 0 combat.state = "Dead" end end end function CombatService:_tickBeamStruggles(dt: number) local now = tick() for id, struggle in pairs(beamStruggles) do if (now - struggle.startTime) >= Settings.Combat.BEAM_STRUGGLE_DURATION then self:_resolveBeamStruggle(id) end end end function CombatService:_resolveBeamStruggle(struggleId: string) local struggle = beamStruggles[struggleId] if not struggle then return end local state1 = combatStates[struggle.player1] local state2 = combatStates[struggle.player2] if not state1 or not state2 then beamStruggles[struggleId] = nil return end local winner = CombatUtil.ResolveBeamStruggle( state1.effectiveStats.KiPower, struggle.player1Taps, state2.effectiveStats.KiPower, struggle.player2Taps, Settings.Combat.BEAM_STRUGGLE_TAP_WEIGHT ) local loser = if winner == 1 then struggle.player2 else struggle.player1 local winnerPlayer = if winner == 1 then struggle.player1 else struggle.player2 local winnerState = combatStates[winnerPlayer] local loserState = combatStates[loser] -- Loser takes big damage local damage = math.floor(winnerState.effectiveStats.KiPower * 5) loserState.hp = math.max(0, loserState.hp - damage) loserState.state = "Knocked" -- Reset states winnerState.state = "Idle" -- Broadcast result self.Client.BeamStruggleSync:Fire(struggle.player1, { winner = winner, damage = damage, }) self.Client.BeamStruggleSync:Fire(struggle.player2, { winner = winner, damage = damage, }) beamStruggles[struggleId] = nil -- Check death if loserState.hp <= 0 then self:_handleDeath(loser, winnerPlayer) end end function CombatService:_handleDeath(deadPlayer: Player, killerPlayer: Player?) local state = combatStates[deadPlayer] if state then state.state = "Dead" end -- Respawn after delay task.delay(5, function() if deadPlayer and deadPlayer:IsDescendantOf(Players) then local character = deadPlayer.Character if character then local humanoid = character:FindFirstChildOfClass("Humanoid") if humanoid then humanoid.Health = humanoid.MaxHealth end end if state then state.hp = state.maxHp state.ki = state.maxKi state.stamina = state.maxStamina state.state = "Idle" end end end) -- Award XP/Zeni to killer if killerPlayer then local DataService = Knit.GetService("DataService") local ProgressionService = Knit.GetService("ProgressionService") if ProgressionService then -- Will be connected when ProgressionService exists end end end -- Public API function CombatService:GetCombatState(player: Player) return combatStates[player] end function CombatService:SetState(player: Player, newState: string) local combat = combatStates[player] if combat then combat.state = newState end end function CombatService:RefreshStats(player: Player) local DataService = Knit.GetService("DataService") local data = DataService:GetData(player) if not data then return end local combat = combatStates[player] if not combat then return end local effectiveStats = StatCalculator.Calculate( data.Stats, data.Level, data.Stats, data.CurrentTransformation, data.Race, data.Rebirths ) combat.effectiveStats = effectiveStats combat.maxHp = StatCalculator.GetMaxHP(effectiveStats.Health) combat.maxKi = StatCalculator.GetMaxKi(effectiveStats.KiPower) combat.maxStamina = StatCalculator.GetMaxStamina(effectiveStats.Stamina) end function CombatService:DealDamage(target: Player, damage: number, knockback: Vector3?, hitstun: number?) local state = combatStates[target] if not state then return end state.hp = math.max(0, state.hp - damage) state.lastCombatTime = tick() if hitstun and hitstun > 0 then state.state = "Stunned" task.delay(hitstun, function() if combatStates[target] and combatStates[target].state == "Stunned" then combatStates[target].state = "Idle" end end) end -- Apply knockback to character if knockback and knockback.Magnitude > 0 then local character = target.Character if character then local rootPart = character:FindFirstChild("HumanoidRootPart") if rootPart then local bv = Instance.new("BodyVelocity") bv.Velocity = knockback bv.MaxForce = Vector3.new(1e6, 1e6, 1e6) bv.P = 1e4 bv.Parent = rootPart task.delay(0.2, function() bv:Destroy() end) end end end -- Check death if state.hp <= 0 then self:_handleDeath(target, nil) end end -- Client intent handlers function CombatService.Client:MeleeAttack(player: Player, targetPlayer: Player, moveId: string) local combat = combatStates[player] if not combat then return end local attackerChar = player.Character local targetChar = if targetPlayer then targetPlayer.Character else nil if not attackerChar or not targetChar then return end local valid, err = HitValidator.ValidateMelee(attackerChar, targetChar, moveId, combat.state) if not valid then return end local move = Moves:Get(moveId) if not move or not move.hits then return end HitValidator.RecordUse(player, moveId) combat.state = "Attacking" combat.lastCombatTime = tick() local targetCombat = combatStates[targetPlayer] if not targetCombat then return end targetCombat.lastCombatTime = tick() local isBlocking = targetCombat.state == "Blocking" -- Process each hit in the combo for i, hitData in ipairs(move.hits) do task.delay(hitData.frame / 60, function() if not combatStates[player] or not combatStates[targetPlayer] then return end local result = DamageResolver.ResolveMelee( combat.effectiveStats, targetCombat.effectiveStats, hitData, targetCombat.state == "Blocking" ) -- Apply knockback direction local direction = CombatUtil.GetKnockbackDirection( attackerChar:GetPivot().Position, targetChar:GetPivot().Position ) local worldKnockback = direction * result.knockback.Z + Vector3.new(0, result.knockback.Y, 0) self.Server:DealDamage(targetPlayer, result.damage, worldKnockback, result.hitstun) -- Launcher if result.launcher then targetCombat.state = "Aerial" end -- Guard break if result.guardBreak then targetCombat.state = "Stunned" task.delay(Settings.Combat.GUARD_BREAK_STUN, function() if combatStates[targetPlayer] and combatStates[targetPlayer].state == "Stunned" then combatStates[targetPlayer].state = "Idle" end end) end -- Broadcast to both players self.Server.Client.CombatResult:Fire(player, { type = "melee", hitIndex = i, target = targetPlayer, damage = result.damage, blocked = result.blocked, guardBreak = result.guardBreak, launcher = result.launcher, }) self.Server.Client.CombatResult:Fire(targetPlayer, { type = "melee_received", hitIndex = i, attacker = player, damage = result.damage, blocked = result.blocked, guardBreak = result.guardBreak, launcher = result.launcher, }) end) end -- Return to idle after combo local lastHit = move.hits[#move.hits] task.delay((lastHit.frame / 60) + 0.5, function() if combatStates[player] and combatStates[player].state == "Attacking" then combatStates[player].state = "Idle" end end) end function CombatService.Client:KiBlast(player: Player, direction: Vector3, moveId: string) local combat = combatStates[player] if not combat then return end local valid, err = HitValidator.ValidateKiBlast(player, moveId, combat.state, combat.ki) if not valid then return end local move = Moves:Get(moveId) if not move then return end -- Deduct ki local kiCost = move.kiCost or move.kiCostBase or 0 combat.ki = combat.ki - kiCost combat.lastCombatTime = tick() HitValidator.RecordUse(player, moveId) -- Broadcast ki blast creation to all clients self.Server.Client.CombatResult:FireAll({ type = "ki_blast", attacker = player, moveId = moveId, direction = direction, origin = player.Character and player.Character:GetPivot().Position or Vector3.zero, }) end function CombatService.Client:Block(player: Player, isBlocking: boolean) local combat = combatStates[player] if not combat then return end if isBlocking then if combat.state == "Idle" then combat.state = "Blocking" end else if combat.state == "Blocking" then combat.state = "Idle" end end end function CombatService.Client:Vanish(player: Player) local combat = combatStates[player] if not combat then return end local valid, err = HitValidator.ValidateStaminaAction(combat.state, "Vanish", combat.stamina) if not valid then return end combat.stamina = combat.stamina - Settings.Combat.VANISH_STAMINA_COST combat.state = "Dodging" -- I-frames task.delay(Settings.Combat.VANISH_I_FRAMES, function() if combatStates[player] and combatStates[player].state == "Dodging" then combatStates[player].state = "Idle" end end) -- Broadcast vanish to clients self.Server.Client.CombatResult:FireAll({ type = "vanish", player = player, }) end function CombatService.Client:ChargeKi(player: Player, isCharging: boolean) local combat = combatStates[player] if not combat then return end if isCharging then if combat.state == "Idle" then combat.state = "Charging" end else if combat.state == "Charging" then combat.state = "Idle" end end end function CombatService.Client:BeamStruggleTap(player: Player, struggleId: string) local struggle = beamStruggles[struggleId] if not struggle then return end if struggle.player1 == player then struggle.player1Taps = struggle.player1Taps + 1 elseif struggle.player2 == player then struggle.player2Taps = struggle.player2Taps + 1 end end -- ========================================== -- NPC COMBAT -- ========================================== function CombatService.Client:MeleeAttackNPC(player: Player, npcModel: Model, moveId: string) local combat = combatStates[player] if not combat then return end -- Validate state local validStates = { Idle = true, Attacking = true } if not validStates[combat.state] then return end local attackerChar = player.Character if not attackerChar then return end -- Validate NPC exists and is in workspace if not npcModel or not npcModel.Parent then return end local npcHumanoid = npcModel:FindFirstChildOfClass("Humanoid") if not npcHumanoid or npcHumanoid.Health <= 0 then return end -- Range check local attackerRoot = attackerChar:FindFirstChild("HumanoidRootPart") local npcRoot = npcModel:FindFirstChild("HumanoidRootPart") if not attackerRoot or not npcRoot then return end local move = Moves:Get(moveId) if not move or not move.hits then return end local range = move.range or 8 if (attackerRoot.Position - npcRoot.Position).Magnitude > range + 3 then return end -- Cooldown check if not HitValidator.IsOffCooldown(player, moveId) then return end HitValidator.RecordUse(player, moveId) combat.state = "Attacking" combat.lastCombatTime = tick() -- Track combo combat.comboCount = (combat.comboCount or 0) local comboTimeout = tick() - (combat.lastHitTime or 0) if comboTimeout > 2 then combat.comboCount = 0 combat.comboDamage = 0 end -- Process hits for i, hitData in ipairs(move.hits) do task.delay(hitData.frame / 60, function() if not combatStates[player] then return end if not npcModel.Parent then return end local npcHum = npcModel:FindFirstChildOfClass("Humanoid") if not npcHum or npcHum.Health <= 0 then return end -- Calculate damage local rawDamage = CombatUtil.CalculateDamage(combat.effectiveStats, hitData.damageMultiplier, false) -- Combo bonus: +5% per hit, max 50% combat.comboCount = combat.comboCount + 1 local comboMult = 1 + math.min(0.5, (combat.comboCount - 1) * 0.05) local damage = math.max(1, math.floor(rawDamage * comboMult)) -- Critical hit: 10% chance + Speed scaling local critChance = 0.10 + (combat.effectiveStats.Speed or 0) / 2000 local isCrit = math.random() < critChance if isCrit then damage = math.floor(damage * 1.5) end combat.comboDamage = (combat.comboDamage or 0) + damage combat.lastHitTime = tick() -- Apply damage to NPC npcHum.Health = npcHum.Health - damage -- Apply knockback if hitData.knockback and npcRoot and npcRoot.Anchored then -- Temporarily unanchor for knockback npcRoot.Anchored = false local direction = CombatUtil.GetKnockbackDirection(attackerRoot.Position, npcRoot.Position) local worldKnockback = direction * hitData.knockback.Z + Vector3.new(0, hitData.knockback.Y, 0) local bv = Instance.new("BodyVelocity") bv.Velocity = worldKnockback bv.MaxForce = Vector3.new(1e6, 1e6, 1e6) bv.P = 1e4 bv.Parent = npcRoot task.delay(0.3, function() bv:Destroy() if npcRoot and npcRoot.Parent then npcRoot.Anchored = true end end) end -- Update visual HP bar on NPC local head = npcModel:FindFirstChild("Head") if head then local billboard = head:FindFirstChild("HealthDisplay") if billboard then local hpBg = billboard:FindFirstChildOfClass("Frame") if hpBg then local hpBar = hpBg:FindFirstChild("HPBar") if hpBar and npcHum.MaxHealth > 0 then hpBar.Size = UDim2.fromScale(math.max(0, npcHum.Health / npcHum.MaxHealth), 1) end end end end -- Broadcast to attacker self.Server.Client.CombatResult:Fire(player, { type = "npc_hit", hitIndex = i, damage = damage, blocked = false, guardBreak = false, launcher = hitData.launcher or false, comboCount = combat.comboCount, comboDamage = combat.comboDamage, isCrit = isCrit, npcModel = npcModel, }) -- Check NPC death if npcHum.Health <= 0 then self.Server.Client.CombatResult:Fire(player, { type = "npc_died", npcModel = npcModel, damage = damage, }) -- Notify NPCSpawnService local NPCSpawnService = Knit.GetService("NPCSpawnService") if NPCSpawnService and NPCSpawnService._handleNPCDeath then NPCSpawnService:_handleNPCDeath(npcModel, player) end end end) end -- Return to idle local lastHit = move.hits[#move.hits] task.delay((lastHit.frame / 60) + 0.5, function() if combatStates[player] and combatStates[player].state == "Attacking" then combatStates[player].state = "Idle" end end) end return CombatService ]]> DataService ()) local profile = profiles[player] if not profile then return false end callback(profile.Data) -- Notify client of changes self.Client.PlayerDataUpdate:Fire(player, profile.Data) return true end function DataService:IsCharacterCreated(player: Player): boolean local data = self:GetData(player) return data and data.CharacterCreated or false end -- Client-facing methods function DataService.Client:RequestPlayerData(player: Player) return self.Server:GetData(player) end function DataService.Client:SubmitCharacterCreation(player: Player, raceChoice: string, appearance: any) local data = self.Server:GetData(player) if not data then return false, "Data not loaded" end if data.CharacterCreated then return false, "Character already created" end if not Races:IsValid(raceChoice) then return false, "Invalid race" end local race = Races:Get(raceChoice) local defaultMoves = Moves:GetDefaultMoves() self.Server:UpdateData(player, function(d) d.Race = raceChoice d.CharacterCreated = true d.UnlockedMoves = defaultMoves -- Apply race base stats for stat, value in pairs(race.baseStats) do d.Stats[stat] = value end end) -- Apply appearance if appearance then self.Server:UpdateData(player, function(d) if appearance.SkinColor then d.Appearance.SkinColor = appearance.SkinColor end if appearance.HairStyle then d.Appearance.HairStyle = appearance.HairStyle end if appearance.HairColor then d.Appearance.HairColor = appearance.HairColor end if appearance.Outfit then d.Appearance.Outfit = appearance.Outfit end if appearance.OutfitColor then d.Appearance.OutfitColor = appearance.OutfitColor end end) end return true, "Character created successfully" end return DataService ]]> LeaderboardService MapService 8 and math.abs(z % 40) > 8 then makeTree(Vector3.new(x, 0, z), zone) end end -- Street lamps for i = -200, 200, 20 do for _, offset in ipairs({ -7, 7 }) do local pole = makePart({ Name = "LampPole", Size = Vector3.new(0.5, 10, 0.5), Position = Vector3.new(i + offset, 5, 0), Color = Color3.fromRGB(80, 80, 80), Material = Enum.Material.Metal, Parent = zone, }) local lamp = makePart({ Name = "Lamp", Size = Vector3.new(2, 1, 2), Position = Vector3.new(i + offset, 10.5, 0), Color = Color3.fromRGB(255, 255, 200), Material = Enum.Material.Neon, Parent = zone, }) local light = Instance.new("PointLight") light.Color = Color3.fromRGB(255, 255, 200) light.Brightness = 1 light.Range = 30 light.Parent = lamp end end -- Training ground (circular arena) makePart({ Name = "TrainingGround", Size = Vector3.new(60, 1, 60), Position = Vector3.new(0, 0.5, 100), Color = Color3.fromRGB(200, 180, 140), Material = Enum.Material.Sandstone, Shape = Enum.PartType.Cylinder, Parent = zone, }) makeZoneLabel("Training Grounds", Vector3.new(0, 2, 100), zone) -- Shop building local shop = makeBuilding( Vector3.new(-80, 0, -60), Vector3.new(20, 15, 20), Color3.fromRGB(255, 200, 100), "Shop", zone, Color3.fromRGB(200, 50, 50) ) makeZoneLabel("SHOP", Vector3.new(-80, 10, -60), zone) -- ============ EXPANDED WEST CITY CONTENT ============ -- Central Fountain/Plaza makePart({ Name = "FountainBase", Size = Vector3.new(20, 2, 20), Position = Vector3.new(0, 1, 0), Color = Color3.fromRGB(200, 200, 210), Material = Enum.Material.Marble, Shape = Enum.PartType.Cylinder, Parent = zone, }) makePart({ Name = "FountainPillar", Size = Vector3.new(3, 8, 3), Position = Vector3.new(0, 6, 0), Color = Color3.fromRGB(200, 200, 210), Material = Enum.Material.Marble, Shape = Enum.PartType.Cylinder, Parent = zone, }) makePart({ Name = "FountainTop", Size = Vector3.new(6, 6, 6), Position = Vector3.new(0, 11, 0), Color = Color3.fromRGB(80, 150, 230), Material = Enum.Material.Glass, Shape = Enum.PartType.Ball, Transparency = 0.3, Parent = zone, }) local fLight = Instance.new("PointLight") fLight.Color = Color3.fromRGB(80, 150, 255) fLight.Brightness = 2 fLight.Range = 30 fLight.Parent = zone:FindFirstChild("FountainTop") or zone -- Park area (northeast) makePart({ Name = "ParkGrass", Size = Vector3.new(150, 0.5, 150), Position = Vector3.new(250, 0.25, -250), Color = Color3.fromRGB(80, 180, 60), Material = Enum.Material.Grass, Parent = zone, }) for i = 1, 20 do makeTree(Vector3.new(250 + math.random(-60, 60), 0.5, -250 + math.random(-60, 60)), zone) end -- Park benches for i = 1, 6 do makePart({ Name = "Bench_" .. i, Size = Vector3.new(6, 1.5, 2), Position = Vector3.new(250 + math.random(-50, 50), 0.75 + 0.5, -250 + math.random(-50, 50)), Color = Color3.fromRGB(120, 80, 40), Material = Enum.Material.Wood, Parent = zone, }) end -- Pond in park makePart({ Name = "Pond", Size = Vector3.new(30, 0.5, 30), Position = Vector3.new(260, 0.4, -260), Color = Color3.fromRGB(60, 130, 200), Material = Enum.Material.Glass, Transparency = 0.3, Shape = Enum.PartType.Cylinder, Parent = zone, }) -- Stadium/Arena (southeast) local stadium = Instance.new("Model") stadium.Name = "Stadium" stadium.Parent = zone -- Arena floor makePart({ Name = "ArenaFloor", Size = Vector3.new(80, 1, 80), Position = Vector3.new(250, 0.5, 250), Color = Color3.fromRGB(200, 180, 140), Material = Enum.Material.Sandstone, Parent = stadium, }) -- Stadium seating (tiered walls) for tier = 1, 3 do local size = 80 + tier * 15 makePart({ Name = "StadiumTier_" .. tier, Size = Vector3.new(size, tier * 4, size), Position = Vector3.new(250, tier * 2, 250), Color = Color3.fromRGB(160, 160, 170), Material = Enum.Material.Concrete, Parent = stadium, }) end makeZoneLabel("PvP Arena", Vector3.new(250, 15, 250), zone) -- Residential area (northwest) — smaller houses for i = 1, 8 do local row = math.floor((i - 1) / 4) local col = (i - 1) % 4 makeBuilding( Vector3.new(-250 + col * 35, 0, -250 + row * 40), Vector3.new(15, 10, 15), Color3.fromRGB(200 + math.random(-20, 20), 190 + math.random(-20, 20), 170 + math.random(-20, 20)), "House_" .. i, zone, Color3.fromRGB(150, 80, 60) ) end makeZoneLabel("Residential District", Vector3.new(-250, 12, -230), zone) -- Market area (southwest) for i = 1, 5 do makePart({ Name = "MarketStall_" .. i, Size = Vector3.new(8, 6, 6), Position = Vector3.new(-250 + i * 15, 3, 250), Color = Color3.fromRGB( math.random(150, 255), math.random(100, 200), math.random(50, 150) ), Material = Enum.Material.Fabric, Parent = zone, }) -- Stall roof makePart({ Name = "StallRoof_" .. i, Size = Vector3.new(10, 0.5, 8), Position = Vector3.new(-250 + i * 15, 6.5, 250), Color = Color3.fromRGB(200, 50, 50), Material = Enum.Material.Fabric, Parent = zone, }) end makeZoneLabel("Market", Vector3.new(-210, 8, 250), zone) -- More distant skyscrapers for city feel for i = 1, 10 do local angle = math.rad(i * 36) local dist = math.random(280, 370) local height = math.random(30, 100) local width = math.random(15, 30) makeBuilding( Vector3.new(math.cos(angle) * dist, 0, math.sin(angle) * dist), Vector3.new(width, height, width), Color3.fromRGB( 160 + math.random(-30, 30), 160 + math.random(-30, 30), 180 + math.random(-20, 20) ), "Skyscraper_" .. i, zone ) end -- Highway overpass makePart({ Name = "HighwayDeck", Size = Vector3.new(800, 1, 16), Position = Vector3.new(0, 15, -350), Color = Color3.fromRGB(70, 70, 70), Material = Enum.Material.Asphalt, Parent = zone, }) -- Highway pillars for i = -350, 350, 50 do makePart({ Name = "HighwayPillar", Size = Vector3.new(3, 15, 3), Position = Vector3.new(i, 7.5, -350), Color = Color3.fromRGB(140, 140, 140), Material = Enum.Material.Concrete, Parent = zone, }) end makeSpawnPoint(Vector3.new(0, 1, 0), "WestCity", zone) makeZoneLabel("West City", Vector3.new(0, 0, -380), zone) end -- ========================================== -- WASTELAND ARENA -- ========================================== function MapService:_buildWastelandArena() local zone = Instance.new("Folder") zone.Name = "WastelandArena" zone.Parent = workspace local OFFSET = Vector3.new(600, 0, 0) -- Desert ground (expanded) makePart({ Name = "Ground", Size = Vector3.new(600, 2, 600), Position = OFFSET + Vector3.new(0, -1, 0), Color = Color3.fromRGB(194, 163, 108), Material = Enum.Material.Sand, Parent = zone, }) -- Rocky terrain - large boulders local rockPositions = { { pos = Vector3.new(80, 0, 80), size = Vector3.new(20, 15, 18) }, { pos = Vector3.new(-70, 0, 50), size = Vector3.new(15, 25, 12) }, { pos = Vector3.new(40, 0, -90), size = Vector3.new(25, 10, 20) }, { pos = Vector3.new(-100, 0, -80), size = Vector3.new(30, 20, 25) }, { pos = Vector3.new(150, 0, 0), size = Vector3.new(18, 30, 15) }, { pos = Vector3.new(-150, 0, 30), size = Vector3.new(22, 18, 20) }, { pos = Vector3.new(0, 0, 150), size = Vector3.new(35, 12, 30) }, { pos = Vector3.new(0, 0, -150), size = Vector3.new(20, 35, 18) }, } for i, cfg in ipairs(rockPositions) do makeRock( OFFSET + cfg.pos + Vector3.new(0, cfg.size.Y / 2, 0), cfg.size, zone, Color3.fromRGB( 130 + math.random(-20, 20), 110 + math.random(-20, 20), 90 + math.random(-20, 20) ) ) end -- Cliff walls on edges makePart({ Name = "CliffNorth", Size = Vector3.new(400, 50, 10), Position = OFFSET + Vector3.new(0, 25, -200), Color = Color3.fromRGB(150, 120, 90), Material = Enum.Material.Rock, Parent = zone, }) makePart({ Name = "CliffSouth", Size = Vector3.new(400, 50, 10), Position = OFFSET + Vector3.new(0, 25, 200), Color = Color3.fromRGB(150, 120, 90), Material = Enum.Material.Rock, Parent = zone, }) -- Battle crater in center makePart({ Name = "Crater", Size = Vector3.new(50, 4, 50), Position = OFFSET + Vector3.new(0, -3, 0), Color = Color3.fromRGB(100, 80, 60), Material = Enum.Material.Slate, Shape = Enum.PartType.Cylinder, Parent = zone, }) -- Scattered small rocks for i = 1, 40 do makeRock( OFFSET + Vector3.new(math.random(-180, 180), math.random(1, 3), math.random(-180, 180)), Vector3.new(math.random(2, 6), math.random(2, 4), math.random(2, 6)), zone ) end makeSpawnPoint(OFFSET + Vector3.new(0, 1, 80), "WastelandArena", zone) makeZoneLabel("Wasteland Arena", OFFSET + Vector3.new(0, 0, -180), zone) end -- ========================================== -- KAMI'S LOOKOUT -- ========================================== function MapService:_buildKamisLookout() local zone = Instance.new("Folder") zone.Name = "KamisLookout" zone.Parent = workspace local OFFSET = Vector3.new(0, 500, 600) -- Main circular platform makePart({ Name = "MainPlatform", Size = Vector3.new(120, 4, 120), Position = OFFSET + Vector3.new(0, 0, 0), Color = Color3.fromRGB(240, 230, 210), Material = Enum.Material.Marble, Shape = Enum.PartType.Cylinder, Parent = zone, }) -- Pillar (tower supporting the lookout) makePart({ Name = "Pillar", Size = Vector3.new(15, 500, 15), Position = OFFSET + Vector3.new(0, -250, 0), Color = Color3.fromRGB(200, 190, 170), Material = Enum.Material.Concrete, Shape = Enum.PartType.Cylinder, Parent = zone, }) -- Palace building local palace = Instance.new("Model") palace.Name = "Palace" palace.Parent = zone makePart({ Name = "PalaceBase", Size = Vector3.new(40, 20, 40), Position = OFFSET + Vector3.new(0, 12, -20), Color = Color3.fromRGB(240, 230, 210), Material = Enum.Material.Marble, Parent = palace, }) makePart({ Name = "PalaceDome", Size = Vector3.new(30, 20, 30), Position = OFFSET + Vector3.new(0, 28, -20), Color = Color3.fromRGB(50, 150, 100), Material = Enum.Material.SmoothPlastic, Shape = Enum.PartType.Ball, Parent = palace, }) -- Spire makePart({ Name = "Spire", Size = Vector3.new(3, 20, 3), Position = OFFSET + Vector3.new(0, 45, -20), Color = Color3.fromRGB(255, 215, 0), Material = Enum.Material.Neon, Parent = palace, }) -- Decorative pillars around edge for angle = 0, 330, 30 do local rad = math.rad(angle) local x = math.cos(rad) * 55 local z = math.sin(rad) * 55 makePart({ Name = "EdgePillar", Size = Vector3.new(3, 12, 3), Position = OFFSET + Vector3.new(x, 8, z), Color = Color3.fromRGB(240, 230, 210), Material = Enum.Material.Marble, Parent = zone, }) end -- Palm trees for i = 1, 8 do local angle = math.rad(i * 45) local x = math.cos(angle) * 40 local z = math.sin(angle) * 40 makeTree(OFFSET + Vector3.new(x, 2, z), zone, Color3.fromRGB(60, 180, 60)) end -- Hyperbolic Time Chamber entrance local htcDoor = makePart({ Name = "HTC_Entrance", Size = Vector3.new(8, 12, 2), Position = OFFSET + Vector3.new(30, 8, 0), Color = Color3.fromRGB(255, 255, 255), Material = Enum.Material.Neon, Transparency = 0.3, Parent = zone, }) makeZoneLabel("Time Chamber", OFFSET + Vector3.new(30, 8, 0), zone) -- Cloud floor below for i = 1, 20 do makePart({ Name = "Cloud_" .. i, Size = Vector3.new( math.random(30, 80), math.random(5, 15), math.random(30, 80) ), Position = OFFSET + Vector3.new( math.random(-200, 200), math.random(-50, -20), math.random(-200, 200) ), Color = Color3.new(1, 1, 1), Material = Enum.Material.SmoothPlastic, Transparency = 0.4, CanCollide = false, Parent = zone, }) end makeSpawnPoint(OFFSET + Vector3.new(0, 3, 30), "KamisLookout", zone) makeZoneLabel("Kami's Lookout", OFFSET + Vector3.new(0, 10, 50), zone) end -- ========================================== -- HYPERBOLIC TIME CHAMBER -- ========================================== function MapService:_buildHyperbolicTimeChamber() local zone = Instance.new("Folder") zone.Name = "HyperbolicTimeChamber" zone.Parent = workspace local OFFSET = Vector3.new(0, 500, 1200) -- Infinite white floor makePart({ Name = "Floor", Size = Vector3.new(2000, 2, 2000), Position = OFFSET + Vector3.new(0, -1, 0), Color = Color3.new(1, 1, 1), Material = Enum.Material.SmoothPlastic, Parent = zone, }) -- Living quarters local quarters = Instance.new("Model") quarters.Name = "LivingQuarters" quarters.Parent = zone makePart({ Name = "Floor", Size = Vector3.new(30, 1, 30), Position = OFFSET + Vector3.new(0, 0.5, 0), Color = Color3.fromRGB(200, 180, 140), Material = Enum.Material.Wood, Parent = quarters, }) -- Beds for _, xOff in ipairs({ -8, 8 }) do makePart({ Name = "Bed", Size = Vector3.new(5, 2, 8), Position = OFFSET + Vector3.new(xOff, 1, -10), Color = Color3.fromRGB(200, 200, 220), Material = Enum.Material.Fabric, Parent = quarters, }) end -- Hourglass makePart({ Name = "Hourglass", Size = Vector3.new(3, 8, 3), Position = OFFSET + Vector3.new(0, 4, -12), Color = Color3.fromRGB(255, 215, 0), Material = Enum.Material.Glass, Shape = Enum.PartType.Cylinder, Parent = quarters, }) -- Zone-specific fog to create infinite void feel -- (client-side fog adjustment would handle this in game) makeSpawnPoint(OFFSET + Vector3.new(0, 1, 5), "HyperbolicTimeChamber", zone) makeZoneLabel("Hyperbolic Time Chamber (3x XP)", OFFSET + Vector3.new(0, 5, 20), zone) end -- ========================================== -- PLANET NAMEK -- ========================================== function MapService:_buildNamek() local zone = Instance.new("Folder") zone.Name = "Namek" zone.Parent = workspace local OFFSET = Vector3.new(2000, 0, 0) -- Green-tinted ground (expanded) makePart({ Name = "Ground", Size = Vector3.new(700, 2, 700), Position = OFFSET + Vector3.new(0, -1, 0), Color = Color3.fromRGB(80, 180, 100), Material = Enum.Material.Grass, Parent = zone, }) -- Namekian water (green water) makePart({ Name = "Water", Size = Vector3.new(150, 1, 200), Position = OFFSET + Vector3.new(150, -0.5, 0), Color = Color3.fromRGB(50, 200, 100), Material = Enum.Material.Glass, Transparency = 0.4, CanCollide = false, Parent = zone, }) -- Namekian houses (dome-shaped) local housePositions = { Vector3.new(0, 0, -60), Vector3.new(-80, 0, 30), Vector3.new(60, 0, 80), Vector3.new(-40, 0, -120), Vector3.new(100, 0, -40), } for i, pos in ipairs(housePositions) do local house = Instance.new("Model") house.Name = "NamekianHouse_" .. i house.Parent = zone makePart({ Name = "Dome", Size = Vector3.new(18, 18, 18), Position = OFFSET + pos + Vector3.new(0, 9, 0), Color = Color3.fromRGB(60, 160, 80), Material = Enum.Material.SmoothPlastic, Shape = Enum.PartType.Ball, Parent = house, }) makePart({ Name = "Base", Size = Vector3.new(20, 4, 20), Position = OFFSET + pos + Vector3.new(0, 2, 0), Color = Color3.fromRGB(80, 140, 90), Material = Enum.Material.Concrete, Parent = house, }) makePart({ Name = "Door", Size = Vector3.new(4, 6, 1), Position = OFFSET + pos + Vector3.new(0, 3, 10), Color = Color3.fromRGB(40, 100, 50), Material = Enum.Material.Wood, Parent = house, }) end -- Namekian trees (tall thin, blue-ish tops) for i = 1, 25 do local x = math.random(-200, 200) local z = math.random(-200, 200) makeTree(OFFSET + Vector3.new(x, 0, z), zone, Color3.fromRGB(50, 120, 180)) end -- Dragon Ball pedestals (3 visible) for i, pos in ipairs({ Vector3.new(0, 0, 0), Vector3.new(-120, 0, -100), Vector3.new(80, 0, 120), }) do local pedestal = makePart({ Name = "DragonBallPedestal_" .. i, Size = Vector3.new(4, 3, 4), Position = OFFSET + pos + Vector3.new(0, 1.5, 0), Color = Color3.fromRGB(180, 160, 120), Material = Enum.Material.Marble, Parent = zone, }) local ball = makePart({ Name = "DragonBall_" .. i, Size = Vector3.new(3, 3, 3), Position = OFFSET + pos + Vector3.new(0, 4.5, 0), Color = Color3.fromRGB(255, 165, 0), Material = Enum.Material.Neon, Shape = Enum.PartType.Ball, Parent = zone, }) local light = Instance.new("PointLight") light.Color = Color3.fromRGB(255, 165, 0) light.Brightness = 2 light.Range = 15 light.Parent = ball end -- Guru's house (larger) local guru = Instance.new("Model") guru.Name = "GuruHouse" guru.Parent = zone makePart({ Name = "Dome", Size = Vector3.new(30, 30, 30), Position = OFFSET + Vector3.new(-100, 15, -150), Color = Color3.fromRGB(80, 180, 100), Material = Enum.Material.SmoothPlastic, Shape = Enum.PartType.Ball, Parent = guru, }) makePart({ Name = "Base", Size = Vector3.new(35, 6, 35), Position = OFFSET + Vector3.new(-100, 3, -150), Color = Color3.fromRGB(100, 160, 110), Material = Enum.Material.Concrete, Parent = guru, }) makeZoneLabel("Guru's House", OFFSET + Vector3.new(-100, 20, -150), zone) makeSpawnPoint(OFFSET + Vector3.new(0, 1, 30), "Namek", zone) makeZoneLabel("Planet Namek", OFFSET + Vector3.new(0, 0, -230), zone) end -- ========================================== -- DEEP SPACE -- ========================================== function MapService:_buildSpace() local zone = Instance.new("Folder") zone.Name = "Space" zone.Parent = workspace local OFFSET = Vector3.new(4000, 0, 0) -- Dark metallic platform (space station) makePart({ Name = "StationFloor", Size = Vector3.new(300, 3, 300), Position = OFFSET + Vector3.new(0, -1.5, 0), Color = Color3.fromRGB(40, 40, 50), Material = Enum.Material.DiamondPlate, Parent = zone, }) -- Frieza's ship (central structure) local ship = Instance.new("Model") ship.Name = "FriezaShip" ship.Parent = zone -- Saucer shape makePart({ Name = "Saucer", Size = Vector3.new(80, 10, 80), Position = OFFSET + Vector3.new(0, 20, 0), Color = Color3.fromRGB(180, 170, 200), Material = Enum.Material.Metal, Shape = Enum.PartType.Cylinder, Parent = ship, }) -- Tower makePart({ Name = "Tower", Size = Vector3.new(20, 40, 20), Position = OFFSET + Vector3.new(0, 45, 0), Color = Color3.fromRGB(160, 150, 180), Material = Enum.Material.Metal, Shape = Enum.PartType.Cylinder, Parent = ship, }) -- Dome top makePart({ Name = "DomeTop", Size = Vector3.new(25, 15, 25), Position = OFFSET + Vector3.new(0, 68, 0), Color = Color3.fromRGB(200, 50, 50), Material = Enum.Material.SmoothPlastic, Shape = Enum.PartType.Ball, Parent = ship, }) -- Landing legs for angle = 0, 270, 90 do local rad = math.rad(angle) makePart({ Name = "Leg_" .. angle, Size = Vector3.new(5, 25, 5), Position = OFFSET + Vector3.new(math.cos(rad) * 35, 7, math.sin(rad) * 35), Color = Color3.fromRGB(120, 120, 130), Material = Enum.Material.Metal, Parent = ship, }) end -- Space debris / asteroids floating for i = 1, 30 do makePart({ Name = "Asteroid_" .. i, Size = Vector3.new( math.random(5, 20), math.random(5, 15), math.random(5, 20) ), Position = OFFSET + Vector3.new( math.random(-200, 200), math.random(30, 100), math.random(-200, 200) ), Color = Color3.fromRGB( 80 + math.random(0, 40), 70 + math.random(0, 40), 70 + math.random(0, 40) ), Material = Enum.Material.Slate, CanCollide = false, Parent = zone, }) end -- Star field (glowing dots) for i = 1, 100 do makePart({ Name = "Star_" .. i, Size = Vector3.new(1, 1, 1), Position = OFFSET + Vector3.new( math.random(-500, 500), math.random(50, 300), math.random(-500, 500) ), Color = Color3.new(1, 1, 1), Material = Enum.Material.Neon, Shape = Enum.PartType.Ball, CanCollide = false, Parent = zone, }) end -- Purple/dark skybox feel via walls for _, dir in ipairs({ { Vector3.new(0, 150, -250), Vector3.new(500, 300, 1) }, { Vector3.new(0, 150, 250), Vector3.new(500, 300, 1) }, { Vector3.new(-250, 150, 0), Vector3.new(1, 300, 500) }, { Vector3.new(250, 150, 0), Vector3.new(1, 300, 500) }, }) do makePart({ Name = "SpaceWall", Size = dir[2], Position = OFFSET + dir[1], Color = Color3.fromRGB(10, 5, 30), Material = Enum.Material.SmoothPlastic, Parent = zone, }) end makeSpawnPoint(OFFSET + Vector3.new(0, 1, 80), "Space", zone) makeZoneLabel("Deep Space - Frieza's Domain", OFFSET + Vector3.new(0, 30, -130), zone) end -- ========================================== -- BEERUS'S PLANET -- ========================================== function MapService:_buildBeerusPlanet() local zone = Instance.new("Folder") zone.Name = "BeerusPlanet" zone.Parent = workspace local OFFSET = Vector3.new(6000, 0, 0) -- Upside-down tree planet (iconic shape) -- Main ground platform (the top of the "tree") makePart({ Name = "Ground", Size = Vector3.new(200, 4, 200), Position = OFFSET + Vector3.new(0, 0, 0), Color = Color3.fromRGB(140, 200, 100), Material = Enum.Material.Grass, Shape = Enum.PartType.Cylinder, Parent = zone, }) -- Giant tree trunk going down makePart({ Name = "TreeTrunk", Size = Vector3.new(40, 300, 40), Position = OFFSET + Vector3.new(0, -150, 0), Color = Color3.fromRGB(120, 80, 40), Material = Enum.Material.Wood, Shape = Enum.PartType.Cylinder, Parent = zone, }) -- Beerus's palace local palace = Instance.new("Model") palace.Name = "BeerusPalace" palace.Parent = zone -- Egyptian/pyramid-ish palace makePart({ Name = "PalaceBase", Size = Vector3.new(60, 15, 60), Position = OFFSET + Vector3.new(0, 9.5, -30), Color = Color3.fromRGB(200, 180, 130), Material = Enum.Material.Sandstone, Parent = palace, }) makePart({ Name = "PalaceMiddle", Size = Vector3.new(45, 12, 45), Position = OFFSET + Vector3.new(0, 23, -30), Color = Color3.fromRGB(210, 190, 140), Material = Enum.Material.Sandstone, Parent = palace, }) makePart({ Name = "PalaceTop", Size = Vector3.new(30, 10, 30), Position = OFFSET + Vector3.new(0, 34, -30), Color = Color3.fromRGB(220, 200, 150), Material = Enum.Material.Sandstone, Parent = palace, }) -- Spires for _, xz in ipairs({ { -25, -5 }, { 25, -5 }, { -25, -55 }, { 25, -55 } }) do makePart({ Name = "Spire", Size = Vector3.new(5, 30, 5), Position = OFFSET + Vector3.new(xz[1], 17, xz[2]), Color = Color3.fromRGB(200, 170, 100), Material = Enum.Material.Sandstone, Parent = palace, }) makePart({ Name = "SpireTop", Size = Vector3.new(3, 3, 3), Position = OFFSET + Vector3.new(xz[1], 33, xz[2]), Color = Color3.fromRGB(180, 50, 200), Material = Enum.Material.Neon, Shape = Enum.PartType.Ball, Parent = palace, }) end -- Koi pond makePart({ Name = "KoiPond", Size = Vector3.new(25, 1, 25), Position = OFFSET + Vector3.new(50, 0, 40), Color = Color3.fromRGB(80, 150, 220), Material = Enum.Material.Glass, Transparency = 0.3, Shape = Enum.PartType.Cylinder, Parent = zone, }) -- Cherry blossom trees (pink) for i = 1, 12 do local angle = math.rad(i * 30) local r = math.random(50, 90) makeTree( OFFSET + Vector3.new(math.cos(angle) * r, 2, math.sin(angle) * r), zone, Color3.fromRGB(255, 150, 180) ) end -- Oracle fish pond makeZoneLabel("Oracle Fish", OFFSET + Vector3.new(50, 3, 40), zone) -- Training courtyard makePart({ Name = "TrainingYard", Size = Vector3.new(40, 0.5, 40), Position = OFFSET + Vector3.new(-50, 2.5, 50), Color = Color3.fromRGB(220, 210, 180), Material = Enum.Material.Marble, Parent = zone, }) makeZoneLabel("Training Courtyard", OFFSET + Vector3.new(-50, 3, 50), zone) makeSpawnPoint(OFFSET + Vector3.new(0, 3, 50), "BeerusPlanet", zone) makeZoneLabel("Beerus's Planet", OFFSET + Vector3.new(0, 10, 90), zone) end -- ========================================== -- TOURNAMENT OF POWER -- ========================================== function MapService:_buildTournamentOfPower() local zone = Instance.new("Folder") zone.Name = "TournamentOfPower" zone.Parent = workspace local OFFSET = Vector3.new(8000, 0, 0) -- The arena stage (floating platform with rocky terrain) makePart({ Name = "ArenaPlatform", Size = Vector3.new(300, 8, 300), Position = OFFSET + Vector3.new(0, -4, 0), Color = Color3.fromRGB(160, 140, 120), Material = Enum.Material.Slate, Parent = zone, }) -- Uneven rocky terrain on the arena for i = 1, 50 do local x = math.random(-130, 130) local z = math.random(-130, 130) makeRock( OFFSET + Vector3.new(x, math.random(1, 8), z), Vector3.new( math.random(5, 20), math.random(5, 25), math.random(5, 20) ), zone, Color3.fromRGB( 140 + math.random(-30, 30), 120 + math.random(-30, 30), 100 + math.random(-30, 30) ) ) end -- Pillars/ruins scattered for i = 1, 15 do local x = math.random(-120, 120) local z = math.random(-120, 120) makePart({ Name = "Pillar_" .. i, Size = Vector3.new(4, math.random(10, 30), 4), Position = OFFSET + Vector3.new(x, math.random(5, 15), z), Color = Color3.fromRGB(180, 170, 150), Material = Enum.Material.Concrete, Parent = zone, }) end -- Spectator benches (Zen-Oh's throne area) makePart({ Name = "ZenOhPlatform", Size = Vector3.new(30, 3, 30), Position = OFFSET + Vector3.new(0, 60, -180), Color = Color3.fromRGB(100, 50, 200), Material = Enum.Material.Neon, Parent = zone, }) -- Throne makePart({ Name = "Throne", Size = Vector3.new(8, 10, 5), Position = OFFSET + Vector3.new(0, 68, -180), Color = Color3.fromRGB(255, 215, 0), Material = Enum.Material.Neon, Parent = zone, }) -- Universe team benches (floating platforms around arena) for i = 1, 8 do local angle = math.rad(i * 45) local dist = 180 makePart({ Name = "UniverseBench_" .. i, Size = Vector3.new(20, 2, 10), Position = OFFSET + Vector3.new(math.cos(angle) * dist, 40, math.sin(angle) * dist), Color = Color3.fromRGB(150, 150, 200), Material = Enum.Material.SmoothPlastic, Parent = zone, }) end -- Void below (dark) makePart({ Name = "Void", Size = Vector3.new(1000, 1, 1000), Position = OFFSET + Vector3.new(0, -50, 0), Color = Color3.fromRGB(20, 10, 40), Material = Enum.Material.SmoothPlastic, CanCollide = false, Parent = zone, }) -- Starfield around arena for i = 1, 80 do makePart({ Name = "Star_" .. i, Size = Vector3.new(math.random(1, 3), math.random(1, 3), math.random(1, 3)), Position = OFFSET + Vector3.new( math.random(-400, 400), math.random(-30, 80), math.random(-400, 400) ), Color = Color3.new(1, 1, 1), Material = Enum.Material.Neon, Shape = Enum.PartType.Ball, CanCollide = false, Parent = zone, }) end makeSpawnPoint(OFFSET + Vector3.new(0, 1, 0), "TournamentOfPower", zone) makeZoneLabel("Tournament of Power", OFFSET + Vector3.new(0, 30, -130), zone) end -- ========================================== -- ZONE PORTALS (Teleporters between zones) -- ========================================== function MapService:_buildZonePortals() local portals = Instance.new("Folder") portals.Name = "ZonePortals" portals.Parent = workspace local portalDefs = { -- From West City { from = "WestCity", to = "WastelandArena", fromPos = Vector3.new(230, 0, 0), toPos = Vector3.new(600 - 180, 0, 0), levelReq = 10 }, { from = "WestCity", to = "KamisLookout", fromPos = Vector3.new(0, 0, -230), toPos = Vector3.new(0, 503, 630), levelReq = 20 }, { from = "WestCity", to = "Namek", fromPos = Vector3.new(-230, 0, 0), toPos = Vector3.new(2000, 0, 200), levelReq = 40 }, -- From Wasteland { from = "WastelandArena", to = "Space", fromPos = Vector3.new(600 + 180, 0, 0), toPos = Vector3.new(4000, 0, 120), levelReq = 60 }, -- From Space { from = "Space", to = "BeerusPlanet", fromPos = Vector3.new(4000 + 130, 0, 0), toPos = Vector3.new(6000, 3, 80), levelReq = 80 }, -- From Beerus { from = "BeerusPlanet", to = "TournamentOfPower", fromPos = Vector3.new(6000 + 90, 0, 0), toPos = Vector3.new(8000, 1, 100), levelReq = 100 }, } for _, def in ipairs(portalDefs) do -- Create portal at 'from' location local portal = Instance.new("Model") portal.Name = "Portal_" .. def.from .. "_to_" .. def.to portal.Parent = portals -- Portal ring local ring = makePart({ Name = "PortalRing", Size = Vector3.new(10, 14, 2), Position = def.fromPos + Vector3.new(0, 7, 0), Color = Color3.fromRGB(100, 50, 255), Material = Enum.Material.Neon, Transparency = 0.3, CanCollide = false, Parent = portal, }) -- Swirl center local center = makePart({ Name = "PortalCenter", Size = Vector3.new(8, 12, 0.5), Position = def.fromPos + Vector3.new(0, 7, 0), Color = Color3.fromRGB(150, 100, 255), Material = Enum.Material.Neon, Transparency = 0.5, CanCollide = false, Parent = portal, }) -- Particle effect local particles = Instance.new("ParticleEmitter") particles.Color = ColorSequence.new(Color3.fromRGB(150, 100, 255)) particles.Size = NumberSequence.new(1) particles.Lifetime = NumberRange.new(0.5, 1) particles.Rate = 30 particles.Speed = NumberRange.new(2, 5) particles.SpreadAngle = Vector2.new(180, 180) particles.LightEmission = 1 particles.Parent = center -- Light local light = Instance.new("PointLight") light.Color = Color3.fromRGB(150, 100, 255) light.Brightness = 2 light.Range = 20 light.Parent = center -- Label makeZoneLabel(def.to .. " (Lv. " .. def.levelReq .. "+)", def.fromPos, portal) -- Teleport touch detection local touchPart = makePart({ Name = "TouchDetector", Size = Vector3.new(8, 12, 4), Position = def.fromPos + Vector3.new(0, 7, 0), Transparency = 1, CanCollide = false, Parent = portal, }) -- Store destination as attributes touchPart:SetAttribute("DestinationX", def.toPos.X) touchPart:SetAttribute("DestinationY", def.toPos.Y + 5) touchPart:SetAttribute("DestinationZ", def.toPos.Z) touchPart:SetAttribute("LevelReq", def.levelReq) touchPart.Touched:Connect(function(hit) local character = hit.Parent local player = game.Players:GetPlayerFromCharacter(character) if not player then return end -- Debounce if touchPart:GetAttribute("_cd_" .. player.UserId) then return end touchPart:SetAttribute("_cd_" .. player.UserId, true) -- Level check local DataService = Knit.GetService("DataService") local data = DataService:GetData(player) if data and data.Level >= def.levelReq then local rootPart = character:FindFirstChild("HumanoidRootPart") if rootPart then rootPart.CFrame = CFrame.new(def.toPos + Vector3.new(0, 5, 0)) end end task.delay(3, function() touchPart:SetAttribute("_cd_" .. player.UserId, nil) end) end) end end -- ========================================== -- SPAWN AREA (first-time spawn hub) -- ========================================== function MapService:_buildSpawnArea() -- Initial spawn is in West City center -- Create a welcome area local hub = Instance.new("Folder") hub.Name = "SpawnHub" hub.Parent = workspace -- Welcome arch makePart({ Name = "ArchLeft", Size = Vector3.new(3, 20, 3), Position = Vector3.new(-10, 10, 30), Color = Color3.fromRGB(255, 215, 0), Material = Enum.Material.Neon, Parent = hub, }) makePart({ Name = "ArchRight", Size = Vector3.new(3, 20, 3), Position = Vector3.new(10, 10, 30), Color = Color3.fromRGB(255, 215, 0), Material = Enum.Material.Neon, Parent = hub, }) makePart({ Name = "ArchTop", Size = Vector3.new(23, 3, 3), Position = Vector3.new(0, 21, 30), Color = Color3.fromRGB(255, 215, 0), Material = Enum.Material.Neon, Parent = hub, }) makeZoneLabel("DRAGON BALL ULTIMATE", Vector3.new(0, 15, 30), hub) -- Info boards local infoPositions = { { pos = Vector3.new(-20, 0, 20), text = "Controls:\nM1/M2 - Attack\nE - Ki Blast\nF - Block\nQ - Vanish\nC - Charge Ki\nT - Transform" }, { pos = Vector3.new(20, 0, 20), text = "Tips:\n- Train to gain XP\n- Allocate stat points\n- Unlock transformations\n- Complete saga quests\n- Challenge other players!" }, } for _, info in ipairs(infoPositions) do local board = makePart({ Name = "InfoBoard", Size = Vector3.new(12, 10, 0.5), Position = info.pos + Vector3.new(0, 7, 0), Color = Color3.fromRGB(40, 40, 60), Material = Enum.Material.SmoothPlastic, Parent = hub, }) local gui = Instance.new("SurfaceGui") gui.Face = Enum.NormalId.Front gui.Parent = board local label = Instance.new("TextLabel") label.Size = UDim2.fromScale(1, 1) label.BackgroundTransparency = 1 label.Text = info.text label.TextColor3 = Color3.new(1, 1, 1) label.TextSize = 20 label.Font = Enum.Font.Gotham label.TextWrapped = true label.TextYAlignment = Enum.TextYAlignment.Top label.Parent = gui end end return MapService ]]> NPCService NPCSpawnService 0.1 then npcRoot.CFrame = CFrame.lookAt(npcRoot.Position, npcRoot.Position + direction) end -- Attack if in melee range if nearestDist <= 8 then local CombatService = Knit.GetService("CombatService") local combat = CombatService:GetCombatState(nearestPlayer) if combat then local damage = npc.definition.damage or 10 local isBlocking = combat.state == "Blocking" if isBlocking then damage = math.floor(damage * 0.4) end combat.hp = math.max(0, combat.hp - damage) combat.lastCombatTime = tick() -- Notify player of NPC attack CombatService.Client.CombatResult:Fire(nearestPlayer, { type = "melee_received", attacker = npcModel, damage = damage, blocked = isBlocking, guardBreak = false, launcher = false, }) -- Check player death if combat.hp <= 0 then CombatService:_handleDeath(nearestPlayer, nil) end end end end end end -- Attack interval: bosses hit fast, normal NPCs moderate local attackInterval = npc.isBoss and 1.0 or 1.8 task.wait(attackInterval) end end return NPCSpawnService ]]> ProgressionService = required then d.XP = d.XP - required d.Level = d.Level + 1 d.StatPoints = d.StatPoints + Settings.Progression.STAT_POINTS_PER_LEVEL else break end end end) -- Refresh combat stats after leveling local CombatService = Knit.GetService("CombatService") CombatService:RefreshStats(player) end function ProgressionService:AwardZeni(player: Player, amount: number) local DataService = Knit.GetService("DataService") DataService:UpdateData(player, function(d) d.Zeni = d.Zeni + amount end) end function ProgressionService:AllocateStat(player: Player, statName: string, points: number): (boolean, string?) if not table.find(Stats.Names, statName) then return false, "Invalid stat name" end if points < 1 then return false, "Must allocate at least 1 point" end local DataService = Knit.GetService("DataService") local data = DataService:GetData(player) if not data then return false, "Data not loaded" end if data.StatPoints < points then return false, "Not enough stat points" end DataService:UpdateData(player, function(d) d.StatPoints = d.StatPoints - points d.Stats[statName] = d.Stats[statName] + points end) local CombatService = Knit.GetService("CombatService") CombatService:RefreshStats(player) return true, nil end function ProgressionService:Rebirth(player: Player): (boolean, string?) local DataService = Knit.GetService("DataService") local data = DataService:GetData(player) if not data then return false, "Data not loaded" end if data.Level < Settings.Progression.MAX_LEVEL then return false, "Must be max level to rebirth" end if data.Rebirths >= Settings.Progression.MAX_REBIRTHS then return false, "Maximum rebirths reached" end DataService:UpdateData(player, function(d) d.Rebirths = d.Rebirths + 1 d.Level = 1 d.XP = 0 d.StatPoints = 3 -- Reset allocated stats to base local race = Races:Get(d.Race) if race then for stat, value in pairs(race.baseStats) do d.Stats[stat] = value end end -- Keep: transformations, moves, zeni, quest progress, appearance end) local CombatService = Knit.GetService("CombatService") CombatService:RefreshStats(player) return true, nil end -- Client methods function ProgressionService.Client:AllocateStat(player: Player, statName: string, points: number) return self.Server:AllocateStat(player, statName, points) end function ProgressionService.Client:RequestRebirth(player: Player) return self.Server:Rebirth(player) end return ProgressionService ]]> PvpService 0.5 or waitTime > Settings.PvP.QUEUE_TIMEOUT then table.remove(rankedQueue, i + 1) table.remove(rankedQueue, i) self:_startMatch(a.player, b.player, "Ranked") else i = i + 1 end end end function PvpService:_startMatch(player1: Player, player2: Player, mode: string) local matchId = player1.UserId .. "_" .. player2.UserId .. "_" .. tick() activeMatches[matchId] = { player1 = player1, player2 = player2, mode = mode, round = 1, player1Wins = 0, player2Wins = 0, startTime = tick(), } -- Notify both players self.Client.PvpMatchStart:Fire(player1, { matchId = matchId, opponent = player2, mode = mode, }) self.Client.PvpMatchStart:Fire(player2, { matchId = matchId, opponent = player1, mode = mode, }) -- TODO: Teleport players to arena end function PvpService:ReportRoundWin(matchId: string, winner: Player) local match = activeMatches[matchId] if not match then return end if winner == match.player1 then match.player1Wins = match.player1Wins + 1 else match.player2Wins = match.player2Wins + 1 end local requiredWins = math.ceil(Settings.PvP.MATCH_ROUNDS / 2) if match.player1Wins >= requiredWins then self:_endMatch(matchId, match.player1, match.player2) elseif match.player2Wins >= requiredWins then self:_endMatch(matchId, match.player2, match.player1) else match.round = match.round + 1 -- Next round starts end end function PvpService:_endMatch(matchId: string, winner: Player, loser: Player) local match = activeMatches[matchId] if not match then return end local DataService = Knit.GetService("DataService") local ProgressionService = Knit.GetService("ProgressionService") -- Update ELO local winnerData = DataService:GetData(winner) local loserData = DataService:GetData(loser) if winnerData and loserData then local newWinnerElo, newLoserElo = EloCalculator.Calculate(winnerData.PvpElo, loserData.PvpElo) DataService:UpdateData(winner, function(d) d.PvpElo = newWinnerElo d.PvpWins = d.PvpWins + 1 end) DataService:UpdateData(loser, function(d) d.PvpElo = newLoserElo d.PvpLosses = d.PvpLosses + 1 end) end -- Award XP/Zeni ProgressionService:AwardXP(winner, Settings.Progression.PVP_WIN_XP_BASE) ProgressionService:AwardZeni(winner, Settings.Economy.PVP_WIN_ZENI) -- Notify players self.Client.PvpMatchEnd:Fire(winner, { result = "win", matchId = matchId }) self.Client.PvpMatchEnd:Fire(loser, { result = "loss", matchId = matchId }) activeMatches[matchId] = nil end -- Client methods function PvpService.Client:JoinQueue(player: Player, mode: string) if mode ~= "Ranked" then return end -- Check not already in queue for _, entry in ipairs(rankedQueue) do if entry.player == player then return end end local DataService = Knit.GetService("DataService") local data = DataService:GetData(player) if not data then return end table.insert(rankedQueue, { player = player, elo = data.PvpElo, joinTime = tick(), }) end function PvpService.Client:LeaveQueue(player: Player) for i, entry in ipairs(rankedQueue) do if entry.player == player then table.remove(rankedQueue, i) return end end end return PvpService ]]> QuestService = obj.target then obj.current = obj.target obj.completed = true end updated = true end -- Check if all objectives complete local allDone = true for _, obj in ipairs(progress.objectives) do if not obj.completed then allDone = false break end end if allDone then progress.completed = true self:_completeQuest(player, questId) end end end) if updated then self.Client.QuestUpdate:Fire(player, data.QuestProgress) end end function QuestService:_completeQuest(player: Player, questId: string) local quest, saga = Sagas:GetQuestById(questId) if not quest then return end local ProgressionService = Knit.GetService("ProgressionService") local TransformationService = Knit.GetService("TransformationService") local DataService = Knit.GetService("DataService") -- Award rewards if quest.rewards.xp then ProgressionService:AwardXP(player, quest.rewards.xp) end if quest.rewards.zeni then ProgressionService:AwardZeni(player, quest.rewards.zeni) end -- Unlock transformations if quest.rewards.transformations then for _, formId in ipairs(quest.rewards.transformations) do TransformationService:UnlockTransformation(player, formId) end end -- Unlock moves if quest.rewards.moves then DataService:UpdateData(player, function(d) for _, moveId in ipairs(quest.rewards.moves) do if not table.find(d.UnlockedMoves, moveId) then table.insert(d.UnlockedMoves, moveId) end end end) end -- Remove from active quests DataService:UpdateData(player, function(d) d.QuestProgress[questId] = nil end) -- Check if saga is complete local allSagaQuestsDone = true for _, q in ipairs(saga.quests) do if q.id ~= questId then local data = DataService:GetData(player) -- Check if other quests were completed previously (simplified) end end self.Client.QuestComplete:Fire(player, { questId = questId, rewards = quest.rewards, }) end function QuestService:AbandonQuest(player: Player, questId: string) local DataService = Knit.GetService("DataService") DataService:UpdateData(player, function(d) d.QuestProgress[questId] = nil end) end -- Client methods function QuestService.Client:AcceptQuest(player: Player, questId: string) return self.Server:AcceptQuest(player, questId) end function QuestService.Client:AbandonQuest(player: Player, questId: string) self.Server:AbandonQuest(player, questId) end return QuestService ]]> TransformationService WorldBossService = Settings.WorldBoss.MIN_PLAYERS_TO_SPAWN then self:_spawnRandomBoss() end end end) end function WorldBossService:_spawnRandomBoss() local boss = WORLD_BOSSES[math.random(#WORLD_BOSSES)] activeBoss = { definition = boss, currentHp = boss.hp, model = nil, -- Would create a large boss model here damageContributions = {}, } -- Announce to all players -- TODO: Use a notification system print("[WorldBoss] " .. boss.displayName .. " has appeared!") end function WorldBossService:DamageBoss(player: Player, damage: number): boolean if not activeBoss then return false end activeBoss.currentHp = activeBoss.currentHp - damage activeBoss.damageContributions[player] = (activeBoss.damageContributions[player] or 0) + damage if activeBoss.currentHp <= 0 then self:_handleBossDefeat() return true end return false end function WorldBossService:_handleBossDefeat() if not activeBoss then return end local totalDamage = 0 for _, dmg in pairs(activeBoss.damageContributions) do totalDamage = totalDamage + dmg end local ProgressionService = Knit.GetService("ProgressionService") local DataService = Knit.GetService("DataService") -- Reward contributors for player, dmg in pairs(activeBoss.damageContributions) do local contribution = dmg / totalDamage if contribution >= Settings.WorldBoss.DAMAGE_CONTRIBUTION_THRESHOLD then -- Base rewards ProgressionService:AwardXP(player, Settings.Progression.WORLD_BOSS_PARTICIPATION_XP) ProgressionService:AwardZeni(player, Settings.Economy.WORLD_BOSS_ZENI) -- Roll loot local loot = LootTable.Roll(activeBoss.definition.lootTable) self:_grantLoot(player, loot) end end -- Clean up if activeBoss.model then activeBoss.model:Destroy() end activeBoss = nil print("[WorldBoss] Boss defeated!") end function WorldBossService:_grantLoot(player: Player, loot: any) local ProgressionService = Knit.GetService("ProgressionService") local DataService = Knit.GetService("DataService") if loot.type == "zeni" then ProgressionService:AwardZeni(player, loot.amount) elseif loot.type == "xp" then ProgressionService:AwardXP(player, loot.amount) elseif loot.type == "move" then DataService:UpdateData(player, function(d) if not table.find(d.UnlockedMoves, loot.moveId) then table.insert(d.UnlockedMoves, loot.moveId) end end) elseif loot.type == "cosmetic" then -- TODO: Cosmetic system end end return WorldBossService ]]> StarterPlayer StarterPlayerScripts Client Controllers AudioController CameraController ())?) camera.CameraType = Enum.CameraType.Scriptable local startCFrame = camera.CFrame local endCFrame = CFrame.lookAt( targetPosition + Vector3.new(0, 3, 8), targetPosition ) local tweenInfo = TweenInfo.new(duration, Enum.EasingStyle.Cubic, Enum.EasingDirection.InOut) local proxy = Instance.new("CFrameValue") proxy.Value = startCFrame proxy.Changed:Connect(function() camera.CFrame = proxy.Value end) local tween = TweenService:Create(proxy, tweenInfo, { Value = endCFrame }) tween:Play() tween.Completed:Connect(function() proxy:Destroy() if callback then callback() end end) end function CameraController:ResetCamera() camera.CameraType = Enum.CameraType.Custom lockOnTarget = nil end return CameraController ]]> CombatController nearestDist then continue end local dot = lookDir:Dot(toTarget.Unit) if dot > 0.5 then nearestDist = dist nearest = model end end return nearest end -- Resolve a target model and send the appropriate server call function CombatController:_attackTarget(moveId: string) local targetModel = self:_getLockedTargetModel() or self:_getTargetModelInFront() if not targetModel then return end -- Check if target is a Player or NPC local targetPlayer = Players:GetPlayerFromCharacter(targetModel) if targetPlayer then CombatService:MeleeAttack(targetPlayer, moveId) else -- NPC target — send model reference to server CombatService:MeleeAttackNPC(targetModel, moveId) end local VfxController = Knit.GetController("VfxController") VfxController:PlayMeleeEffect(moveId) end function CombatController:OnLightAttack(target: Player?) if target then CombatService:MeleeAttack(target, "LightCombo") local VfxController = Knit.GetController("VfxController") VfxController:PlayMeleeEffect("LightCombo") return end self:_attackTarget("LightCombo") end function CombatController:OnHeavyAttack(target: Player?) if target then CombatService:MeleeAttack(target, "HeavyAttack") local VfxController = Knit.GetController("VfxController") VfxController:PlayMeleeEffect("HeavyAttack") return end self:_attackTarget("HeavyAttack") end function CombatController:OnKiBlast() local character = localPlayer.Character if not character then return end local rootPart = character:FindFirstChild("HumanoidRootPart") if not rootPart then return end -- Aim toward locked target if available local targetModel = self:_getLockedTargetModel() local direction = rootPart.CFrame.LookVector if targetModel then local targetRoot = targetModel:FindFirstChild("HumanoidRootPart") if targetRoot then direction = (targetRoot.Position - rootPart.Position).Unit end end CombatService:KiBlast(direction, "KiBlast") end function CombatController:OnChargedKiBlastStart() local VfxController = Knit.GetController("VfxController") VfxController:StartChargeEffect() end function CombatController:OnChargedKiBlastRelease() local character = localPlayer.Character if not character then return end local rootPart = character:FindFirstChild("HumanoidRootPart") if not rootPart then return end local targetModel = self:_getLockedTargetModel() local direction = rootPart.CFrame.LookVector if targetModel then local targetRoot = targetModel:FindFirstChild("HumanoidRootPart") if targetRoot then direction = (targetRoot.Position - rootPart.Position).Unit end end CombatService:KiBlast(direction, "ChargedKiBlast") local VfxController = Knit.GetController("VfxController") VfxController:StopChargeEffect() end function CombatController:OnBlock(isBlocking: boolean) CombatService:Block(isBlocking) end function CombatController:OnVanish() CombatService:Vanish() end function CombatController:OnChargeKi(isCharging: boolean) CombatService:ChargeKi(isCharging) local VfxController = Knit.GetController("VfxController") if isCharging then VfxController:StartKiChargeEffect() else VfxController:StopKiChargeEffect() end end function CombatController:OnSkill(slotIndex: number) local DataService = Knit.GetService("DataService") DataService:RequestPlayerData():andThen(function(data) if not data then return end local moveId = data.MoveLoadout[slotIndex] if not moveId then return end local move = Moves:Get(moveId) if not move then return end if move.category == "Beam" or move.category == "Signature" or move.category == "Ultimate" then local character = localPlayer.Character if not character then return end local rootPart = character:FindFirstChild("HumanoidRootPart") if not rootPart then return end -- Aim toward locked target local targetModel = self:_getLockedTargetModel() local direction = rootPart.CFrame.LookVector if targetModel then local targetRoot = targetModel:FindFirstChild("HumanoidRootPart") if targetRoot then direction = (targetRoot.Position - rootPart.Position).Unit end end CombatService:KiBlast(direction, moveId) elseif move.category == "Evasive" then CombatService:Vanish() end end) end function CombatController:_handleCombatResult(result: any) local VfxController = Knit.GetController("VfxController") local AudioController = Knit.GetController("AudioController") local CameraController = Knit.GetController("CameraController") local UIController = Knit.GetController("UIController") -- ===== STATE SYNC: Update HUD bars every frame ===== if result.type == "state_sync" then UIController:UpdateHealthBar(result.hp, result.maxHp) UIController:UpdateKiBar(result.ki, result.maxKi) UIController:UpdateStaminaBar(result.stamina, result.maxStamina) return end if result.type == "melee" or result.type == "melee_received" or result.type == "npc_hit" then if result.blocked then AudioController:PlaySound("BlockHit") else AudioController:PlaySound("MeleeHit") CameraController:ScreenShake(0.15, math.clamp(result.damage / 50, 0.1, 1.5)) if result.launcher then VfxController:PlayLaunchEffect(result.target or result.attacker) end end if result.guardBreak then AudioController:PlaySound("GuardBreak") CameraController:ScreenShake(0.5, 1.0) end -- Combo counter if result.comboCount and result.comboCount > 1 then -- UIController will display this local UIController = Knit.GetController("UIController") if UIController.ShowComboCounter then UIController:ShowComboCounter(result.comboCount, result.comboDamage or 0) end end elseif result.type == "ki_blast" then VfxController:SpawnKiBlastProjectile(result.attacker, result.direction, result.moveId, result.origin) AudioController:PlaySound("KiBlast") elseif result.type == "vanish" then VfxController:PlayVanishEffect(result.player) AudioController:PlaySound("Vanish") elseif result.type == "npc_died" then AudioController:PlaySound("Explosion") CameraController:ScreenShake(0.3, 0.8) end end function CombatController:_handleBeamStruggle(result: any) local VfxController = Knit.GetController("VfxController") local CameraController = Knit.GetController("CameraController") VfxController:PlayBeamStruggleResult(result.winner) CameraController:ScreenShake(1.0, 2.0) end return CombatController ]]> DamageNumberController 0 and result.comboCount % 5 == 0 then task.delay(0.15, function() self:SpawnText(targetModel, result.comboCount .. " HIT COMBO!", Color3.fromRGB(255, 200, 50), true) end) end elseif result.type == "melee_received" then -- Show damage on our own character local myChar = localPlayer.Character if myChar then local color = result.blocked and Color3.fromRGB(150, 150, 150) or Color3.fromRGB(255, 80, 80) self:SpawnNumber(myChar, tostring(result.damage), color, false) end elseif result.type == "npc_died" then local targetModel = result.npcModel if targetModel then self:SpawnText(targetModel, "KO!", Color3.fromRGB(255, 50, 50), true) end end end function DamageNumberController:SpawnNumber(targetModel: Model, text: string, color: Color3, isBig: boolean?) local head = targetModel:FindFirstChild("Head") or targetModel:FindFirstChild("HumanoidRootPart") if not head then return end -- Stagger offset so numbers don't overlap activeNumbers = activeNumbers + 1 local offset = Vector3.new(math.random(-10, 10) / 10, 2 + (activeNumbers % 3) * 0.8, math.random(-5, 5) / 10) local billboard = Instance.new("BillboardGui") billboard.Name = "DamageNumber" billboard.Size = isBig and UDim2.new(4, 0, 1.5, 0) or UDim2.new(3, 0, 1, 0) billboard.StudsOffset = offset billboard.AlwaysOnTop = true billboard.MaxDistance = 100 billboard.Parent = head local label = Instance.new("TextLabel") label.Size = UDim2.fromScale(1, 1) label.BackgroundTransparency = 1 label.Text = text label.TextColor3 = color label.TextStrokeColor3 = Color3.new(0, 0, 0) label.TextStrokeTransparency = 0 label.TextSize = isBig and 28 or 22 label.Font = Enum.Font.GothamBold label.TextScaled = false label.Parent = billboard -- Animate: float up + fade out local duration = 0.8 -- Scale pop on crits if isBig then label.TextSize = 10 TweenService:Create(label, TweenInfo.new(0.15, Enum.EasingStyle.Back, Enum.EasingDirection.Out), { TextSize = 32, }):Play() end -- Float upward TweenService:Create(billboard, TweenInfo.new(duration, Enum.EasingStyle.Quad, Enum.EasingDirection.Out), { StudsOffset = offset + Vector3.new(0, 2, 0), }):Play() -- Fade out TweenService:Create(label, TweenInfo.new(duration * 0.6, Enum.EasingStyle.Linear, Enum.EasingDirection.In, 0, false, duration * 0.4), { TextTransparency = 1, TextStrokeTransparency = 1, }):Play() -- Cleanup task.delay(duration + 0.1, function() billboard:Destroy() activeNumbers = math.max(0, activeNumbers - 1) end) end function DamageNumberController:SpawnText(targetModel: Model, text: string, color: Color3, isBig: boolean?) self:SpawnNumber(targetModel, text, color, isBig) end return DamageNumberController ]]> InputController IntroController QuestController TargetController MAX_TARGET_RANGE * 2 then self:SetTarget(nil) return nil end end end end return currentTarget end function TargetController:CycleTarget() local targets = self:_getTargetsInRange() if #targets == 0 then self:SetTarget(nil) return end -- Find current target index local currentIdx = 0 for i, t in ipairs(targets) do if t == currentTarget then currentIdx = i break end end -- Cycle to next local nextIdx = (currentIdx % #targets) + 1 self:SetTarget(targets[nextIdx]) end function TargetController:_getTargetsInRange(): { Model } local myChar = localPlayer.Character if not myChar then return {} end local myRoot = myChar:FindFirstChild("HumanoidRootPart") if not myRoot then return {} end local targets = {} -- NPCs for _, model in ipairs(workspace:GetDescendants()) do if model:IsA("Model") and model ~= myChar and model:FindFirstChildOfClass("Humanoid") then local rootPart = model:FindFirstChild("HumanoidRootPart") if rootPart then local dist = (myRoot.Position - rootPart.Position).Magnitude if dist <= MAX_TARGET_RANGE then local humanoid = model:FindFirstChildOfClass("Humanoid") if humanoid and humanoid.Health > 0 then table.insert(targets, model) end end end end end -- Sort by distance table.sort(targets, function(a, b) local aRoot = a:FindFirstChild("HumanoidRootPart") local bRoot = b:FindFirstChild("HumanoidRootPart") if not aRoot or not bRoot then return false end return (myRoot.Position - aRoot.Position).Magnitude < (myRoot.Position - bRoot.Position).Magnitude end) return targets end function TargetController:_createTargetIndicator(model: Model) local head = model:FindFirstChild("Head") local rootPart = model:FindFirstChild("HumanoidRootPart") local attachTo = head or rootPart if not attachTo then return end local billboard = Instance.new("BillboardGui") billboard.Name = "TargetIndicator" billboard.Size = UDim2.new(3, 0, 1.5, 0) billboard.StudsOffset = Vector3.new(0, 4, 0) billboard.AlwaysOnTop = true billboard.Parent = attachTo -- Diamond/arrow indicator local arrow = Instance.new("TextLabel") arrow.Size = UDim2.new(1, 0, 0.5, 0) arrow.Position = UDim2.new(0, 0, 0, 0) arrow.BackgroundTransparency = 1 arrow.Text = "V" arrow.TextColor3 = Color3.fromRGB(255, 50, 50) arrow.TextSize = 30 arrow.Font = Enum.Font.GothamBold arrow.TextStrokeTransparency = 0 arrow.TextStrokeColor3 = Color3.new(0, 0, 0) arrow.Parent = billboard -- Name local name = Instance.new("TextLabel") name.Size = UDim2.new(1, 0, 0.35, 0) name.Position = UDim2.new(0, 0, 0.45, 0) name.BackgroundTransparency = 1 name.Text = "[ " .. model.Name .. " ]" name.TextColor3 = Color3.fromRGB(255, 80, 80) name.TextSize = 16 name.Font = Enum.Font.GothamBold name.TextStrokeTransparency = 0 name.TextStrokeColor3 = Color3.new(0, 0, 0) name.Parent = billboard -- Health info local humanoid = model:FindFirstChildOfClass("Humanoid") if humanoid then local hpLabel = Instance.new("TextLabel") hpLabel.Size = UDim2.new(1, 0, 0.2, 0) hpLabel.Position = UDim2.new(0, 0, 0.75, 0) hpLabel.BackgroundTransparency = 1 hpLabel.Text = math.floor(humanoid.Health) .. " / " .. math.floor(humanoid.MaxHealth) hpLabel.TextColor3 = Color3.fromRGB(255, 150, 150) hpLabel.TextSize = 12 hpLabel.Font = Enum.Font.Gotham hpLabel.TextStrokeTransparency = 0 hpLabel.TextStrokeColor3 = Color3.new(0, 0, 0) hpLabel.Name = "HPLabel" hpLabel.Parent = billboard end -- Pulsing animation task.spawn(function() while billboard.Parent do TweenService:Create(arrow, TweenInfo.new(0.5, Enum.EasingStyle.Sine, Enum.EasingDirection.InOut), { TextColor3 = Color3.fromRGB(255, 100, 100), }):Play() task.wait(0.5) TweenService:Create(arrow, TweenInfo.new(0.5, Enum.EasingStyle.Sine, Enum.EasingDirection.InOut), { TextColor3 = Color3.fromRGB(255, 50, 50), }):Play() task.wait(0.5) end end) targetIndicator = billboard end function TargetController:_updateTargetIndicator() if not currentTarget or not targetIndicator then return end -- Update HP local humanoid = currentTarget:FindFirstChildOfClass("Humanoid") if humanoid then local hpLabel = targetIndicator:FindFirstChild("HPLabel") if hpLabel then hpLabel.Text = math.floor(humanoid.Health) .. " / " .. math.floor(humanoid.MaxHealth) end end end function TargetController:_updateNearbyIndicators() local myChar = localPlayer.Character if not myChar then return end local myRoot = myChar:FindFirstChild("HumanoidRootPart") if not myRoot then return end -- Find nearby targetable models local nearby = {} for _, model in ipairs(workspace:GetDescendants()) do if model:IsA("Model") and model ~= myChar and model:FindFirstChildOfClass("Humanoid") then local rootPart = model:FindFirstChild("HumanoidRootPart") if rootPart then local dist = (myRoot.Position - rootPart.Position).Magnitude if dist <= NEARBY_RANGE then local humanoid = model:FindFirstChildOfClass("Humanoid") if humanoid and humanoid.Health > 0 then nearby[model] = true -- Add subtle indicator if not already targeted if model ~= currentTarget and not nearbyIndicators[model] then local head = model:FindFirstChild("Head") or rootPart local bb = Instance.new("BillboardGui") bb.Name = "NearbyIndicator" bb.Size = UDim2.new(1, 0, 0.5, 0) bb.StudsOffset = Vector3.new(0, 3.5, 0) bb.AlwaysOnTop = false bb.Parent = head local dot = Instance.new("TextLabel") dot.Size = UDim2.fromScale(1, 1) dot.BackgroundTransparency = 1 dot.Text = "o" dot.TextColor3 = Color3.fromRGB(200, 200, 200) dot.TextTransparency = 0.4 dot.TextSize = 18 dot.Font = Enum.Font.GothamBold dot.Parent = bb nearbyIndicators[model] = bb end end end end end end -- Remove indicators for models that are no longer nearby for model, bb in pairs(nearbyIndicators) do if not nearby[model] or model == currentTarget then bb:Destroy() nearbyIndicators[model] = nil end end end function TargetController:_faceTarget() if not currentTarget then return end local myChar = localPlayer.Character if not myChar then return end local myRoot = myChar:FindFirstChild("HumanoidRootPart") local targetRoot = currentTarget:FindFirstChild("HumanoidRootPart") if not myRoot or not targetRoot then return end -- Smoothly rotate character to face target local direction = (targetRoot.Position - myRoot.Position) direction = Vector3.new(direction.X, 0, direction.Z) -- Keep level if direction.Magnitude > 0.1 then local targetCFrame = CFrame.lookAt(myRoot.Position, myRoot.Position + direction) myRoot.CFrame = myRoot.CFrame:Lerp(targetCFrame, 0.1) end end return TargetController ]]> TransformationController UIController 0.6 then return Color3.fromRGB(50, 220, 80) -- Green elseif percent > 0.35 then return Color3.fromRGB(255, 200, 50) -- Yellow elseif percent > 0.15 then return Color3.fromRGB(255, 130, 30) -- Orange else return Color3.fromRGB(255, 50, 50) -- Red end end function UIController:KnitInit() end function UIController:KnitStart() local DataService = Knit.GetService("DataService") DataService.PlayerDataUpdate:Connect(function(data) self:_refreshHUD(data) end) self:_createHUD() DataService:RequestPlayerData():andThen(function(data) if data and not data.CharacterCreated then -- IntroController handles intro -> character creation end end) end -- ========================================== -- HUD CREATION -- ========================================== function UIController:_createHUD() local gui = Instance.new("ScreenGui") gui.Name = "GameHUD" gui.ResetOnSpawn = false gui.DisplayOrder = 5 gui.Parent = playerGui hudElements.gui = gui -- ========== PLAYER STATUS (Top-Left) ========== local playerFrame = makeFrame({ Name = "PlayerStatus", Size = UDim2.new(0, 320, 0, 95), Position = UDim2.new(0, 15, 0, 15), Color = Color3.fromRGB(15, 15, 25), Transparency = 0.15, Corner = 10, Parent = gui, }) -- Glow border local playerStroke = Instance.new("UIStroke") playerStroke.Color = Color3.fromRGB(80, 80, 120) playerStroke.Thickness = 1.5 playerStroke.Transparency = 0.3 playerStroke.Parent = playerFrame -- Portrait circle local portrait = makeFrame({ Name = "Portrait", Size = UDim2.new(0, 50, 0, 50), Position = UDim2.new(0, 8, 0, 8), Color = Color3.fromRGB(40, 40, 60), Corner = 25, Parent = playerFrame, }) local portraitStroke = Instance.new("UIStroke") portraitStroke.Color = Color3.fromRGB(255, 215, 0) portraitStroke.Thickness = 2 portraitStroke.Parent = portrait local raceIcon = makeLabel({ Name = "RaceIcon", Text = "S", Size = UDim2.fromScale(1, 1), TextSize = 24, Color = Color3.fromRGB(255, 215, 0), Align = Enum.TextXAlignment.Center, Parent = portrait, }) hudElements.raceIcon = raceIcon -- Level + Name local nameLabel = makeLabel({ Name = "PlayerName", Text = "Lv.1 " .. localPlayer.Name, Size = UDim2.new(0, 200, 0, 18), Position = UDim2.new(0, 65, 0, 5), TextSize = 14, Color = Color3.new(1, 1, 1), Stroke = 0, Parent = playerFrame, }) hudElements.nameLabel = nameLabel -- Transformation label local formLabel = makeLabel({ Name = "FormLabel", Text = "Base Form", Size = UDim2.new(0, 150, 0, 14), Position = UDim2.new(0, 65, 0, 22), TextSize = 11, Color = Color3.fromRGB(180, 180, 220), Parent = playerFrame, }) hudElements.formLabel = formLabel -- HP Bar local hpBg = makeFrame({ Name = "HpBg", Size = UDim2.new(0, 240, 0, 16), Position = UDim2.new(0, 65, 0, 40), Color = Color3.fromRGB(25, 25, 35), Corner = 4, Parent = playerFrame, }) Instance.new("UIStroke", hpBg).Color = Color3.fromRGB(60, 60, 80) -- HP damage flash layer (shows red briefly when hit) local hpDamageBar = makeFrame({ Name = "HpDamage", Size = UDim2.fromScale(1, 1), Color = Color3.fromRGB(200, 50, 50), Corner = 4, Parent = hpBg, }) hudElements.hpDamageBar = hpDamageBar -- HP actual bar local hpBar = makeFrame({ Name = "HpBar", Size = UDim2.fromScale(1, 1), Color = Color3.fromRGB(50, 220, 80), Corner = 4, Parent = hpBg, }) -- Gradient on HP bar local hpGradient = Instance.new("UIGradient") hpGradient.Color = ColorSequence.new({ ColorSequenceKeypoint.new(0, Color3.fromRGB(80, 255, 100)), ColorSequenceKeypoint.new(1, Color3.fromRGB(40, 200, 60)), }) hpGradient.Parent = hpBar hudElements.hpBar = hpBar hudElements.hpGradient = hpGradient local hpText = makeLabel({ Name = "HpText", Text = "100 / 100", Size = UDim2.fromScale(1, 1), TextSize = 11, Color = Color3.new(1, 1, 1), Align = Enum.TextXAlignment.Center, Stroke = 0, Parent = hpBg, }) hpText.ZIndex = 5 hudElements.hpText = hpText -- HP label makeLabel({ Name = "HpLabel", Text = "HP", Size = UDim2.new(0, 20, 0, 16), Position = UDim2.new(0, 65 - 22, 0, 40), TextSize = 10, Color = Color3.fromRGB(255, 100, 100), Align = Enum.TextXAlignment.Center, Parent = playerFrame, }) -- Ki Bar (segmented style like FighterZ) local kiBg = makeFrame({ Name = "KiBg", Size = UDim2.new(0, 240, 0, 12), Position = UDim2.new(0, 65, 0, 60), Color = Color3.fromRGB(20, 20, 35), Corner = 3, Parent = playerFrame, }) Instance.new("UIStroke", kiBg).Color = Color3.fromRGB(40, 60, 100) local kiBar = makeFrame({ Name = "KiBar", Size = UDim2.fromScale(1, 1), Color = Color3.fromRGB(60, 150, 255), Corner = 3, Parent = kiBg, }) local kiGradient = Instance.new("UIGradient") kiGradient.Color = ColorSequence.new({ ColorSequenceKeypoint.new(0, Color3.fromRGB(100, 200, 255)), ColorSequenceKeypoint.new(1, Color3.fromRGB(40, 120, 255)), }) kiGradient.Parent = kiBar hudElements.kiBar = kiBar -- Ki segment lines (7 segments like FighterZ) for seg = 1, 6 do local line = makeFrame({ Name = "KiSeg_" .. seg, Size = UDim2.new(0, 1, 1, 0), Position = UDim2.new(seg / 7, 0, 0, 0), Color = Color3.fromRGB(15, 15, 25), Transparency = 0.3, Parent = kiBg, }) line.ZIndex = 4 end makeLabel({ Name = "KiLabel", Text = "KI", Size = UDim2.new(0, 20, 0, 12), Position = UDim2.new(0, 65 - 22, 0, 60), TextSize = 9, Color = Color3.fromRGB(100, 180, 255), Align = Enum.TextXAlignment.Center, Parent = playerFrame, }) -- Stamina Bar (thin) local staBg = makeFrame({ Name = "StaBg", Size = UDim2.new(0, 240, 0, 6), Position = UDim2.new(0, 65, 0, 76), Color = Color3.fromRGB(20, 25, 20), Corner = 2, Parent = playerFrame, }) local staBar = makeFrame({ Name = "StaBar", Size = UDim2.fromScale(1, 1), Color = Color3.fromRGB(80, 230, 80), Corner = 2, Parent = staBg, }) hudElements.staBar = staBar -- Stamina cost markers (each vanish costs 25 stamina out of ~100) for marker = 1, 3 do makeFrame({ Name = "StaMarker_" .. marker, Size = UDim2.new(0, 1, 1, 2), Position = UDim2.new(marker * 0.25, 0, 0, -1), Color = Color3.fromRGB(255, 255, 255), Transparency = 0.5, Parent = staBg, }).ZIndex = 4 end makeLabel({ Name = "StaLabel", Text = "ST", Size = UDim2.new(0, 20, 0, 6), Position = UDim2.new(0, 65 - 22, 0, 76), TextSize = 8, Color = Color3.fromRGB(80, 200, 80), Align = Enum.TextXAlignment.Center, Parent = playerFrame, }) -- ========== TARGET FRAME (Top-Right, mirrors player) ========== local targetFrame = makeFrame({ Name = "TargetFrame", Size = UDim2.new(0, 280, 0, 65), Position = UDim2.new(1, -295, 0, 15), Color = Color3.fromRGB(15, 15, 25), Transparency = 0.15, Corner = 10, Parent = gui, }) targetFrame.Visible = false hudElements.targetFrame = targetFrame local targetStroke = Instance.new("UIStroke") targetStroke.Color = Color3.fromRGB(200, 60, 60) targetStroke.Thickness = 1.5 targetStroke.Transparency = 0.3 targetStroke.Parent = targetFrame local targetName = makeLabel({ Name = "TargetName", Text = "Target", Size = UDim2.new(1, -15, 0, 18), Position = UDim2.new(0, 10, 0, 5), TextSize = 14, Color = Color3.fromRGB(255, 100, 100), Stroke = 0, Parent = targetFrame, }) hudElements.targetName = targetName local targetHpBg = makeFrame({ Name = "TargetHpBg", Size = UDim2.new(0, 250, 0, 14), Position = UDim2.new(0, 10, 0, 28), Color = Color3.fromRGB(25, 25, 35), Corner = 4, Parent = targetFrame, }) Instance.new("UIStroke", targetHpBg).Color = Color3.fromRGB(80, 40, 40) local targetHpBar = makeFrame({ Name = "TargetHpBar", Size = UDim2.fromScale(1, 1), Color = Color3.fromRGB(220, 50, 50), Corner = 4, Parent = targetHpBg, }) hudElements.targetHpBar = targetHpBar local targetHpText = makeLabel({ Name = "TargetHpText", Text = "", Size = UDim2.fromScale(1, 1), TextSize = 10, Align = Enum.TextXAlignment.Center, Stroke = 0, Parent = targetHpBg, }) targetHpText.ZIndex = 5 hudElements.targetHpText = targetHpText local targetLevelLabel = makeLabel({ Name = "TargetLevel", Text = "", Size = UDim2.new(0, 100, 0, 14), Position = UDim2.new(0, 10, 0, 46), TextSize = 11, Color = Color3.fromRGB(180, 180, 200), Parent = targetFrame, }) hudElements.targetLevelLabel = targetLevelLabel -- ========== MOVE BUBBLES (Bottom-Center) ========== -- Single container with skill bubbles. Basic controls shown inside each bubble's tooltip. local SLOT_COLORS = { Color3.fromRGB(50, 50, 100), Color3.fromRGB(50, 50, 100), Color3.fromRGB(50, 50, 100), Color3.fromRGB(50, 50, 100), Color3.fromRGB(100, 40, 40), Color3.fromRGB(40, 100, 50), } local SLOT_KEYS = { "[Z]", "[X]", "[V]", "[B]", "[N] ULT", "[G] EVD" } local SLOT_BORDER_COLORS = { Color3.fromRGB(100, 100, 220), Color3.fromRGB(100, 100, 220), Color3.fromRGB(100, 100, 220), Color3.fromRGB(100, 100, 220), Color3.fromRGB(255, 80, 80), Color3.fromRGB(80, 220, 100), } -- Master container — holds controls hint row + bubble row local bottomContainer = makeFrame({ Name = "BottomContainer", Size = UDim2.new(0, 620, 0, 120), Position = UDim2.new(0.5, -310, 1, -128), Transparency = 1, Parent = gui, }) -- Controls hint row (compact, above the bubbles) local controlsHint = makeFrame({ Name = "ControlsHint", Size = UDim2.new(1, 0, 0, 22), Position = UDim2.new(0, 0, 0, 0), Color = Color3.fromRGB(15, 15, 25), Transparency = 0.3, Corner = 6, Parent = bottomContainer, }) local controlsText = makeLabel({ Name = "ControlsText", Text = "M1 Light | M2 Heavy | E Ki Blast | R Charged | F Block | Q Vanish | C Charge Ki | T Transform | Tab Lock-On | Z X V B Skills | N Ult | G Evade", Size = UDim2.fromScale(1, 1), TextSize = 10, Color = Color3.fromRGB(160, 160, 190), Align = Enum.TextXAlignment.Center, Font = Enum.Font.Gotham, Parent = controlsHint, }) -- Bubble row local bubbleBar = makeFrame({ Name = "BubbleBar", Size = UDim2.new(1, 0, 0, 90), Position = UDim2.new(0, 0, 0, 28), Transparency = 1, Parent = bottomContainer, }) local bubbleLayout = Instance.new("UIListLayout") bubbleLayout.FillDirection = Enum.FillDirection.Horizontal bubbleLayout.HorizontalAlignment = Enum.HorizontalAlignment.Center bubbleLayout.VerticalAlignment = Enum.VerticalAlignment.Center bubbleLayout.Padding = UDim.new(0, 10) bubbleLayout.Parent = bubbleBar hudElements.skillSlots = {} -- Skill move bubbles (the 6 loadout slots) for i = 1, 6 do local bubble = makeFrame({ Name = "SkillBubble_" .. i, Size = UDim2.new(0, 85, 0, 85), Color = SLOT_COLORS[i], Transparency = 0.15, Corner = 42, Parent = bubbleBar, }) -- Glowing border local stroke = Instance.new("UIStroke") stroke.Color = SLOT_BORDER_COLORS[i] stroke.Thickness = 2.5 stroke.Transparency = 0.2 stroke.Parent = bubble -- Key binding label (top) makeLabel({ Name = "KeyBind", Text = SLOT_KEYS[i], Size = UDim2.new(1, 0, 0, 14), Position = UDim2.new(0, 0, 0, 6), TextSize = 10, Color = SLOT_BORDER_COLORS[i], Align = Enum.TextXAlignment.Center, Font = Enum.Font.GothamBold, Parent = bubble, }) -- Move name (center, big) local moveName = makeLabel({ Name = "MoveName", Text = "Empty", Size = UDim2.new(1, -8, 0, 28), Position = UDim2.new(0, 4, 0, 20), TextSize = 11, Color = Color3.new(1, 1, 1), Align = Enum.TextXAlignment.Center, Font = Enum.Font.GothamBold, Parent = bubble, }) moveName.TextWrapped = true -- Ki cost (bottom) local kiCost = makeLabel({ Name = "KiCost", Text = "", Size = UDim2.new(1, 0, 0, 12), Position = UDim2.new(0, 0, 0, 50), TextSize = 9, Color = Color3.fromRGB(100, 180, 255), Align = Enum.TextXAlignment.Center, Font = Enum.Font.Gotham, Parent = bubble, }) -- Cooldown label (bottom) local cdLabel = makeLabel({ Name = "CooldownLabel", Text = "", Size = UDim2.new(1, 0, 0, 10), Position = UDim2.new(0, 0, 0, 62), TextSize = 8, Color = Color3.fromRGB(180, 150, 100), Align = Enum.TextXAlignment.Center, Font = Enum.Font.Gotham, Parent = bubble, }) -- Cooldown dark overlay (sweeps down from top when on cooldown) local cooldownOverlay = makeFrame({ Name = "CooldownOverlay", Size = UDim2.fromScale(1, 0), Color = Color3.new(0, 0, 0), Transparency = 0.4, Corner = 42, Parent = bubble, }) -- Tooltip on hover (shows description) local tooltip = makeFrame({ Name = "Tooltip", Size = UDim2.new(0, 180, 0, 60), Position = UDim2.new(0.5, -90, 0, -68), Color = Color3.fromRGB(15, 15, 30), Transparency = 0.05, Corner = 8, Parent = bubble, }) tooltip.Visible = false tooltip.ZIndex = 10 local tooltipStroke = Instance.new("UIStroke") tooltipStroke.Color = SLOT_BORDER_COLORS[i] tooltipStroke.Thickness = 1 tooltipStroke.Parent = tooltip local tooltipTitle = makeLabel({ Name = "TooltipTitle", Text = "", Size = UDim2.new(1, -10, 0, 16), Position = UDim2.new(0, 5, 0, 3), TextSize = 12, Color = Color3.new(1, 1, 1), Font = Enum.Font.GothamBold, Parent = tooltip, }) tooltipTitle.ZIndex = 11 local tooltipDesc = makeLabel({ Name = "TooltipDesc", Text = "", Size = UDim2.new(1, -10, 0, 36), Position = UDim2.new(0, 5, 0, 20), TextSize = 10, Color = Color3.fromRGB(180, 180, 200), Font = Enum.Font.Gotham, Parent = tooltip, }) tooltipDesc.TextWrapped = true tooltipDesc.ZIndex = 11 -- Hover detection via invisible button local hoverBtn = Instance.new("TextButton") hoverBtn.Size = UDim2.fromScale(1, 1) hoverBtn.BackgroundTransparency = 1 hoverBtn.Text = "" hoverBtn.ZIndex = 6 hoverBtn.Parent = bubble hoverBtn.MouseEnter:Connect(function() tooltip.Visible = true TweenService:Create(stroke, TweenInfo.new(0.15), { Color = Color3.new(1, 1, 1) }):Play() TweenService:Create(bubble, TweenInfo.new(0.15), { Size = UDim2.new(0, 90, 0, 90) }):Play() end) hoverBtn.MouseLeave:Connect(function() tooltip.Visible = false TweenService:Create(stroke, TweenInfo.new(0.15), { Color = SLOT_BORDER_COLORS[i] }):Play() TweenService:Create(bubble, TweenInfo.new(0.15), { Size = UDim2.new(0, 85, 0, 85) }):Play() end) hudElements.skillSlots[i] = { slot = bubble, moveName = moveName, kiCost = kiCost, cdLabel = cdLabel, cooldown = cooldownOverlay, tooltipTitle = tooltipTitle, tooltipDesc = tooltipDesc, stroke = stroke, } end -- ========== COMBO COUNTER (Right side) ========== local comboFrame = makeFrame({ Name = "ComboFrame", Size = UDim2.new(0, 150, 0, 70), Position = UDim2.new(1, -170, 0.4, 0), Transparency = 1, Parent = gui, }) comboFrame.Visible = false hudElements.comboFrame = comboFrame local comboCount = makeLabel({ Name = "ComboCount", Text = "0", Size = UDim2.new(1, 0, 0, 45), TextSize = 42, Color = Color3.fromRGB(255, 200, 50), Align = Enum.TextXAlignment.Right, Stroke = 0, Parent = comboFrame, }) hudElements.comboCount = comboCount local comboLabel = makeLabel({ Name = "ComboLabel", Text = "HITS", Size = UDim2.new(1, 0, 0, 18), Position = UDim2.new(0, 0, 0, 42), TextSize = 14, Color = Color3.fromRGB(255, 180, 50), Align = Enum.TextXAlignment.Right, Stroke = 0, Parent = comboFrame, }) local comboDamage = makeLabel({ Name = "ComboDamage", Text = "0 DMG", Size = UDim2.new(1, 0, 0, 14), Position = UDim2.new(0, 0, 0, 58), TextSize = 11, Color = Color3.fromRGB(200, 150, 50), Align = Enum.TextXAlignment.Right, Parent = comboFrame, }) hudElements.comboDamage = comboDamage -- ========== POWER LEVEL (Below player frame) ========== local powerLabel = makeLabel({ Name = "PowerLevel", Text = "Power Level: 0", Size = UDim2.new(0, 200, 0, 16), Position = UDim2.new(0, 15, 0, 115), TextSize = 12, Color = Color3.fromRGB(200, 200, 220), Parent = gui, }) hudElements.powerLabel = powerLabel -- ========== XP BAR (Bottom) ========== local xpBg = makeFrame({ Name = "XpBg", Size = UDim2.new(0.5, 0, 0, 6), Position = UDim2.new(0.25, 0, 1, -8), Color = Color3.fromRGB(20, 20, 30), Corner = 3, Parent = gui, }) local xpBar = makeFrame({ Name = "XpBar", Size = UDim2.fromScale(0, 1), Color = Color3.fromRGB(255, 255, 80), Corner = 3, Parent = xpBg, }) local xpGrad = Instance.new("UIGradient") xpGrad.Color = ColorSequence.new({ ColorSequenceKeypoint.new(0, Color3.fromRGB(255, 255, 120)), ColorSequenceKeypoint.new(1, Color3.fromRGB(200, 200, 50)), }) xpGrad.Parent = xpBar hudElements.xpBar = xpBar local xpText = makeLabel({ Name = "XpText", Text = "Lv.1 — 0 / 100 XP", Size = UDim2.new(1, 0, 0, 18), Position = UDim2.new(0, 0, 0, -16), TextSize = 10, Color = Color3.fromRGB(200, 200, 180), Align = Enum.TextXAlignment.Center, Parent = xpBg, }) hudElements.xpText = xpText -- ========== ZENI (Top-right corner) ========== local zeniLabel = makeLabel({ Name = "Zeni", Text = "0 Zeni", Size = UDim2.new(0, 120, 0, 20), Position = UDim2.new(1, -135, 0, 85), TextSize = 14, Color = Color3.fromRGB(255, 215, 0), Align = Enum.TextXAlignment.Right, Stroke = 0, Parent = gui, }) hudElements.zeniLabel = zeniLabel -- ========== LEVEL UP POPUP ========== local levelUpPopup = makeLabel({ Name = "LevelUp", Text = "LEVEL UP!", Size = UDim2.new(0, 300, 0, 50), Position = UDim2.new(0.5, -150, 0.3, 0), TextSize = 36, Color = Color3.fromRGB(255, 255, 50), Align = Enum.TextXAlignment.Center, Stroke = 0, Parent = gui, }) levelUpPopup.TextTransparency = 1 hudElements.levelUpPopup = levelUpPopup -- ========== TARGET FRAME UPDATE LOOP ========== RunService.RenderStepped:Connect(function() self:_updateTargetFrame() end) end -- ========================================== -- HUD UPDATES -- ========================================== function UIController:_refreshHUD(data: any) if not hudElements.gui then return end -- Name + Level if hudElements.nameLabel then hudElements.nameLabel.Text = "Lv." .. data.Level .. " " .. localPlayer.Name end -- Race icon if hudElements.raceIcon then local raceLetters = { Saiyan = "S", Namekian = "N", FriezaRace = "F", Majin = "M", Android = "A", Human = "H" } hudElements.raceIcon.Text = raceLetters[data.Race] or "?" end -- Transformation label if hudElements.formLabel then local formText = data.CurrentTransformation == "Base" and "Base Form" or data.CurrentTransformation hudElements.formLabel.Text = formText -- Update portrait border color to match transformation aura local Transformations = require(ReplicatedStorage.Shared.Constants.Transformations) local form = Transformations:Get(data.CurrentTransformation) local portrait = hudElements.gui:FindFirstChild("PlayerStatus") and hudElements.gui.PlayerStatus:FindFirstChild("Portrait") if portrait then local stroke = portrait:FindFirstChildOfClass("UIStroke") if stroke then stroke.Color = form and form.auraColor or Color3.fromRGB(255, 215, 0) end end end -- Zeni if hudElements.zeniLabel then hudElements.zeniLabel.Text = tostring(data.Zeni) .. " Zeni" end -- XP local Stats = require(ReplicatedStorage.Shared.Constants.Stats) local required = Stats:GetRequiredXP(data.Level) local xpPercent = if required > 0 then data.XP / required else 0 if hudElements.xpBar then TweenService:Create(hudElements.xpBar, TweenInfo.new(0.3), { Size = UDim2.fromScale(math.clamp(xpPercent, 0, 1), 1), }):Play() end if hudElements.xpText then hudElements.xpText.Text = "Lv." .. data.Level .. " — " .. data.XP .. " / " .. required .. " XP" end -- Power Level (sum of all effective stats) if hudElements.powerLabel then local power = 0 for _, v in pairs(data.Stats) do power = power + v end power = power * data.Level hudElements.powerLabel.Text = "Power Level: " .. tostring(math.floor(power)) end -- Skill loadout bubbles — populate with full move info if hudElements.skillSlots and data.MoveLoadout then local Moves = require(ReplicatedStorage.Shared.Constants.Moves) for i = 1, 6 do local slot = hudElements.skillSlots[i] if not slot then continue end local moveId = data.MoveLoadout[i] if moveId then local move = Moves:Get(moveId) if move then slot.moveName.Text = move.displayName -- Ki cost local ki = move.kiCost or move.kiCostBase or 0 slot.kiCost.Text = ki > 0 and (ki .. " Ki") or "Free" -- Cooldown local cd = move.cooldown or 0 slot.cdLabel.Text = cd > 0 and (cd .. "s CD") or "" -- Tooltip slot.tooltipTitle.Text = move.displayName .. " [" .. move.category .. "]" slot.tooltipDesc.Text = move.description or "" -- Style active slot.moveName.TextColor3 = Color3.new(1, 1, 1) else slot.moveName.Text = moveId slot.kiCost.Text = "" slot.cdLabel.Text = "" slot.tooltipTitle.Text = moveId slot.tooltipDesc.Text = "" end else slot.moveName.Text = "Empty" slot.moveName.TextColor3 = Color3.fromRGB(80, 80, 100) slot.kiCost.Text = "" slot.cdLabel.Text = "" slot.tooltipTitle.Text = "No move equipped" slot.tooltipDesc.Text = "Open Move Loadout (K) to equip a move to this slot." end end end end function UIController:UpdateHealthBar(current: number, max: number) if not hudElements.hpBar then return end local percent = if max > 0 then current / max else 0 percent = math.clamp(percent, 0, 1) -- Damage flash: show red bar at old position, then tween down if percent < lastHpPercent and hudElements.hpDamageBar then hudElements.hpDamageBar.Size = UDim2.fromScale(lastHpPercent, 1) TweenService:Create(hudElements.hpDamageBar, TweenInfo.new(0.6, Enum.EasingStyle.Quad, Enum.EasingDirection.Out, 0, false, 0.2), { Size = UDim2.fromScale(percent, 1), }):Play() end -- Smooth HP bar tween TweenService:Create(hudElements.hpBar, TweenInfo.new(0.2), { Size = UDim2.fromScale(percent, 1), }):Play() -- Color change based on HP local color = getHpColor(percent) if hudElements.hpGradient then local bright = Color3.new( math.min(1, color.R * 1.3), math.min(1, color.G * 1.3), math.min(1, color.B * 1.3) ) hudElements.hpGradient.Color = ColorSequence.new({ ColorSequenceKeypoint.new(0, bright), ColorSequenceKeypoint.new(1, color) }) end -- HP text if hudElements.hpText then hudElements.hpText.Text = math.floor(current) .. " / " .. math.floor(max) end -- Low HP warning pulse if percent <= 0.2 and hudElements.hpBar then TweenService:Create(hudElements.hpBar, TweenInfo.new(0.3, Enum.EasingStyle.Sine, Enum.EasingDirection.InOut, 0, true), { BackgroundTransparency = 0.4, }):Play() end lastHpPercent = percent end function UIController:UpdateKiBar(current: number, max: number) if not hudElements.kiBar then return end local percent = if max > 0 then current / max else 0 TweenService:Create(hudElements.kiBar, TweenInfo.new(0.15), { Size = UDim2.fromScale(math.clamp(percent, 0, 1), 1), }):Play() end function UIController:UpdateStaminaBar(current: number, max: number) if not hudElements.staBar then return end local percent = if max > 0 then current / max else 0 TweenService:Create(hudElements.staBar, TweenInfo.new(0.15), { Size = UDim2.fromScale(math.clamp(percent, 0, 1), 1), }):Play() end -- ========================================== -- TARGET FRAME (updates every frame) -- ========================================== function UIController:_updateTargetFrame() local TargetController = Knit.GetController("TargetController") if not TargetController then return end local targetModel = TargetController:GetTarget() if not targetModel then if hudElements.targetFrame then hudElements.targetFrame.Visible = false end return end if hudElements.targetFrame then hudElements.targetFrame.Visible = true end -- Name if hudElements.targetName then hudElements.targetName.Text = targetModel.Name end -- HP local humanoid = targetModel:FindFirstChildOfClass("Humanoid") if humanoid and hudElements.targetHpBar then local percent = if humanoid.MaxHealth > 0 then humanoid.Health / humanoid.MaxHealth else 0 hudElements.targetHpBar.Size = UDim2.fromScale(math.clamp(percent, 0, 1), 1) hudElements.targetHpBar.BackgroundColor3 = getHpColor(percent) if hudElements.targetHpText then hudElements.targetHpText.Text = math.floor(humanoid.Health) .. " / " .. math.floor(humanoid.MaxHealth) end end end -- ========================================== -- COMBO COUNTER -- ========================================== function UIController:ShowComboCounter(hits: number, totalDamage: number) if not hudElements.comboFrame then return end hudElements.comboFrame.Visible = true if hudElements.comboCount then hudElements.comboCount.Text = tostring(hits) -- Pop animation hudElements.comboCount.TextSize = 25 TweenService:Create(hudElements.comboCount, TweenInfo.new(0.15, Enum.EasingStyle.Back, Enum.EasingDirection.Out), { TextSize = 42, }):Play() end if hudElements.comboDamage then hudElements.comboDamage.Text = tostring(math.floor(totalDamage)) .. " DMG" end -- Auto-hide after 2 seconds of no updates if comboCounterVisible then return end comboCounterVisible = true task.spawn(function() local lastHits = hits while true do task.wait(2) if hudElements.comboCount and tonumber(hudElements.comboCount.Text) == lastHits then -- No new hits — fade out if hudElements.comboFrame then hudElements.comboFrame.Visible = false end comboCounterVisible = false return end lastHits = tonumber(hudElements.comboCount.Text) or 0 end end) end -- ========================================== -- LEVEL UP POPUP -- ========================================== function UIController:ShowLevelUp(newLevel: number) local popup = hudElements.levelUpPopup if not popup then return end popup.Text = "LEVEL UP! Lv." .. newLevel popup.TextTransparency = 0 popup.TextSize = 20 TweenService:Create(popup, TweenInfo.new(0.3, Enum.EasingStyle.Back, Enum.EasingDirection.Out), { TextSize = 40, }):Play() task.delay(2, function() TweenService:Create(popup, TweenInfo.new(0.5), { TextTransparency = 1, }):Play() end) end -- ========================================== -- MENUS -- ========================================== function UIController:_showCharacterCreation() local CharacterCreation = require(script.Parent.Parent.UI.Menus.CharacterCreation) CharacterCreation.Show() end function UIController:SetMenuVisible(menuName: string, visible: boolean) menuVisibility[menuName] = visible if menuName == "TransformationWheel" then local TransformationWheel = require(script.Parent.Parent.UI.Menus.TransformationWheel) if visible then local DataService = Knit.GetService("DataService") DataService:RequestPlayerData():andThen(function(data) if data then TransformationWheel.Show(data.UnlockedTransformations, data.CurrentTransformation, data.Race) end end) else TransformationWheel.Hide() end elseif menuName == "QuestLog" then local QuestLog = require(script.Parent.Parent.UI.Menus.QuestLog) if visible then local DataService = Knit.GetService("DataService") DataService:RequestPlayerData():andThen(function(data) QuestLog.Show(data) end) else QuestLog.Hide() end elseif menuName == "Shop" then local Shop = require(script.Parent.Parent.UI.Menus.Shop) if visible then local DataService = Knit.GetService("DataService") DataService:RequestPlayerData():andThen(function(data) Shop.Show(data) end) else Shop.Hide() end elseif menuName == "MoveLoadout" then local MoveLoadout = require(script.Parent.Parent.UI.Menus.MoveLoadout) if visible then local DataService = Knit.GetService("DataService") DataService:RequestPlayerData():andThen(function(data) MoveLoadout.Show(data) end) else MoveLoadout.Hide() end elseif menuName == "Settings" then local SettingsMenu = require(script.Parent.Parent.UI.Menus.Settings) if visible then SettingsMenu.Show() else SettingsMenu.Hide() end end end return UIController ]]> VfxController UI Menus CharacterCreation ") end end -- Update stats preview when race changes (polling fallback) task.spawn(function() while gui.Parent do if selectedRace then refreshPreview() end task.wait(0.5) end -- Cleanup preview on close CharacterPreview.Destroy() end) -- Confirm handler confirmBtn.MouseButton1Click:Connect(function() if not selectedRace then errorLabel.Text = "Please select a race!" return end errorLabel.Text = "Creating..." confirmBtn.BackgroundColor3 = Color3.fromRGB(100, 100, 100) local DataService = Knit.GetService("DataService") local success, message = DataService:SubmitCharacterCreation(selectedRace, { SkinColor = selectedSkinColor, HairStyle = selectedHairStyle, HairColor = selectedHairColor, Outfit = "Default", OutfitColor = selectedOutfitColor, }) if success then -- Fade out and destroy TweenService:Create(bg, TweenInfo.new(0.5), { BackgroundTransparency = 1, }):Play() for _, desc in ipairs(gui:GetDescendants()) do if desc:IsA("GuiObject") then TweenService:Create(desc, TweenInfo.new(0.5), { BackgroundTransparency = 1, }):Play() if desc:IsA("TextLabel") or desc:IsA("TextButton") then TweenService:Create(desc, TweenInfo.new(0.5), { TextTransparency = 1, }):Play() end end end task.delay(0.6, function() gui:Destroy() end) else errorLabel.Text = message or "Failed to create character!" confirmBtn.BackgroundColor3 = Color3.fromRGB(50, 180, 50) end end) -- Animate in bg.BackgroundTransparency = 1 TweenService:Create(bg, TweenInfo.new(0.5), { BackgroundTransparency = 0 }):Play() end function CharacterCreation.Hide() local gui = playerGui:FindFirstChild("CharacterCreation") if gui then gui:Destroy() end end return CharacterCreation ]]> CharacterPreview 0 and math.rad(15) or math.rad(-15)) end end if raceConfig.hasHeadTentacle then local tent = makePart(Vector3.new(0.25, 0.25, 1.3), skin, Enum.Material.SmoothPlastic, model) tent.CFrame = head.CFrame * CFrame.new(0, 0.4, -0.4) * CFrame.Angles(math.rad(-55), 0, 0) end -- Floor disc local floor = makePart(Vector3.new(4, 0.1, 4), Color3.fromRGB(40, 40, 60), Enum.Material.SmoothPlastic, model) floor.Shape = Enum.PartType.Cylinder floor.CFrame = CFrame.new(0, 0.95, 0) * CFrame.Angles(0, 0, math.rad(90)) currentModel = model end function CharacterPreview.Destroy() if renderConn then renderConn:Disconnect() renderConn = nil end if currentViewport then currentViewport:Destroy() currentViewport = nil end currentModel = nil currentCamera = nil end return CharacterPreview ]]> MoveLoadout QuestLog = saga.levelRequirement local isCompleted = false if playerData and playerData.CompletedSagas then for _, id in ipairs(playerData.CompletedSagas) do if id == saga.id then isCompleted = true break end end end local sagaFrame = Instance.new("Frame") sagaFrame.Size = UDim2.new(0.95, 0, 0, 90) sagaFrame.BackgroundColor3 = isCompleted and Color3.fromRGB(30, 60, 30) or (isAvailable and Color3.fromRGB(40, 40, 60) or Color3.fromRGB(30, 30, 40)) sagaFrame.BorderSizePixel = 0 sagaFrame.Parent = rightPanel Instance.new("UICorner", sagaFrame).CornerRadius = UDim.new(0, 6) local sTitle = Instance.new("TextLabel") sTitle.Size = UDim2.new(1, -10, 0, 22) sTitle.Position = UDim2.new(0, 5, 0, 3) sTitle.BackgroundTransparency = 1 sTitle.Text = saga.displayName .. (isCompleted and " [COMPLETE]" or "") .. " (Lv." .. saga.levelRequirement .. "+)" sTitle.TextColor3 = isCompleted and Color3.fromRGB(100, 255, 100) or (isAvailable and Color3.new(1, 1, 1) or Color3.fromRGB(120, 120, 120)) sTitle.TextSize = 14 sTitle.Font = Enum.Font.GothamBold sTitle.TextXAlignment = Enum.TextXAlignment.Left sTitle.Parent = sagaFrame local sDesc = Instance.new("TextLabel") sDesc.Size = UDim2.new(1, -15, 0, 35) sDesc.Position = UDim2.new(0, 10, 0, 25) sDesc.BackgroundTransparency = 1 sDesc.Text = saga.description sDesc.TextColor3 = Color3.fromRGB(180, 180, 200) sDesc.TextSize = 11 sDesc.Font = Enum.Font.Gotham sDesc.TextXAlignment = Enum.TextXAlignment.Left sDesc.TextWrapped = true sDesc.Parent = sagaFrame -- Accept first quest button if isAvailable and not isCompleted and #saga.quests > 0 then local acceptBtn = Instance.new("TextButton") acceptBtn.Size = UDim2.new(0, 80, 0, 25) acceptBtn.Position = UDim2.new(1, -90, 1, -30) acceptBtn.BackgroundColor3 = Color3.fromRGB(50, 150, 50) acceptBtn.Text = "START" acceptBtn.TextColor3 = Color3.new(1, 1, 1) acceptBtn.TextSize = 12 acceptBtn.Font = Enum.Font.GothamBold acceptBtn.BorderSizePixel = 0 acceptBtn.Parent = sagaFrame Instance.new("UICorner", acceptBtn).CornerRadius = UDim.new(0, 4) acceptBtn.MouseButton1Click:Connect(function() local QuestController = Knit.GetController("QuestController") QuestController:AcceptQuest(saga.quests[1].id) acceptBtn.Text = "Accepted!" acceptBtn.BackgroundColor3 = Color3.fromRGB(100, 100, 100) end) end end end function QuestLog.Hide() if currentGui then currentGui:Destroy() currentGui = nil end end return QuestLog ]]> Settings Shop = move.zeniCost local meetsLevel = playerData and playerData.Level >= (move.levelRequirement or 0) local card = Instance.new("Frame") card.BackgroundColor3 = owned and Color3.fromRGB(30, 60, 30) or Color3.fromRGB(35, 35, 55) card.BorderSizePixel = 0 card.Parent = scroll Instance.new("UICorner", card).CornerRadius = UDim.new(0, 8) -- Move name local nameLabel = Instance.new("TextLabel") nameLabel.Size = UDim2.new(1, -10, 0, 22) nameLabel.Position = UDim2.new(0, 5, 0, 5) nameLabel.BackgroundTransparency = 1 nameLabel.Text = move.displayName .. " [" .. move.category .. "]" nameLabel.TextColor3 = owned and Color3.fromRGB(100, 255, 100) or Color3.new(1, 1, 1) nameLabel.TextSize = 14 nameLabel.Font = Enum.Font.GothamBold nameLabel.TextXAlignment = Enum.TextXAlignment.Left nameLabel.Parent = card -- Description local descLabel = Instance.new("TextLabel") descLabel.Size = UDim2.new(1, -15, 0, 35) descLabel.Position = UDim2.new(0, 10, 0, 28) descLabel.BackgroundTransparency = 1 descLabel.Text = move.description descLabel.TextColor3 = Color3.fromRGB(180, 180, 200) descLabel.TextSize = 11 descLabel.Font = Enum.Font.Gotham descLabel.TextXAlignment = Enum.TextXAlignment.Left descLabel.TextWrapped = true descLabel.Parent = card -- Stats line local statsText = "Ki: " .. (move.kiCost or 0) .. " | CD: " .. (move.cooldown or 0) .. "s | Lv." .. (move.levelRequirement or 0) local statsLabel = Instance.new("TextLabel") statsLabel.Size = UDim2.new(1, -10, 0, 18) statsLabel.Position = UDim2.new(0, 5, 0, 68) statsLabel.BackgroundTransparency = 1 statsLabel.Text = statsText statsLabel.TextColor3 = Color3.fromRGB(150, 180, 255) statsLabel.TextSize = 11 statsLabel.Font = Enum.Font.Gotham statsLabel.TextXAlignment = Enum.TextXAlignment.Left statsLabel.Parent = card -- Buy/Owned button if owned then local ownedLabel = Instance.new("TextLabel") ownedLabel.Size = UDim2.new(1, -10, 0, 25) ownedLabel.Position = UDim2.new(0, 5, 1, -30) ownedLabel.BackgroundTransparency = 1 ownedLabel.Text = "OWNED" ownedLabel.TextColor3 = Color3.fromRGB(100, 255, 100) ownedLabel.TextSize = 14 ownedLabel.Font = Enum.Font.GothamBold ownedLabel.Parent = card else local buyBtn = Instance.new("TextButton") buyBtn.Size = UDim2.new(0.5, 0, 0, 25) buyBtn.Position = UDim2.new(0.25, 0, 1, -30) buyBtn.Text = move.zeniCost .. " Zeni" buyBtn.TextSize = 12 buyBtn.Font = Enum.Font.GothamBold buyBtn.TextColor3 = Color3.new(1, 1, 1) buyBtn.BorderSizePixel = 0 buyBtn.Parent = card Instance.new("UICorner", buyBtn).CornerRadius = UDim.new(0, 4) if canAfford and meetsLevel then buyBtn.BackgroundColor3 = Color3.fromRGB(50, 150, 50) buyBtn.MouseButton1Click:Connect(function() -- TODO: Call PurchaseItem on server buyBtn.Text = "Purchased!" buyBtn.BackgroundColor3 = Color3.fromRGB(100, 100, 100) end) else buyBtn.BackgroundColor3 = Color3.fromRGB(100, 50, 50) if not meetsLevel then buyBtn.Text = "Lv." .. (move.levelRequirement or 0) .. " Required" end end end end -- Auto-size canvas local totalItems = 0 for _ in pairs(scroll:GetChildren()) do totalItems = totalItems + 1 end local rows = math.ceil((totalItems - 1) / 3) -- subtract UIGridLayout scroll.CanvasSize = UDim2.new(0, 0, 0, rows * 140) end function Shop.Hide() if currentGui then currentGui:Destroy() currentGui = nil end end return Shop ]]> TransformationWheel