Ocean Lua API

IntelliSense for the anticheat.ac Ocean Lua scripting API, based on the bundled doc.txt. Supports all 28 documented functions, GAMEPIDS, and 17 scanner dataset keys.

Features

• Visible variables rank ahead of API globals; shadowed names appear once. New variable and parameter declarations do not get API suggestions.
• Function completion with quoted choices, existing-variable placeholders, parameter hints, and hover documentation loaded on demand.
• Contextual dataset keys, severities, connection kinds, registry views, and option-table keys.
• Decoded JSON field completion through local assignments, API aliases, constant dataset keys, array indexing, nested objects, bracket notation, and ipairs/pairs loops. Local table fields are also inferred.
• Gentle informational diagnostics and explicit quick fixes for API and option spellings, argument values, drive formats, registry roots, Windows path escapes, and unnecessary JSON decoding. Also detects duplicate options, quoted boolean options, calling native values, argument counts, and fields read from raw JSON.
• Go to Definition opens a local variable declaration or the relevant API section of doc.txt.
• Shared, bounded document-version caches and linear scope lookup reduce repeated work. Automatic checks wait until typing pauses, and all providers respect the configured file-size limit.
• Nine snippets for checked JSON calls, processes, events, scanner data, file searches, journal entries, reports, game PIDs, and registry values. Type ocean- to find them.
• Bundled Lua Language Server annotations for globals, parameters, options, and documented result shapes.

Install and use

Build with npm install followed by npm run package, then use Extensions: Install from VSIX to install ocean-lua-0.1.0.vsix. Requires VS Code 1.136 or newer. To develop, open this project and press F5.

Open a .lua file and type an API name, or run Ocean Lua: New Script. Use Ctrl+Space for suggestions. The extension works without a separate language server and does not execute scripts or connect to the scanner.

local raw, err = Processes()
if not raw then
    log(err)
    return
end
local processes = json.decode(raw)
for _, process in ipairs(processes) do
    log(process.Name, process.PID)
    -- Type process. here to see documented record fields.
end

Most APIs return JSON text and an error. Decode only after checking for nil. ReadEventLog also returns truncated. GAMEPIDS is already a Lua table; IsPe returns a boolean; ScanPattern returns a count; lastWrite and createdAt return timestamps.

Commands

• Ocean Lua: Search API Reference — searchable function list that opens the bundled reference.
• Ocean Lua: New Script — creates an unsaved Lua script with error handling.
• Ocean Lua: Open Lua Language Server Definitions — opens resources/ocean-api.lua.

Friendly input, strict runtime API

The extension does not add functions to the scanner or assume it accepts alternative arguments. Completion and quick fixes rewrite convenient spellings to actual API calls. Existing scripts are never rewritten on save.

journal("C:") is already the documented form and is left alone. Drive suggestions are examples, not a scan of your disks. Use the lightbulb or Ctrl+. to accept a fix. The scanner still receives only the code you choose to insert.

Settings

All settings support per-workspace configuration. Set oceanLua.enabled to false in workspaces that do not use Ocean. Static snippets remain available.

The extension defaults Lua's editor.wordBasedSuggestions to off, so VS Code does not reintroduce unrelated words or duplicate names from other open documents. You can override this in your own [lua] settings. Suggestions from other installed language extensions cannot be removed by Ocean.

Lua Language Server integration

For broader Lua syntax checking, formatting and navigation, this extension can coexist with Lua Language Server. Use the definitions command to locate resources/ocean-api.lua, then add its containing directory to your Lua.workspace.library setting. Do not execute the definitions file. No workspace settings are changed automatically.

The generated annotations describe actual API returns as JSON strings, not decoded tables. Result classes can also be used in manual type annotations. If both extensions suggest the same globals, turn off oceanLua.completion or avoid adding the definitions library. If both suggest local variables, set oceanLua.variableCompletion to false.

Inference limits

Field suggestions are inferred from JSON examples in doc.txt; fields may be absent or differ at runtime. This is a lightweight lexical analyzer, not a full Lua compiler or control-flow engine. It handles common direct calls, raw-to-decoded assignments, aliases, literal dataset-key variables, nested fields and loops. Computed dataset keys, custom decoding wrappers, metatables, cross-file types and complex branch-dependent assignments are not resolved. No unknown-field warnings are emitted. The undocumented ScanPattern flags remain any. General Lua syntax checking remains the responsibility of a Lua language server.

License

Copyright (c) 2026 Ocean creators. All rights reserved. See the bundled LICENSE file for terms. Third-party components retain their own licenses.

Development

• npm test — compile, regenerate definitions, lint, and run core tests.
• npm run test:integration — run provider tests in an isolated VS Code extension host. Set VSCODE_EXECUTABLE_PATH to use an installed executable; otherwise the runner downloads VS Code.
• npm run package — produce an installable VSIX.

The catalog in src/api.ts defines signatures and constraints. Result shapes are extracted from doc.txt at activation; scripts/generate.cjs uses that same catalog to generate resources/ocean-api.lua during compilation. Keep signatures and reference documentation in sync when the runtime API changes.