Umbra Guide 1.0.0d

Umbra: Script Search Tool - User Guide
Umbra is a tool for searching script content within your Roblox environment. It allows for complex queries to find specific code segments and provides a viewer to inspect matched scripts.

Interface Overview
Search Bar: Input search queries and commands.

Results List: Displays scripts matching your query. Click a script to open it.

Script Viewer: Shows the content of the selected script, with line numbers.

Match Navigator: (Right of script viewer) Lists lines in the current script where search terms were found. Click to jump to the line.

Info Panel: Displays status messages, search results summaries (including ETA during searches), and command outputs.

Progress Bar: Shows visual progress during a search, along with a script count.

Search Query Syntax
Terms
Enclose search terms in single quotes ('term') or double quotes ("term").

Example: "RemoteEvent", 'GetData'

Searches are case-insensitive.

Parentheses inside quoted strings (e.g., "myFunction(arg)") are treated as literal text, not as grouping operators.

Logical Operators
+ (AND): Finds scripts containing all specified terms.

Example: 'player' + 'save' (Finds scripts with both "player" AND "save")

/ (OR): Finds scripts containing at least one of the specified terms.

Example: 'FireServer' / 'InvokeServer' (Finds scripts with "FireServer" OR "InvokeServer")

! (NOT): Excludes scripts containing the term immediately following !.

Example: ! 'debug' (Excludes scripts containing "debug")

Can be combined: 'Weld' + ! 'Constraint' (Finds "Weld" but not "Constraint")

Grouping with Parentheses ()
Use parentheses to group expressions and control the order of operations for complex queries.

Example: ('load' / 'get') + 'data' (Finds (load OR get) AND data)

Example: ! ('deprecated' + 'legacy') (Excludes scripts containing both "deprecated" AND "legacy")

Commands
Enter commands in the search bar, prefixed with a semicolon (;).

General Commands
;guide

Copies a link to this user guide to the clipboard (if setclipboard is available).

;version

Displays Umbra's version information.

;copy

Copies the full content of the script currently in the viewer to the clipboard.

;clear (or ;cls)

Clears search results, the script viewer, and the info panel.

;path

Displays the full path of the script currently in the viewer.

;last (or ;!!)

Re-runs the previous search query.

;help (or ;?)

Displays a list of general commands and how to access container command help.

;conshelp

Displays help specifically for container management commands.

Container Management Commands
;addcon <FullPathToContainer> (alias: ;addcontainer)

Adds a new location (container) for Umbra to search within.

Example: ;addcon game.Workspace.SpecificModel

Example: ;addcon workspace.Tools

;listcons (alias: ;listcontainers)

Lists all currently active search containers and the number of searchable scripts (LocalScript, ModuleScript) within each.

;removecon <index> (alias: ;removecontainer)

Removes a search container from the list by its index number (shown by ;listcons).

Example: ;removecon 2

;listunusedcons

Scans common game services and lists potential top-level script-holding instances (and their script counts) that are not currently in your active search containers and are not descendants of any active container. Useful for discovering scripts in locations you might have overlooked.

Search Process
When a search begins, the Info Panel will indicate "Preparing search... (Counting scripts)".

It then updates to "Searching X/Y scripts... ETA: Zm Zs", providing an estimated time remaining.

The progress bar visually tracks the search.

Duplicate scripts (found via multiple container paths) are processed only once.

Troubleshooting
Syntax Errors ("Unrecognized character", "Mismatched parentheses"):

Ensure terms are quoted ('' or "").

Verify parentheses (for grouping logic) are balanced and are outside of quoted terms.

Check operator usage (+, /, !).

No Results:

Simplify your query or use broader terms.

Use ;listcons to verify the target scripts exist in the currently configured search locations.

Use ;addcon if the desired location isn't being searched.

Highlighting Issues:

If RichText tags (like <font>) appear as plain text, it may indicate an issue with special characters in the script content interfering with tag parsing.

Container Command Errors (e.g., "Path must start with 'game'..."):

For ;addcon, ensure your path is valid (e.g., game.Workspace, workspace.MyFolder).

For ;removecon, use a valid index number from the ;listcons output.

This guide provides essential instructions for using Umbra effectively.