Skip to content

Development

Abdelrahman Abdelaal edited this page Aug 6, 2026 · 5 revisions

Development

This page covers development tasks for maintaining the Verse Auto Imports extension.

Table of Contents


Updating Digest Files

Digest files contain the official Verse API documentation from Epic Games. These files need to be updated when a new UEFN version is released to ensure the extension has the latest API information.

Source Files

The raw digest files are located in:

src/utils/
  Fortnite.digest.verse
  UnrealEngine.digest.verse
  Verse.digest.verse

Pre-compiled JSON Files

At build time, the digest files are parsed into JSON format for faster runtime loading:

src/data/
  Fortnite.digest.json
  UnrealEngine.digest.json
  Verse.digest.json

Where to Find Digest Files

Digest files are generated when you build a UEFN project. They are stored in your local AppData:

%LOCALAPPDATA%\UnrealEditorFortnite\Saved\VerseProject\<ProjectName>\
  Fortnite\Fortnite.digest.verse
  UnrealEngine\UnrealEngine.digest.verse
  Verse\Verse.digest.verse

Example paths:

C:\Users\<username>\AppData\Local\UnrealEditorFortnite\Saved\VerseProject\MyProject\Fortnite\Fortnite.digest.verse
C:\Users\<username>\AppData\Local\UnrealEditorFortnite\Saved\VerseProject\MyProject\UnrealEngine\UnrealEngine.digest.verse
C:\Users\<username>\AppData\Local\UnrealEditorFortnite\Saved\VerseProject\MyProject\Verse\Verse.digest.verse

Community Resource: The vz-creates/uefn repository maintains updated digest files for each UEFN release. This is the recommended source for getting the latest digest files without needing to build a project yourself.

Steps to Update Digest Files

  1. Get the new digest files

    Option A: From vz-creates/uefn repository (recommended)

    Download the latest digest files from github.com/vz-creates/uefn

    Option B: From your UEFN project AppData

    After building your project in UEFN, find the digest files in:

    %LOCALAPPDATA%\UnrealEditorFortnite\Saved\VerseProject\<ProjectName>\
    
  2. Replace the source files

    Copy the new .verse digest files to src/utils/:

    # Example (adjust paths as needed)
    cp /path/to/new/Fortnite.digest.verse src/utils/
    cp /path/to/new/UnrealEngine.digest.verse src/utils/
    cp /path/to/new/Verse.digest.verse src/utils/
  3. Parse the digest files to JSON

    Run the parse script to generate the pre-compiled JSON files:

    npm run parse-digest

    This will output:

    Parsing Verse digest files...
      Source: src/utils
      Output: src/data
    
      Parsing Fortnite.digest.verse...
        -> Fortnite.digest.json
           1234 entries, 56 modules
           Build: ++Fortnite+Release-XX.XX-CL-XXXXXXXX
      ...
    
    Done! Total: XXXX entries parsed
    
  4. Verify the changes

    Check that the JSON files were updated:

    ls -la src/data/*.json

    Review the generated JSON to ensure it parsed correctly.

  5. Test the extension

    • Press F5 to launch the Extension Development Host
    • Open a .verse file
    • Test that digest-based suggestions work correctly
  6. Commit the changes

    git add src/utils/*.verse src/data/*.json
    git commit -m "chore: update digest files to build XX.XX"

Automatic Parsing During Build

The npm run vscode:prepublish script automatically runs parse-digest before packaging:

{
  "scripts": {
    "vscode:prepublish": "npm run parse-digest && npm run compile"
  }
}

This ensures the JSON files are always up-to-date when publishing the extension.

Digest File Format

The source .verse files follow the standard Verse syntax with special comments:

# Module import path: /Fortnite.com/Devices

creative_device<public> := class<concrete>(creative_object_interface):
    # Device that can be placed in a level
    ...

The parser extracts:

  • Class, struct, interface, enum declarations
  • Function and variable declarations
  • Only <public> declarations are included, in any specifier order — <native><public> is recognized the same as <public>

Module scope is derived from indentation, not from ambient state. A pending # Module import path: comment applies to the next module only; after that, resolution falls back to a (/path:) scope qualifier, then the enclosing module, then the file's root domain. This is what keeps a comment from leaking onto later comment-less modules.


Building the Extension

Development Build

npm run compile        # One-time compile
npm run watch         # Watch mode for development

Production Build

npm run vscode:prepublish   # Full build with digest parsing

Testing

Unit Tests

Jest with ts-jest. The vscode module is mocked at src/__mocks__/vscode.ts, so these run without a VS Code runtime. Tests live in __tests__/ directories beside the code they cover.

npm test                    # whole suite
npx jest path/to.test.ts    # one file

Any bug fix in pure logic (extractors, formatters, parsers) should come with a regression test.

Integration Tests

A second layer runs inside a real extension host, compiled separately via tsconfig.integration.json from src/test-integration/:

npm run test:integration        # against the compiled extension
npm run test:integration:vsix   # against a packaged VSIX

Formatting

Prettier formats all TypeScript at 4-space indentation (config in .prettierrc.json). CI fails on unformatted code:

npm run format          # write
npm run format:check    # verify, as CI does

Manual Testing

  1. Press F5 in VS Code to launch the Extension Development Host
  2. Open a UEFN project with .verse files
  3. Test:
    • Auto-import triggers correctly
    • Quick fixes appear for ambiguous imports
    • Path conversion CodeLens works
    • Digest-based suggestions (if enabled)

Contributing

Issues and pull requests are welcome. The repository follows GitHub Flow: main is the only long-lived branch, and every change branches from it and returns by pull request.

Branching

Branch from main using one of the established prefixes, and open the PR back into main:

feature/ fix/ chore/ docs/ test/ refactor/

A hotfix is just a fix/ branch; it needs no special path. Because PRs target the default branch, writing Closes #N in the PR body genuinely links and closes the issue.

Before opening a PR

npm run format         # Prettier, 4-space; CI fails on unformatted code
npm run compile        # tsc
npm test               # jest

A bug fix in pure logic — extractors, formatters, parsers — should come with a regression test. Those run without the VS Code runtime, so they are cheap to add and cheap to keep.

Changelog

Any user-facing change needs a changelog fragment rather than an edit to CHANGELOG.md. Add one file at changelog.d/<key>.<category>.md containing the entry prose only — no leading - , no ([#N]) tag, no link definition, since release assembly generates all three. The key is the issue number, or a short slug when nothing tracks the change; the category is one of the Keep a Changelog six, lowercase.

Purely internal changes — refactors, test-only work, CI tweaks — do not need a fragment.

Merging

Every PR into main is squash-merged, so a branch lands as exactly one commit. This is enforced by the Default Branch ruleset, not just convention, and the release tooling depends on it when it reads the commit range for a new version.


Releasing

Releasing is automated. Nobody runs vsce publish by hand — the only manual step is publishing the draft release, and that is deliberate, because a Marketplace version cannot be unpublished, only superseded.

The flow

  1. Open a release PR on a chore/release-vX.Y.Z branch that bumps version in package.json, refreshes the lockfile with npm install --package-lock-only, and assembles the changelog.
  2. Squash-merge it into main. Squash is the only merge method the Default Branch ruleset allows.
  3. release-draft.yml fires on the push to main, notices the version is new, and creates a draft GitHub Release with that version's changelog section as the notes. No git tag exists yet — GitHub holds the tag name on the draft and only creates it on publish.
  4. Publish the draft. That is the manual gate.
  5. publish.yml fires on the release: published event, packages the VSIX, ships it to the Marketplace, and announces on Discord.

Changelog entries

Do not edit CHANGELOG.md directly for a pending change. Each user-facing change gets its own fragment file at changelog.d/<key>.<category>.md, holding the entry prose only — no leading - , no ([#N]) tag, no link definition. The key is the tracked issue number or a short slug; the category is one of the Keep a Changelog six, lowercase.

Release assembly folds every fragment into one dated section, generates the issue links and the compare link, and deletes the fragments it consumed. One file per change is what stops parallel branches conflicting on a single shared file.

Building a VSIX locally

vsce package

Useful for installing a build via Extensions: Install from VSIX... or attaching one to a PR for testing. CI already produces this artifact for every pull request.