{"id":"ffrostfall/jabby-test","name":"jabby-test","scope":"ffrostfall","platform":"roblox","description":"Jecs debugger built with Vide","version":"0.2.0-rc.6","latest":"0.2.0-rc.6","versions":["0.2.0-rc.6"],"license":"MIT","licenseRating":"safe","licenseCaveats":["License identified from the packaged LICENSE file; the manifest declared none."],"licenseVerified":true,"dependencies":{"ukendio/jecs":{"version":"^0.4.0","alias":"jecs"},"alicesaidhi/pebble":{"version":"^0.1.0-rc.9","alias":"pebble"},"osyrisrblx/t":{"version":"^3.1.1","alias":"t"},"centau/vide":{"version":"^0.3.1","alias":"vide"}},"integrity":"9d196bdcdf5c4488880173f50c31d0e4efe008d6534afb5648699173c554a062","likes":0,"downloads":0,"install":"forest install ffrostfall/jabby-test","url":"https://forest.dev/p/roblox/ffrostfall/jabby-test","files":"https://api.forest.dev/ai/package/roblox/ffrostfall/jabby-test/files","readme":"# jabby\r\n\r\njabby is a debugger for [jecs](https://github.com/ukendio/jecs) based off [gorp](https://github.com/aloroid/gorp)\r\n\r\nIt's still in the early stages of development and is very experimental.\r\n\r\n> [!NOTE]\r\n> jabby is compatible with [jecs 0.2.9](https://github.com/Ukendio/jecs/releases/tag/v0.2.9) and up.\r\n> Do not install jecs 0.3.0-rc.1, it is not compatible (for some reason, it's older than 0.2.9??)\r\n\r\n> [!NOTE]\r\n> jabby requires vide with the recursive queue fix patch (git commit [fbe2f01](https://github.com/centau/vide/commit/fbe2f01bb99e7f7744d5039f36c494044f044883))\r\n\r\nWhile jabby is currently only compatible with jecs, the intent is to be able to use this as a alternative debugger for Matter and ECR in the future as well.\r\n\r\n## How to get it working\r\n\r\njabby shouldn't be too intrusive to integrate into any existing or new ecs setups, but there are some notes to be made.\r\nThe current API is very experimental, and not exactly meant for developer use.\r\nI will probably continue supporting this API in the future, until I have came up with a proper scheduler api.\r\n\r\njabby exposes a `public` field which is where you add your Worlds and\r\nSchedulers to that you want to be exposed to the client. After adding a object\r\nto the public field, you must set `public.updated` to `true` so that jabby knows\r\nto broadcast that a new world and scheduler is added.\r\n\r\n### World\r\n\r\nWhen adding a world to jabby, they're expected in the following format:\r\n\r\n```luau\r\ntype world_data = {\r\n\t--- when it reads this, it recognizes the data as a World. required\r\n\tclass_name: \"World\",\r\n\t--- this is the name that will be displayed in the client\r\n\t--- recommendation is to keep it descriptive\r\n\tname: string,\r\n\t--- the actual jecs world that jabby will read from\r\n\tworld: jecs.World,\r\n\t--- a debug component that jabby uses to get all components and their names.\r\n\tdebug: jecs.Entity<string>,\r\n\r\n\t-- the following is optional starting from jabby 0.1.1\r\n\t--- associates a entity with a instance. jabby uses this to find the correct\r\n\t--- entity associated with the given part. this will be removed in 0.2.0\r\n\t--- optional\r\n\tentities: {[Instance]: jecs.Entity<any>},\r\n\t--- this function is user-provided. when provided, jabby will ignore the entities\r\n\t--- field and instead call this function to get the entity. optionally, a instance\r\n\t--- can be provided which will be used as a highlight for the entity\r\n\t--- optional\r\n\tget_entity_from_part: (part: BasePart) -> (jecs.Entity<any>?, Instance?)\r\n}\r\n```\r\n\r\nexample code:\r\n\r\n```lua\r\nlocal world = jecs.World.new()\r\n\r\nlocal debug = world:entity()\r\n\r\ntable.insert(\r\n\tjabby.public,\r\n\t{\r\n\t\tclass_name = \"World\",\r\n\t\tname = \"jecs world\",\r\n\t\tworld = world,\r\n\t\tdebug = debug,\r\n\r\n\t\tentities = {}\r\n\t}\r\n)\r\njabby.public.updated = true\r\n```\r\n\r\n### Scheduler\r\n\r\njabby exposes a scheduler object which is used to report necessary scheduler data to jorp.\r\nYou'll need to instantiate your own scheduler and add it to the public table for jabby to see it.\r\n\r\nAdding it to the public table is as simple as just using `table.insert` on it.\r\nIt's recommended to write your own scheduler, and have it wrap around jabby's scheduler. jabby's scheduler is only meant for reporting data and debugging.\r\n\r\nRegistering a system can be performed using `scheduler:register_system(settings?)`\r\nsettings can be provided to the system. Current relevant settings are `name` and `paused`.\r\n\r\njabby exposes a `scheduler:run()` function to start running a system.\r\n\r\nThis can be as simple as `scheduler:run(systemId, system, world, delta_time)`, where any arguments after the system will be used as arguments to the system callback.\r\n\r\nNote that `scheduler:run` does not check for yielding or pcalls. This should be handled from the user side.\r\n\r\nexample code\r\n\r\n```lua\r\n\r\nlocal scheduler = jabby.scheduler.create(\"example scheduler\")\r\n\r\nlocal system_a = scheduler:register_system {name = \"a\"}\r\nlocal system_b = scheduler:register_system {name = \"a\"}\r\nlocal system_c = scheduler:register_system {name = \"a\"}\r\n\r\nRunService.Heartbeat:Connect(function(dt)\r\n\r\n\tscheduler:run(system_a, systems.A, dt)\r\n\tscheduler:run(system_b, systems.B, dt)\r\n\tscheduler:run(system_c, systems.C, dt)\r\n\t\r\nend)\r\n\r\ntable.insert(jabby.public, scheduler)\r\njabby.public.updated = true\r\n\r\n```\r\n\r\n### Running in-game\r\n\r\njabby does not have any significant overhead if you aren't using it, so it's fine\r\nto leave it running in production. If you want to use jabby outside Studio, you are required to set a function which jabby can use to figure out which players are allowed to use jabby in-game.\r\n\r\nYou can overwrite the function using `jabby.set_check_function`; By default, this checks if you are currently running in Roblox Studio, and allows usage of the debugger while in Studio.\r\n\r\nIt's recommended to overwrite this to a function that allows the developer to use jabby while in-game. Note that this needs to be set on **every actor on both client and server**, otherwise it won't work. You should set this before spawning a jabby widget.\r\n\r\n### Spawning a widget\r\n\r\nJabby exposes `obtain_client`, which should be called in a script without a actor, unless you know what you are doing.\r\nRunning `obtain_client` on different actors should not be allowed.\r\n\r\nTo spawn a widget, just run `client.spawn_app(client.apps.home)`, which will\r\ncreate a new application where you can select the world / scheduler to debug.\r\n","readmeTruncated":false}