Contributing Your Own Diagnostics, Autocompletions, or Definitions

March 29, 2026 · View on GitHub

A workflow-centric guide for contributors who want to add diagnostics, completions, or custom type definitions to the Minecraft Bedrock Language Server — whether for the upstream repository or for private use.

Table of Contents

Who This Guide Is For

This guide is for anyone who wants to:

  • Add a new diagnostic (error/warning/info check) for Bedrock project files
  • Add or extend autocomplete (completion) suggestions in JSON or mcfunction files
  • Contribute custom type definitions or project definitions
  • Make changes for private use without opening a pull request

No prior experience with language servers is required, but familiarity with TypeScript and npm workspaces will help.

Prerequisites and Setup

Tools Required

1. Fork the Repository

Click Fork on the GitHub repository page to create your own copy.

2. Clone Your Fork

git clone https://github.com/<your-username>/minecraft-bedrock-language-server.git
cd minecraft-bedrock-language-server

3. Install Dependencies

This installs dependencies for all packages in the monorepo:

npm install

4. Build the Project

Compile all TypeScript packages:

npm run build

5. Run Tests

Verify that everything works before making changes:

npm test

If all tests pass, you are ready to start contributing.

Understanding What You Can Contribute

The language server supports several types of features, each living in a specific package:

FeatureWhat It DoesWhere to Look
DiagnosticsReports errors, warnings, or hints for invalid content in Bedrock filespackages/bedrock-diagnoser/
CompletionsSuggests values when editing JSON or mcfunction fileside/base/server/src/lsp/completion/
Definitions (Go-to-Definition)Navigates from a reference to its definitionide/base/server/src/lsp/definition/
Type definitions / project dataDescribes types, entities, blocks, and other Bedrock conceptspackages/bedrock-types/ and packages/bedrock-project/
Custom project definitionsUser-defined tags, entities, objectives via .mcattributes / .mcdefinitionsSee MCDefinitions

Quick Decision Chart

Do you want to check for mistakes in files?
  → Add a Diagnostic (see packages/bedrock-diagnoser/)

Do you want to suggest values while typing?
  → Add a Completion (see ide/base/server/src/lsp/completion/)

Do you want Ctrl+Click / Go-to-Definition to work?
  → Add a Definition handler (see ide/base/server/src/lsp/definition/)

Do you want to describe your own entities, tags, etc.?
  → Use .mcdefinitions (see documentation/project/MCDefinitions.md)

Finding the Right Place to Make Changes

Diagnostics

All diagnostic logic lives in:

packages/bedrock-diagnoser/src/diagnostics/
├── behavior-pack/        # Checks for behavior pack files (entities, items, blocks, …)
├── resource-pack/        # Checks for resource pack files (animations, sounds, …)
├── general/              # Generic value checks (integers, booleans, floats, …)
├── minecraft/            # Minecraft-specific checks (selectors, effects, …)
├── molang/               # Molang expression checks
└── errors/               # Shared error utilities

Look for a subfolder that matches the type of file or concept you are checking. If one already exists, add your check to the relevant file in that folder. If not, create a new subfolder following the existing pattern.

Completions

Completion logic lives in:

ide/base/server/src/lsp/completion/minecraft/
├── behavior-pack/        # Completions for behavior pack JSON files
├── resource-pack/        # Completions for resource pack JSON files
└── (general)             # Shared completion utilities

Each file type (entity, item, block, …) typically has its own .ts file.

Definitions (Go-to-Definition)

Definition handlers live in:

ide/base/server/src/lsp/definition/

Vanilla / Type Data

If your change requires adding new Minecraft data (new entity IDs, block states, etc.):

  • Vanilla data: packages/bedrock-vanilla-data/
  • Type definitions: packages/bedrock-types/

Step-by-Step Contribution Workflow

Before starting significant work, open an issue to describe the change you want to make. This lets maintainers provide early feedback, avoid duplicate work, and guide your implementation.

For small fixes (typos, minor corrections, obvious bugs), you can skip this step and open a pull request directly.

2. Create a Branch

Create a dedicated branch from main:

git checkout main
git pull origin main
git checkout -b feature/my-feature-name

Use a descriptive branch name such as feature/diagnose-missing-loot-table or fix/entity-event-completion.

3. Make Your Changes

Follow the Implementing Your Feature section below.

4. Lint Your Code

npm run lint

Fix any warnings or errors before continuing.

5. Run the Tests

npm test

All existing tests must pass. If you added new tests, make sure those pass too.

6. Commit Your Changes

Use clear and concise commit messages:

git add .
git commit -m "feat(diagnoser): add missing loot table diagnostic"

7. Push and Open a Pull Request

git push origin feature/my-feature-name

Then open a pull request on GitHub (see Submitting a Pull Request).

Implementing Your Feature

Adding a Diagnostic

See the detailed guide: Creating Diagnostics

Quick example — checking that a required property exists:

// packages/bedrock-diagnoser/src/diagnostics/behavior-pack/loot-table/diagnose.ts
import { DiagnosticsBuilder, DiagnosticSeverity } from '../../types';

export function diagnose_loot_table_pool(
  pool: LootPool,
  path: string,
  diagnoser: DiagnosticsBuilder
): void {
  if (!pool.rolls) {
    diagnoser.add(
      `${path}/rolls`,
      'Loot table pool is missing required property: rolls',
      DiagnosticSeverity.error,
      'behaviorpack.loot_table.pool.rolls.missing'
    );
  }
}

Error code naming: follow the category.subcategory.type.detail convention (all lowercase). See the Style Guide for details.

Adding a Completion

See the detailed guide: JSON Completion

Quick example — suggesting loot table file names:

// ide/base/server/src/lsp/completion/minecraft/behavior-pack/my-feature.ts
import { MinecraftData } from 'bc-minecraft-bedrock-vanilla-data';
import { Context } from '../../../context/context';
import { CompletionContext } from '../../context';

export function provideCompletion(context: Context<CompletionContext>): void {
  const builder = context.builder;

  // Suggest items from the current project
  builder.generate(
    context.database.ProjectData.behaviorPacks.loot_tables,
    (item) => `Loot table: ${item.id}`
  );

  // Suggest vanilla items
  builder.generate(
    MinecraftData.vanilla.BehaviorPack.loot_tables,
    (item) => `Vanilla loot table: ${item.id}`
  );
}

Then register this function in the appropriate main.ts for behavior pack or resource pack completions.

Adding a Custom Type Definition

If you want to describe a new Minecraft concept (for example, a new component or a new field on an existing entity), update the relevant files in:

  • packages/bedrock-types/ — TypeScript interfaces and types
  • packages/bedrock-project/ — Project-level parsing and data collection

After changing type data, rebuild and rerun the tests to make sure the rest of the codebase still compiles.

Using Custom Project Definitions (Private Use)

If you only want custom definitions locally (for your own workspace, without modifying the repository), use the .mcdefinitions project file. See MCDefinitions for the full reference.

Writing Tests

Every diagnostic addition should have a corresponding test. The test infrastructure uses Jest and a custom test helper in packages/bedrock-diagnoser/test/.

Test File Location

Place tests under:

packages/bedrock-diagnoser/test/lib/diagnostics/<category>/<subcategory>/

Example Test

// packages/bedrock-diagnoser/test/lib/diagnostics/behavior-pack/loot-table/pool.test.ts
import { TestDiagnoser } from '../../../../diagnoser';
import { diagnose_loot_table_pool } from '../../../../../src/diagnostics/behavior-pack/loot-table/diagnose';

describe('diagnose_loot_table_pool', () => {
  it('should report an error when rolls is missing', () => {
    const diagnoser = TestDiagnoser.create();
    diagnose_loot_table_pool({} as any, 'pools/0', diagnoser);

    expect(diagnoser.items.length).toBeGreaterThan(0);
    expect(diagnoser.items[0].code).toBe('behaviorpack.loot_table.pool.rolls.missing');
  });

  it('should not report an error when rolls is present', () => {
    const diagnoser = TestDiagnoser.create();
    diagnose_loot_table_pool({ rolls: 1 } as any, 'pools/0', diagnoser);

    expect(diagnoser.items).toHaveLength(0);
  });
});

Run only the tests for the package you changed:

cd packages/bedrock-diagnoser
npm test

Or run all tests from the root:

npm test

Submitting a Pull Request

What to Include in Your PR Description

A good pull request description helps reviewers understand and approve your change faster. Include:

  1. What the change does — One or two sentences summarizing the new feature or fix.
  2. Why it is needed — Link to the related issue if one exists (e.g., Closes #123).
  3. How to test it manually — Describe any steps the reviewer can follow to verify the change.
  4. Checklist (optional but appreciated):
    • I have run npm run lint and fixed all warnings
    • I have run npm test and all tests pass
    • I have added tests for new functionality
    • I have updated documentation where relevant

PR Title Convention

Use a short, descriptive title in imperative mood:

feat(diagnoser): add missing loot table pool diagnostic
fix(completion): correct entity event suggestions in behavior packs
docs: add contributor guide for custom features

What Reviewers Look For

  • Naming conventions: error codes and function names follow the Style Guide
  • Test coverage: new diagnostics or completions have tests
  • Scope: the change is focused and does not include unrelated modifications
  • Code style: code is formatted consistently with the rest of the codebase

Getting Help and Reviews

ResourcePurpose
GitHub IssuesReport bugs, request features, or ask for guidance before starting
GitHub DiscussionsGeneral questions and community conversation
Pull request commentsAsk for clarification or feedback directly on your PR
CONTRIBUTING.mdHigh-level contribution guidelines
Code of ConductCommunity standards

Tips for getting faster reviews:

  • Keep pull requests small and focused on one thing.
  • Write a clear description so reviewers understand your intent without reading all the code.
  • Respond promptly to review comments to keep the conversation moving.
  • If a PR sits for more than a week without feedback, leave a polite comment to ping reviewers.

Contributing for Private Use

If you want to use these features in your own tooling without contributing back to the repository:

  1. Fork the repository (see Prerequisites and Setup).
  2. Make your changes on your fork — you do not need to open a pull request.
  3. Link your fork locally instead of the published npm packages: 
    npm run build
npm link
  4. In your own project, link to your local build: 
    npm link bc-minecraft-bedrock-diagnoser
  5. Rebuild your fork whenever you update it: 
    npm run build

For workspace-level custom definitions that do not require code changes, see MCDefinitions and MCAttributes.

Happy contributing! 🎉 If you get stuck, open an issue — the maintainers are happy to help.