Noble Fates OctDat & Modding Support

Language support and tooling for Noble Fates .octdat modding files.

Requirements

• Visual Studio Code 1.105.0 or higher

Features

🎨 Editor Features

• Custom File Icon - Noble Fates icon for .octdat files
• Syntax Highlighting - Color-coded syntax based on VS Code Dark+ theme
• Formatting - Format documents with Shift + Alt + F
• IntelliSense - Basic Type completion and suggestions
• Hover Tooltips - Information on hover
• Auto-closing Pairs - Automatic bracket/quote completion and surrounding
• .octdat.bak Support - Works with backup files

🧭 Navigation & Indexing

• Go to Definition - Ctrl+Click or F12 on IDs and <...> references to jump to their definitions
• Find All References - Shift+F12 to see everywhere an ID is used
• Local ID Resolution - .ChildId automatically resolves to full qualified names
• Mod Tracking - See which mods define or reference specific IDs
• Diagnostics:
  • Warnings for unknown references when base files are present
  • Info-level hints when base OctDats aren't in workspace (with prompt to add them)
  • Syntax errors and style hints (with Quick Fixes):
    • Inline // comments after code are invalid (game parser only supports full-line comments)
    • Mismatched/unclosed {}, [] braces
    • Missing space before = (can break parsing)
    • Missing space after = (style warning)
• Status Bar Indicator - Shows indexing status

Commands

Access via Command Palette (Ctrl+Shift+P):

• Format .octdat Files in Directory - Format all .octdat files in a folder (also Ctrl+K 8)
• Create OctMod.info - Create mod metadata file (also Ctrl+K 9)
• OctDat: Add Base OctDat Folder to Workspace... - Add base game files for complete navigation
• OctDat: Rebuild Index - Manually refresh the index
• OctDat: Show ID Definitions - View all definitions of an ID (with mod info)

⌨️ Keyboard Shortcuts

• Shift + Alt + F - Format document
• F12 - Go to Definition
• Shift + F12 - Find All References
• Ctrl+K 8 - Format all .octdat files in directory
• Ctrl+K 9 - Create OctMod.info

💡 Tips

• Add the base game's StreamingAssets/OctDats folder to your workspace for full reference resolution
• Run OctDat: Rebuild Index after adding/removing many files

📊 CodeLens

Inline information above ID definitions:

• Definition Counts - See how many times an ID is defined (with mod sources)
• Duplicate Detection - Warns when the same mod is installed multiple times
• Inheritance Chain - Shows which IDs inherit from the current definition
• Reference Usage - Displays where IDs are referenced via <...> tags
• Local ID Resolution - Shows what .ChildID resolves to

🔧 Side Panel

Access from the Activity Bar (left sidebar):

• Workspace Status Dashboard - Live workspace/index status
  • Index state (indexing / indexed)
  • Base OctDats detected/missing
  • Indexed file count and unique ID count
  • Unknown reference counts + ratio
  • Last index rebuild time
• OctMod.info Creator - Interactive form to generate mod metadata files
  • Supports: name, preview, description, compatibleVersions, compatibilityPatches, dependencies, localize, defaultOrder
  • Folder navigation to select target location
• Modding Guide - Quick link to official documentation
• Settings - Access extension settings

You can also run common actions directly from the side panel:

• Rebuild Index
• Add Base OctDat Folder (attempts to auto-detect common Steam install paths first, then falls back to manual folder selection)

📝 Workflow Features

• Snippets - Tab-completable templates for common patterns
• Format Directory - Format all .octdat files in a folder
  • Context menu: Right-click in editor
  • Keybinding: Ctrl+K 8
• Create OctMod.info - Quick command from context menu
  • Keybinding: Ctrl+K 9

Extension Settings

Configure via File > Preferences > Settings or search for "OctDat":

• octdat.formatOnSave - Automatically format .octdat files on save (default: false)
• octdat.saveOnFormat - Automatically save after formatting (default: false)
• octdat.useTooltips - Enable hover tooltips (default: true)
• octdat.liveIndexing.debounceMs - Delay (ms) before live indexing runs after you stop typing
• octdat.indentation - Choose indentation style:
  • Tab (\t) (default)
  • Two Spaces
  • Four Spaces

Navigation/Indexing:

• octdat.index.rebuildOnWorkspaceFolderChange - Automatically rebuild the index when workspace folders change
• octdat.index.maxFilesForLiveIndexing - If greater than 0, disables live indexing when the index contains more than this many .octdat files

Base OctDats:

• octdat.base.autoDetect.enabled - Attempt to auto-detect the base StreamingAssets/OctDats folder when adding base content
• octdat.base.autoDetect.confirm - Confirmation behavior for auto-detected base folder (always, onlyWhenMultiple, never)
• octdat.base.missingPrompt.enabled - Enable/disable the "base missing" prompt
• octdat.base.missingPrompt.minUnknownRefs - Unknown reference count threshold for the "base missing" heuristic
• octdat.base.missingPrompt.unknownRatio - Unknown reference ratio threshold (0-1) for the "base missing" heuristic

Side Panel:

• octdat.sidePanel.showWorkspaceStatus - Show/hide the Workspace Status dashboard
• octdat.sidePanel.refreshIntervalMs - If greater than 0, periodically request fresh status updates

Issues & Feedback

Found a bug or have a feature request? Report it on our GitLab Issue Tracker.

Common Issues:

• If syntax highlighting isn't working, reload the window (Ctrl+Shift+P → "Reload Window") and ensure files use .octdat extension
• For formatting issues, check extension settings under "Noble Fates OctDat"
• If navigation isn't working, ensure the indexing status bar shows "OctDat: Indexed"

Contributing

Contributions are welcome:

1. Check open issues
2. Fork the repository
3. Submit a merge request

For major changes, open an issue first to discuss.

License

See LICENSE file for details.