{"id":46588611,"url":"https://github.com/secondlife/sl-vscode-plugin","last_synced_at":"2026-04-10T19:03:41.680Z","repository":{"id":325124627,"uuid":"1099329074","full_name":"secondlife/sl-vscode-plugin","owner":"secondlife","description":"Second Life scripting VSCode plugin.","archived":false,"fork":false,"pushed_at":"2026-03-04T18:18:25.000Z","size":765,"stargazers_count":23,"open_issues_count":12,"forks_count":11,"subscribers_count":3,"default_branch":"develop","last_synced_at":"2026-03-05T00:44:12.594Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/secondlife.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-18T21:26:47.000Z","updated_at":"2026-03-04T18:18:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/secondlife/sl-vscode-plugin","commit_stats":null,"previous_names":["secondlife/sl-vscode-plugin"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/secondlife/sl-vscode-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secondlife%2Fsl-vscode-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secondlife%2Fsl-vscode-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secondlife%2Fsl-vscode-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secondlife%2Fsl-vscode-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/secondlife","download_url":"https://codeload.github.com/secondlife/sl-vscode-plugin/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secondlife%2Fsl-vscode-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30214618,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T12:15:00.571Z","status":"ssl_error","status_checked_at":"2026-03-07T12:15:00.217Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-07T13:02:33.412Z","updated_at":"2026-03-07T13:02:34.216Z","avatar_url":"https://github.com/secondlife.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Second Life VSCode Plugin\r\n\r\n**Enhance your Second Life scripting workflow with advanced preprocessing and external editing capabilities!**\r\n\r\n[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/secondlife/sl-vscode-plugin)\r\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\r\n[![VS Code](https://img.shields.io/badge/VS%20Code-1.85.0+-red.svg)](https://code.visualstudio.com/)\r\n\r\nThe Second Life External Scripting Extension transforms VS Code into a development environment for Second Life scripts, supporting both **LSL (Linden Scripting Language)** and **SLua (Second Life Lua)** with preprocessing capabilities and viewer integration.\r\n\r\n---\r\n\r\n## Key Features\r\n\r\n### Script Preprocessing\r\n\r\n- **Include System**: Modular programming with `#include` directives (LSL) and `require()` syntax (SLua)\r\n- **Macro Processing**: Define constants and function-like macros with `#define`\r\n- **Conditional Compilation**: Code inclusion with `#ifdef`, `#ifndef`, `#if`, `#elif`, `#else`\r\n- **Include Guards**: Automatic prevention of duplicate file inclusion\r\n- **Circular Protection**: Detection and prevention of infinite include loops\r\n- **Flexible Search Paths**: Configurable include directories for organized projects\r\n\r\n### Real-Time Viewer Integration\r\n\r\n- **WebSocket Connection**: Direct communication with Second Life viewer\r\n- **Live Synchronization**: Real-time script editing and updates\r\n- **External Editing**: Edit scripts externally while maintaining viewer session\r\n- **Configurable Networking**: Customizable WebSocket port and connection settings\r\n\r\n### Development Tools\r\n\r\n- **Language Definitions**: Automatic download and updating of latest Second Life language definitions\r\n- **Compile Error Display**: Real-time display of compilation errors from Second Life viewer\r\n- **Debug Message Monitoring**: Capture and display debug messages from `llOwnerSay()` calls and debug channel chat\r\n- **In-World Debugging**: Monitor script output and debug information directly in VS Code\r\n\r\n### Cross-Language Support\r\n\r\n- **LSL (Linden Scripting Language)**: Full preprocessing with includes, macros, and conditionals\r\n- **SLua (Second Life Lua)**: Modern Lua scripting with `require()` module system\r\n- **Smart Detection**: Automatic language recognition based on file extensions\r\n\r\n---\r\n\r\n## Installation\r\n\r\n### From VS Code Marketplace (Coming Soon)\r\n\r\n1. Open VS Code\r\n2. Go to Extensions (Ctrl+Shift+X)\r\n3. Search for \"Second Life External Scripting\"\r\n4. Click Install\r\n\r\n### Manual Installation\r\n\r\n1. Download the latest `.vsix` file from [Releases](https://github.com/secondlife/sl-vscode-plugin/releases)\r\n2. Open VS Code\r\n3. Press `Ctrl+Shift+P` and type \"Extensions: Install from VSIX\"\r\n4. Select the downloaded file\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\n### Setting Up Your First Project\r\n\r\n1. **Create a new workspace folder** for your Second Life scripts\r\n2. **Open the folder in VS Code**\r\n3. **Start scripting** with preprocessing features!\r\n\r\n### Basic Include Example (LSL)\r\n\r\nCreate modular, maintainable scripts:\r\n\r\n**utils/constants.lsl**\r\n```lsl\r\n#define MAX_AVATARS 10\r\n#define CHAT_CHANNEL 42\r\n#define DEBUG_MODE\r\n```\r\n\r\n**utils/helpers.lsl**\r\n```lsl\r\n#include \"constants.lsl\"\r\n\r\n#ifdef DEBUG_MODE\r\n    #define DEBUG_SAY(msg) llOwnerSay(\"[DEBUG] \" + msg)\r\n#else\r\n    #define DEBUG_SAY(msg) // No debug output in release\r\n#endif\r\n\r\nstring formatMessage(string message) {\r\n    return \"[\" + llGetScriptName() + \"] \" + message;\r\n}\r\n```\r\n\r\n**main.lsl**\r\n```lsl\r\n#include \"utils/helpers.lsl\"\r\n\r\ndefault {\r\n    state_entry() {\r\n        DEBUG_SAY(\"Script initialized\");\r\n        llSay(PUBLIC_CHANNEL, formatMessage(\"Hello, world!\"));\r\n        llListen(CHAT_CHANNEL, \"\", NULL_KEY, \"\");\r\n    }\r\n\r\n    listen(integer channel, string name, key id, string message) {\r\n        if (channel == CHAT_CHANNEL) {\r\n            DEBUG_SAY(\"Received: \" + message);\r\n            // Process command...\r\n        }\r\n    }\r\n}\r\n```\r\n\r\n### Modern Module System (SLua)\r\n\r\nUse modern Lua module patterns:\r\n\r\n**modules/math-utils.luau**\r\n```lua\r\nlocal function clamp(value, min, max)\r\n    return math.max(min, math.min(max, value))\r\nend\r\n\r\nlocal function lerp(a, b, t)\r\n    return a + (b - a) * clamp(t, 0, 1)\r\nend\r\n\r\nreturn {\r\n    clamp = clamp,\r\n    lerp = lerp\r\n}\r\n```\r\n\r\n**main.luau**\r\n```lua\r\nlocal mathUtils = require(\"modules/math-utils\")\r\n\r\nfunction onTouch(avatar)\r\n    local distance = (avatar.position - object.position).magnitude\r\n    local alpha = mathUtils.lerp(0.2, 1.0, distance / 10.0)\r\n    object:setAlpha(alpha)\r\nend\r\n```\r\n\r\n---\r\n\r\n## Configuration\r\n\r\n### Only use plugin in specific workspaces\r\n\r\nThe plugin can be configured to only run inside specific workspaces, instead of globally.\r\n\r\nTo do this, go to `settings` \u003e `extienstions` and find the SL Scipting settings,\r\nand uncheck the `Enabled` setting.\r\n\r\nThen in any workspace you want to use the plugin in, you can either manually set the\r\n`Enabled` setting at the workspace level, or open the command pallete and run the\r\n`Second Life: Enable Extension for Workspace` command.\r\n\r\n### Preprocessor Settings\r\n\r\nConfigure preprocessing behavior in VS Code settings:\r\n\r\n```json\r\n{\r\n    \"slVscodeEdit.preprocessor.enable\": true,\r\n    \"slVscodeEdit.preprocessor.includePaths\": [\r\n        \".\",\r\n        \"./include/\",\r\n        \"**/include/\"\r\n    ],\r\n    \"slVscodeEdit.preprocessor.maxIncludeDepth\": 5\r\n}\r\n```\r\n\r\n**Note**: The `includePaths` shown above are the defaults. You can customize them to match your project structure (e.g., add `\"./lib/\"`, `\"./utils/\"`, or `\"**/common/\"`).\r\n\r\n### Network Settings\r\n\r\nCustomize viewer connection:\r\n\r\n```json\r\n{\r\n    \"slVscodeEdit.network.websocketPort\": 9020,\r\n    \"slVscodeEdit.network.disconnectDelayMs\": 100,\r\n    \"slVscodeEdit.network.disposeDelayMs\": 1000\r\n}\r\n```\r\n\r\n### Storage Settings\r\n\r\nControl where configuration files are stored:\r\n\r\n```json\r\n{\r\n    \"slVscodeEdit.storage.useLocalConfig\": true\r\n}\r\n```\r\n\r\nWhen `true` (default), configuration files are stored in your workspace's `.vscode` directory. When `false`, they're stored in the global VS Code settings directory.\r\n\r\n---\r\n\r\n## Using with Second Life Viewer\r\n\r\n### Connection Setup\r\n\r\n1. **Enable External Script Editor** in Second Life viewer preferences\r\n2. **Set the editor** to connect via WebSocket on port 9020 (configurable)\r\n3. **Configure the extension** using VS Code settings for WebSocket connection\r\n\r\n### Workflow\r\n\r\n1. **Right-click** on an object in Second Life\r\n2. **Select \"Edit\"** → **\"Scripts\"**\r\n3. **Click \"New Script\"** or **\"Edit\"** on existing script\r\n4. **Choose external editor** - VS Code will automatically open\r\n5. **Edit in VS Code** with full preprocessing support\r\n6. **Save** to sync changes back to the viewer\r\n\r\n### Linux-specific instructions\r\nIf using the flatpak version of vscode, the External Script Editor command is:\r\n```\r\n/usr/bin/flatpak run --file-forwarding com.visualstudio.code --reuse-window @@ \"%s\" @@\r\n```\r\n\r\n---\r\n\r\n## Additional Features\r\n\r\n### Conditional Compilation\r\n\r\nCreate feature-toggled and platform-specific code:\r\n\r\n```lsl\r\n// Feature flags\r\n#define FEATURE_ANALYTICS\r\n#define FEATURE_ADVANCED_PHYSICS\r\n// #define FEATURE_BETA_FEATURES\r\n\r\n// Environment configuration\r\n#ifdef PRODUCTION\r\n    #define LOG_LEVEL 1\r\n    #define MAX_RETRIES 3\r\n#else\r\n    #define LOG_LEVEL 3\r\n    #define MAX_RETRIES 10\r\n#endif\r\n\r\ndefault {\r\n    state_entry() {\r\n        llOwnerSay(\"Log level: \" + (string)LOG_LEVEL);\r\n\r\n        #ifdef FEATURE_ANALYTICS\r\n            // Analytics code only included when feature is enabled\r\n            initializeAnalytics();\r\n        #endif\r\n\r\n        #ifdef FEATURE_BETA_FEATURES\r\n            llOwnerSay(\"Beta features enabled\");\r\n        #endif\r\n    }\r\n}\r\n```\r\n\r\n### Function-Like Macros\r\n\r\nCreate reusable code templates:\r\n\r\n```lsl\r\n// Define a logging macro with parameters\r\n#define LOG_ERROR(category, message) \\\r\n    llOwnerSay(\"[ERROR][\" + category + \"] \" + message + \" at \" + (string)llGetUnixTime())\r\n\r\n#define VALIDATE_AVATAR(id, action) \\\r\n    if (id == NULL_KEY) { \\\r\n        LOG_ERROR(\"AVATAR\", \"Invalid avatar ID in \" + action); \\\r\n        return; \\\r\n    }\r\n\r\ndefault {\r\n    touch_start(integer total_number) {\r\n        key toucher = llDetectedKey(0);\r\n        VALIDATE_AVATAR(toucher, \"touch_start\");\r\n\r\n        // Macro expands to full validation and logging code\r\n        LOG_ERROR(\"TOUCH\", \"Unexpected touch event\");\r\n    }\r\n}\r\n```\r\n\r\n### Nested Requirements (SLua)\r\n\r\nBuild complex module hierarchies:\r\n\r\n**utils/logger.luau**\r\n```lua\r\nlocal Logger = {}\r\n\r\nfunction Logger.info(message)\r\n    print(\"[INFO] \" .. message)\r\nend\r\n\r\nfunction Logger.warn(message)\r\n    print(\"[WARN] \" .. message)\r\nend\r\n\r\nfunction Logger.error(message)\r\n    print(\"[ERROR] \" .. message)\r\nend\r\n\r\nreturn Logger\r\n```\r\n\r\n**services/inventory.luau**\r\n```lua\r\nlocal logger = require(\"utils/logger\")\r\n\r\nlocal function getItemCount(itemName)\r\n    logger.info(\"Checking inventory for: \" .. itemName)\r\n    -- Inventory logic here\r\n    return 5\r\nend\r\n\r\nlocal function addItem(itemName, count)\r\n    logger.info(\"Adding \" .. count .. \" of \" .. itemName)\r\n    -- Add item logic here\r\nend\r\n\r\nreturn {\r\n    getItemCount = getItemCount,\r\n    addItem = addItem\r\n}\r\n```\r\n\r\n**main.luau**\r\n```lua\r\nlocal inventory = require(\"services/inventory\")\r\n\r\nfunction onTouch(avatar)\r\n    local coinCount = inventory.getItemCount(\"coins\")\r\n    inventory.addItem(\"coins\", 1)\r\nend\r\n```\r\n\r\n---\r\n\r\n## Commands\r\n\r\nAccess these commands via the Command Palette (`Ctrl+Shift+P`):\r\n\r\n| Command | Description |\r\n|---------|-----------|\r\n| `Second Life: Force Language Update` | Refresh language definitions and features |\r\n\r\n---\r\n\r\n## Documentation\r\n\r\nComprehensive guides available in the `doc/` directory:\r\n\r\n- **[Preprocessor Guide](doc/preprocessor-guide.md)** - Complete preprocessing reference\r\n- **[Message Interfaces](doc/Message_Interfaces.md)** - WebSocket communication protocols\r\n\r\n---\r\n\r\n## Requirements\r\n\r\n- **Visual Studio Code** 1.85.0 or later\r\n- **Node.js** (for development and testing)\r\n- **Second Life Viewer** with external editor support\r\n\r\n### Recommended Extensions\r\n\r\nFor enhanced language support and features, install these language server extensions:\r\n\r\n**For SLua/Luau files:**\r\n- **Selene** (`kampfkarren.selene-vscode`) - Lua linter and language support\r\n- **Luau Language Server** (`johnnymorganz.luau-lsp`) - Luau language server\r\n\r\n**For LSL files:**\r\n- **LSL Language Server** (such as `sekkmer.vscode-lsl-lsp`) - LSL language support with diagnostics\r\n\r\n**Additional Extensions for Enhanced Development:**\r\n- **StyLua** (`johnnymorganz.stylua`) - Lua code formatter\r\n- **VSCode LSL** (`vrtlabs.vscode-lsl`) - Alternative LSL language support\r\n\r\n**Note**: These extensions are optional but recommended for the best development experience. The preprocessor and viewer integration features work independently of these language servers.\r\n\r\n---\r\n\r\n## Troubleshooting\r\n\r\n### Common Issues\r\n\r\n#### WebSocket Connection Failed\r\n- **Check port**: Ensure port 9020 (or configured port) is available\r\n- **Firewall**: Allow VS Code through Windows Firewall\r\n- **Viewer settings**: Verify external editor is enabled in viewer preferences\r\n\r\n#### Include Files Not Found\r\n- **Check paths**: Verify include paths in settings\r\n- **File extensions**: Ensure `.lsl` or `.luau` extensions are used\r\n- **Working directory**: Includes are resolved relative to workspace root\r\n\r\n#### Preprocessing Not Working\r\n- **Enable preprocessing**: Check `slVscodeEdit.preprocessor.enable` setting\r\n- **File types**: Preprocessing only works on `.lsl` and `.luau` files\r\n- **Syntax errors**: Check for malformed directive syntax\r\n\r\n### Getting Help\r\n\r\n- **Issues**: [GitHub Issues](https://github.com/secondlife/sl-vscode-plugin/issues)\r\n- **Discussions**: [GitHub Discussions](https://github.com/secondlife/sl-vscode-plugin/discussions)\r\n- **Documentation**: Check the `doc/` folder for detailed guides\r\n\r\n---\r\n\r\n## Contributing\r\n\r\nWe welcome contributions! Please see our contributing guidelines:\r\n\r\n1. **Fork** the repository\r\n2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)\r\n3. **Commit** your changes (`git commit -m 'Add amazing feature'`)\r\n4. **Push** to the branch (`git push origin feature/amazing-feature`)\r\n5. **Open** a Pull Request\r\n\r\n### Development Setup\r\n\r\n```bash\r\ngit clone https://github.com/secondlife/sl-vscode-plugin.git\r\ncd sl-vscode-plugin\r\nnpm install\r\nnpm run compile\r\n```\r\n\r\n### Running Tests\r\n\r\n```bash\r\nnpm test              # Full test suite\r\nnpm run test-unit     # Unit tests only\r\nnpm run lint          # Code linting\r\n```\r\n\r\n---\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n---\r\n\r\n## Version History\r\n\r\n### v1.0.1\r\n- Fix for incorrect luau-lsp config use\r\n- Switch from class to extern syntax for luau-lsp defs and move DetecteEvent\r\n- Fix selene yaml gen and toml config\r\n- Fix for selene yaml self on : calls\r\n- Fix default data to have eventname for LLEvents:off\r\n- Make saves of included/required files trigger 'saves' on actively sync'd file\r\n- Fix precomp require generating invalid code for files with no trailing line ending\r\n- Add fallback lookup for matching file, if the default glob finds nothing\r\n- Add config to enable/disable the extension, and a command to do it quickly\r\n- Update Package Name Across Project to fix README Links and be Consistent with Repo Name\r\n- Implement optional check to prevent saving over a file with identicle content\r\n\r\n### v1.0.0 (Initial Release)\r\n- Advanced LSL and SLua preprocessing\r\n- WebSocket viewer integration\r\n- Include system with search paths\r\n- Macro processing and conditional compilation\r\n- Include guards and circular protection\r\n- Real-time script synchronization\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsecondlife%2Fsl-vscode-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsecondlife%2Fsl-vscode-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsecondlife%2Fsl-vscode-plugin/lists"}