{"id":"vocksel/object-highlighter","name":"object-highlighter","scope":"vocksel","platform":"roblox","description":"Mirrored from the Wally registry.","version":"0.1.0","latest":"0.1.0","versions":["0.1.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":["License identified from the packaged LICENSE file; the manifest declared none."],"licenseVerified":true,"dependencies":{},"integrity":"399063ccd0f40f01a51b6f18104281291d6983731168b2603a54950d6df2e410","likes":0,"downloads":0,"install":"forest install vocksel/object-highlighter","url":"https://forest.dev/p/roblox/vocksel/object-highlighter","files":"https://api.forest.dev/ai/package/roblox/vocksel/object-highlighter/files","readme":"\n\n# ObjectHighlighter\nThis module allows you to make an object or model act as \"Always on Top\" (or X-Ray) and layer over the normal 3D game world.\n\n##### Table of Contents\n* [Purpose](#purpose)\n* [Screenshots](#screenshots)\n* [Code Example](#code-example)\n* [API Reference](#api-reference)\n\t* [Methods](#methods)\n\t* [Renderer](#renderer)\n\t* [Render Implementations](#render-implementations)\n\n# Purpose\nTo provide an generic, sexy, and extendable solution to adopting ViewportFrames as a means to render an object on top of a 3D environment.\n\nThis is intended to replace older solutions such as [rbx-XRayAdornment](https://github.com/benbrimeyer/rbx-XRayAdornment). Our previous issues with this old xray module is that it made it really hard to balance the state of the target object with the actual rendering process.\n\nThere was some difficulty in making a good \"only-render-when-obstructed\" highlighted object. All attempts were messy and oddly coupled with the creation of the XRayAdornment itself.\nOur philosophy is to separate highlight state from highlight render rules.\n\n# Screenshots\n![Screenshot of module in action; The user is on Crossroads looking at the silhouette of a house through the side of a wall.](https://i.imgur.com/mwNxmpZ.png)\n*Implementations.highlightColor example*\n\n![Screenshot of module in action; The user is looking at a wooden wall and can see full colored avatars through the wall using X-Ray vision.](https://i.imgur.com/xMk1xBd.jpg)\n*Implementations.worldColor example*\n\n\n# Code Example\n_Check out our other annotated examples in the [`examples`](https://github.com/benbrimeyer/rbx-ObjectHighlighter/tree/master/examples) directory!_\n\n```lua\nlocal ObjectHighlighter = require(ReplicatedStorage:FindFirstChild(\"ObjectHighlighter\"))\n\n-- This screen gui will contain our ViewportFrames\nlocal myScreenGui = Instance.new(\"ScreenGui\")\nmyScreenGui.Name = \"ObjectHighlighter\"\nmyScreenGui.Parent = Players.LocalPlayer.PlayerGui\n\nlocal myRenderer = ObjectHighlighter.createRenderer(myScreenGui)\n\n-- Assume we have a Model as a direct child of Workspace\nlocal myHighlight = ObjectHighlighter.createFromTarget(Workspace.Model)\n\n-- Apply our highlight object to our Renderer stack.\n-- We can add as many highlight objects to a renderer as we need\nmyRenderer:addToStack(myHighlight)\n\nRunService.RenderStepped:Connect(function(dt)\n\t-- Our renderer will not render until it steps\n\tmyRenderer:step(dt)\nend)\n```\n\n# API Reference\n\n## Methods\n\n### ObjectHighlighter.createFromTarget\n`ObjectHighlighter.createFromTarget(targetModel)`\n\nReturns a Highlight state generated from the given `targetModel`.\nBy default, this state contains the following fields: `target` and `color`.\n\n### ObjectHighlighter.createRenderer\n`ObjectHighlighter.createRenderer(targetScreenGui)`\n\nReturns a Renderer object targeted to the given `targetScreenGui`.\n\n## Renderer\n\n### Renderer:withRenderImpl\n`Renderer:withRenderImpl(implentationFunc)`\n\nInjects the given `implementationFunc` that will be used by the current Renderer.\n\nYou may apply any of ObjectHighlighter's pre-built render implementation functions or offer a custom function.\n\nBy default, the Renderer will use the `worldColor` implementation.\n\nSee Render Implementations below for more details.\n\n### Renderer:addToStack\n`Renderer:addToStack(highlight)`\n\nInserts the given `highlight` state to the end of the stack.\n\nThe Renderer will iterate through all Highlight states when it's `step` function is invoked.\n\n### Renderer:removeFromStack\n`Renderer:removeFromStack(highlight)`\n\nRemoves the given `highlight` state from the stack.\n\nThis will remove any active ViewportFrames that may be associated with this highlight state.\n\n### Renderer:step\n`Renderer:step(deltaTime)`\n\nInvoking this method will cause the Renderer to iterate through all highlight states in its stack.\n\nWhile iterating, it will map its current render implementation to every highlight state in the stack.\n\nSee Render Implementations below for more details.\n\n## Render Implementations\n\nRender Implementations allow the user to extend the Renderer in an entirely user-defined way.\n\n### Pre-built Implementations\n\nThe current pre-built Render Implmentations are:\n\n* worldColor\n\t* The default implementation. This will sync any color changes that occur on the target model with the ViewportFrame model.\n\t* Use this if you want an authentic look to the highlighted model.\n* highlightColor\n\t* When rendering, the ViewportFrame model will override the target model's coloring with the current `color` field found on the `Highlight` object.\n\t* Use this if you prefer a silhouette look to the highlighted model.\n\n### Custom Implementations\n\nUndoubtably, there will come a time where you will need to write a custom render implementation.\n\nRender implementations injected using `Renderer:withRenderImpl` must be a **function** that returns a **dictonary of functions**. These functions should be keyed with specific namespaces.\n\n#### onBeforeRender\n`onBeforeRender = function(dt, worldModel)`\n\nThis function will be invoked every step before onRender.\n\nIf this function returns `false`, the Renderer will not render the ViewportFrame for the current frame. If this function returns anything else, it will continue to render.\n\nThis function can be used to filter highlighted objects from rendering. This can be useful when implementing an implmentation that only renders highlights if there is something obstructing the view of the `targetModel`.\n\n#### onRender\n`onRender = function(deltaTime, worldPart, viewportPart, highlightState)`\n\nThis function will be invoked every step after onRender. It is invoked on every indivual BasePart of the `targetModel` and ViewportFrame respectively.\n\nBy default, this function is soley responsible for repositioning the `viewportPart` to match any recent transformations that may have occured to the `worldPart`.\n\nBecause this function is invoked for every BasePart on every frame, it is important to keep this function as succient and tight as possible for performance reasons.\n\n\n#### onAdded\n`onAdded = function(worldPart, viewportPart, highlight)`\n\nThis function will be invoked after `Renderer:addToStack`.\n\nThis can be used to set up any temporary event connections that need to be used to sync the state of the `worldPart` to the `viewportPart`.\n\n#### onRemoved\n`onRemoved = function(worldPart, viewportPart, highlight)`\n\nThis function will be invoked when `Renderer:removeFromStack` is called.\n\nThis is usually used in tandem with the `onAdded` render implementation to clean up any event connections is may have temporarily created.\n","readmeTruncated":false}