{"id":"illinois-roadbuff/light-reflector","name":"light-reflector","scope":"illinois-roadbuff","platform":"roblox","description":"A vehicle-based light reflector that reflects decals and basepart reflectors at long distances on a road.","version":"2.3.1","latest":"2.3.1","versions":["0.0.1","0.0.2","1.0.0-alpha.2","1.0.0-infdev.2","1.0.0-infdev.2.1","1.1.0-beta","1.1.1-beta","2.3.0","2.3.1"],"license":"MPL-2.0","licenseRating":"caution","licenseCaveats":["File-level copyleft: if you modify this package's own source files, those modified files must be made available under MPL-2.0. Using it unmodified in a closed-source game is fine."],"licenseVerified":false,"dependencies":{},"integrity":"7894d160973c8ed43ee29abbd25d3cb1883baef7afeda78e7e8225b1677cd503","likes":0,"downloads":0,"install":"forest install illinois-roadbuff/light-reflector","url":"https://forest.dev/p/roblox/illinois-roadbuff/light-reflector","files":"https://api.forest.dev/ai/package/roblox/illinois-roadbuff/light-reflector/files","readme":"# Light Reflector \r\n**Latest Pre-Release Version: N/A**\r\n\r\n**Latest Partially Stable Version: 2.3.1**\r\n\r\n **A vehicle-based light reflector system that reflects `Decals` and `BasePart` reflectors at long distances on roads, built using [Jecs](https://github.com/Ukendio/jecs.git).**\r\n\r\n[![License: MPL 2.0](https://img.shields.io/badge/MPL_2.0-License-gray.svg?logo=mozilla&labelColor=28733f)](https://opensource.org/licenses/MPL-2.0) [![Codeberg](https://img.shields.io/badge/Codeberg-Main%20Repository-white?logo=codeberg)](https://codeberg.org/project-roadwork/light-reflector.git) [![GitHub](https://img.shields.io/badge/GitHub-Mirror/Backup%20Repository-darkgrey?logo=github)](https://github.com/project-roadwork/light-reflector.git) \r\n\r\n\r\n> [!IMPORTANT]\r\n> ****Please use the [main repository](https://codeberg.org/project-roadwork/light-reflector.git) especially with contributions or commits!*** *Additionally, please **DO NOT** make any changes in the mirrored repository as it cannot be pulled into the main repo.**\r\n> \r\n> **The main repository is in Codeberg; however, I provided a *push* mirror on GitHub (pulls are not supported). Open an issue in Codeberg if you have concerns with this.**\r\n\r\n> [!NOTE]\r\n> ### Codeberg Releases (`.rbxm` download)\r\n> ***https://codeberg.org/project-roadwork/light-reflector/releases***\r\n\r\n> [!WARNING]\r\n> **This script is under `alpha` and some functions may not work correctly or be unstable. Additionally, there is no *external* documentation for this module at the moment.**\r\n\r\n### Wally / Pesde Notice\r\n**The Wally and Pesde packages are outdated! Unfortunately I cannot publish Pesde packages due to `const` usage.**\r\n\r\n*Additionally, this is my first time using Pesde AND Wally - apologies if something is not formatted correctly.*\r\n\r\n### Issues\r\n1. **Broken Wally and Pesde packages, with mismatched versioning**\r\n2. **Rojo may not work correctly?**\r\n3. **Possible BasePart memory leak on games with Instance Streaming**\r\n4. ~~**Many `:GetAttribute` calls popping up in the Microprofiler**~~\r\n5. **No external documentation**\r\n6. **Some signs and reflectors may not work at all in very rare occasions**\r\n\r\n## Global features\r\n1. Adaptive waiting on performance-critical functions\r\n2. Distance fall-off\r\n3. Angle-based brightness\r\n4. Multi-vehicle support\r\n5. Non-tweened fading/transitions for gradual brightness\r\n6. Option to use `Tags` with `CollectionService`\r\n7. Uses Entity Component System via [Jecs](https://github.com/Ukendio/jecs.git)\r\n\r\n## Sign/Gantry System Features\r\n1. Utilizes `SurfaceGuis` and `ImageLabel` OR `Decals` by itself for reflectivity\r\n2. Uses `.ImageTransparency`, `.Brightness`, and `.LightInfluence`\r\n3. SurfaceGui pooling to increase performance\r\n4. Automatic sign `:Dot` support\r\n   * This determines if the vehicle is facing the sign or not to determine reflectiveness\r\n5. Automatic part rotation for `Top` faces\r\n   * Part rotation is needed since the orientation of images in `Decals` and `SurfaceGuis` are NOT the same\r\n   * This may break the visuals of actual non-square parts due to rotations\r\n6. Best for large reflective highway signs on gantries\r\n\r\n## Reflector System Features\r\n1. Utilizes `BaseParts` for reflectivity\r\n2. Uses `.Color` and `.Material`\r\n3. Wedge `:Dot` support, with face (`Enum.NormalId`) selection on non-wedges\r\n   * This determines if the vehicle is facing the part or not to determine reflectiveness\r\n4. Best for pavement reflectors on the road\r\n\r\n### Hybrid System Features\r\n1. Works alongside the Reflector System with no separate loop needed\r\n2. Uses `.Color`, `.Material`, AND `.Transparency` with similar equations to the Sign/Gantry System\r\n3. Face (`Enum.NormalId`) selection\r\n4. Best for reflective traffic light shields, non-decal signs, etc.\r\n\r\n## Essential Public API\r\n1. `.start()` - Starts the module\r\n2. `.reset()` - Resets states and cleans up the module\r\n3. `.config.applyOverrides({})` - Parses user configuration before starting (if you cannot do it IN the module first)\r\n4. `.register.addVehicle(car: Instance, isHeadlightEnabled: () -> boolean, getIntensity: () -> number)` - Registers vehicles into the module\r\n5. `.register.removeVehicle(car: Instance)` - Unregisters vehicles from the module\r\n\r\n## Example Usage\r\n```lua\r\nlocal LightReflector = require(path.to.module)\r\n\r\nlocal function determineIntensity(car)\r\n  local finalIntensity = 1\r\n-- logic to see if high beams are enabled or not (thus increase the intensity)\r\n  return finalIntensity\r\nend\r\n\r\nLightReflector.config.applyOverrides({\r\n  -- make any config changes here\r\n})\r\n\r\nLightReflector.start()\r\n\r\nworkspace.Cars.ChildAdded:Connect(function(car)\r\n\tif car:IsA(\"Model\") and car:FindFirstChildOfClass(\"VehicleSeat\") then\r\n\t\tprint(\"Indexed Vehicle\")\r\n\t\tLightReflector.register.registerVehicle(car, true, determineIntensity) -- true is the placeholder of what \"enables\" the light source like a Headlight boolean value\r\n\tend\r\nend)\r\n\r\nworkspace.Cars.ChildRemoved:Connect(function(car)\r\n\tif car:IsA(\"Model\") and car:FindFirstChildOfClass(\"VehicleSeat\") then\r\n\t\tLightReflector.register.unregisterVehicle(car)\r\n\tend\r\nend)\r\n```\r\n**Other examples such as server pre-tagging and a vehicle handler are provided in the examples folder.**\r\n\r\n## Systems Diagram\r\n![Diagram](assets/images/light_reflector_systems.png)\r\n\r\n## Older YouTube Showcase\r\n***Not up to date, uses 0.1.x***\r\n[![](https://utfs.io/f/nGnSqDveMsqxO7YMYJ0k5fKEn2LbBoPAuZ6XMTHDcNJ0QiG1)](https://www.youtube.com/watch?v=YK-_NzeLqjI)\r\n\r\n\r\n## Contributing\r\n**This section exists due to the file-level copyleft nature of the Mozilla Public License 2.0.**\r\n\r\n*By contributing to this project, you agree that your contributions may be redistributed and relicensed by this project under other open-source and/or open-content licenses in the future (such as Apache-2.0).*\r\n\r\n**View the reason why this clause exists in [./CONTRIBUTING.md](CONTRIBUTING.md)**\r\n\r\n## License\r\n**License: [Mozilla Public License 2.0](https://mozilla.org/MPL/2.0/) (open source).** \r\n\r\n*This may be changed to a more permissive license in the future, but unlikely.*\r\n\r\n> [!NOTE]\r\n> ### Mozilla Public License 2.0 Summary\r\n> **Warning: This summary does NOT act as a subsitute for the entire legal text. This is also not legal advice**\r\n> \r\n> **The Mozilla Public License 2.0 (MPL-2.0) is a weak copyleft license.**\r\n> \r\n> **You are free to:**\r\n> * Use, modify, and distribute the code\r\n> * Use the code commercially (including games and/or proprietary software)\r\n>\r\n> **Under the following conditions:**\r\n> * Any files originally from MPL that you modify must remain licensed under MPL\r\n> * You must make the source code of MPL-licensed files publicly available\r\n> * MPL-covered code must remain in separate files\r\n> \r\n> **In short:** You can use MPL code in closed-source and/or commercial projects; however, any changes to MPL-covered files must stay open under MPL.\r\n>\r\n> **Compared to GPL/GNU licenses:**\r\n> * **GPL:** May require the entire project (like games) to be fully open-sourced under GPL if GPL code is included\r\n> * **LGPL:** Allows use in proprietary projects, but requires that users can modify and swap out LGPL-covered code and still run the project with it, which is not very feasible with games and closed-source binary platforms such as ROBLOX. Additionally, this license allows users to reverse engineer entire projects\r\n> * **MPL:** Only requires open-sourcing the specific modified files\r\n\r\n### License Comparison (not legal advice)\r\n\r\n| Feature / License        | Expact (aka \"MIT\")    | Apache 2.0 | MPL 2.0       | GPL / AGPL v3               |\r\n| ------------------------ | ------ | ---------- | ------------- | ------------------------ |\r\n| **Permissive**           | ✅      | ✅          | ℹ️ Partial    | ❌                        |\r\n| **Patent Clause**         | ❌      | ✅          | ✅             | ✅                        |\r\n| **Proprietary Use OK**   | ✅      | ✅          | ✅¹           | ❌  (Must release whole source)                       |\r\n| **Roblox Asset Usage**   | ✅      | ✅          | ℹ️ Depends; must share any changes    | ❌ May violate terms      |\r\n\r\n* ¹ Proprietary use in MPL is permitted (allowed) as long as the MPL-covered files remain open souce.\r\n","readmeTruncated":false}