@minecraft/creator-tools
Version:
Minecraft Creator Tools command line and libraries.
243 lines (242 loc) • 11 kB
TypeScript
import IFormDefinition from "../dataform/IFormDefinition";
import IFile from "../storage/IFile";
import IFolder from "../storage/IFolder";
import IField from "../dataform/IField";
export declare const MarkdownTop = "---\nauthor: mammerla\nms.author: mikeam\ntitle: \"{0}\"\ndescription: \"{1}\"\nai-usage: ai-assisted\nms.service: minecraft-bedrock-edition\nms.date: 02/11/2025 \n---\n";
export declare enum ExportMode {
other = 0,
triggers = 1,
blockComponents = 2,
itemComponents = 3,
entityComponents = 4,
AIGoals = 5,
visuals = 6,
fogs = 7,
websockets = 8,
filters = 9,
MCToolsVal = 10,
eventResponses = 11,
clientBiomes = 12,
biomes = 13,
features = 14,
featureCore = 15,
deferredRendering = 16,
molang = 17,
culling = 18,
manifest = 19,
blockCullingComponents = 20,
recipes = 21,
lootTables = 22,
spawnRules = 23,
animations = 24,
camera = 25,
dialogue = 26,
particles = 27,
commands = 28,
jigsaw = 29,
dimensions = 30,
attachables = 31,
jsonUi = 32,
tradeTables = 33,
featureRules = 34,
voxelShapes = 35
}
export default class FormMarkdownDocumentationGenerator {
private _referenceFolder;
private _skippedFiles;
/** Keyword param types that represent literal tokens in command syntax, not user-supplied values. */
private static readonly KEYWORD_PARAM_TYPES;
/**
* Generate markdown documentation from form JSON files.
* @param formJsonInputFolder The folder containing form.json files
* @param outputFolder The folder to write generated markdown to
* @param referenceFolder Optional folder containing existing docs - files that exist here will be skipped
*/
generateMarkdown(formJsonInputFolder: IFolder, outputFolder: IFolder, referenceFolder?: IFolder): Promise<void>;
/**
* Check if a file exists in the reference folder (existing docs).
* Also checks for common naming variations (e.g., minecraft_ prefix).
*/
private existsInReferenceFolder;
private getFileNameFromBaseName;
exportMarkdownAggregatedPage(formsByPath: {
[name: string]: IFormDefinition;
}, outputFolder: IFolder, exportMode: ExportMode, filePath: string, formsPath: string, category: string, categoryExtended: string, exclusionList?: string[]): Promise<void>;
exportValidatorMarkdownCatalogDocs(formsByPath: {
[name: string]: IFormDefinition;
}, outputFolder: IFolder, exportMode: ExportMode, subFolderPath: string, formsPath: string, categoryPlural: string, categorySingular: string, exclusionList?: string[]): Promise<void>;
exportMarkdownCatalogDocs(formsByPath: {
[name: string]: IFormDefinition;
}, outputFolder: IFolder, exportMode: ExportMode, subFolderPath: string, formsPath: string, categoryPlural: string, categorySingular: string, exclusionList?: string[]): Promise<void>;
exportMarkdownDocListPage(formsByPath: {
[name: string]: IFormDefinition;
}, outputFolder: IFolder, exportMode: ExportMode, subFolderPath: string, formsPath: string, category: string, subFolderName: string, exclusionList?: string[]): Promise<void>;
exportListYml(formsByPath: {
[name: string]: IFormDefinition;
}, outputFolder: IFolder, exportMode: ExportMode, subFolderPath: string, formsPath: string, header?: string, prefix?: string, exclusionList?: string[]): Promise<void>;
private getFirstSentence;
saveMarkdownDocFromForm(markdownFile: IFile, form: IFormDefinition, baseName: string, exportMode: ExportMode, category: string, categoryExtended: string): Promise<void>;
saveValidatorMarkdownDocFromForm(markdownFile: IFile, form: IFormDefinition, baseName: string, exportMode: ExportMode, category: string, categoryExtended: string): Promise<void>;
sanitizeDescription(description: string): string;
/**
* Format a long description for rendering outside a table.
* Detects embedded definition-list patterns (lines like "term: description")
* and renders them as a bulleted list with bold terms for readability.
*/
formatLongDescription(description: string): string;
getFileNameFromJsonKey(key: string): string;
/**
* Compute a structural fingerprint for a sub-form based on its field IDs and types.
* Used to detect structurally identical sub-forms and deduplicate them in the output.
*/
private getSubFormFingerprint;
/**
* Compute a stable key for a choices array so identical choices tables can be deduplicated.
*/
private getChoicesFingerprint;
/**
* Returns the markdown heading prefix for a given nesting depth.
* depth 0 → "##", depth 1 → "###", depth 2 → "####", capping at "######".
*/
private getHeadingPrefix;
appendForm(form: IFormDefinition, content: string[], depth: number, altTitle?: string, formStack?: string[], formsAppended?: {
[name: string]: boolean;
}, jsonPath?: string, choicesAppended?: {
[fingerprint: string]: string;
}): Promise<void>;
addAdditionalNotes(field: IField): string;
appendValidatorForm(form: IFormDefinition, content: string[], depth: number, altTitle?: string, filePrefix?: string): Promise<void>;
/**
* Checks if a validation field has auto-fix actions available.
*/
private validatorFieldHasAutoFix;
getValueAsString(value: any): any;
sanitizeForTable(value: string): string;
getMarkdownBookmark(id: string): string;
getFormsFromFilter(formsByPath: {
[name: string]: IFormDefinition;
}, formsPath: string, mode: ExportMode, exclusionList?: string[]): {
[name: string]: IFormDefinition;
};
loadFormJsonFromFolder(formsByPath: {
[name: string]: IFormDefinition;
}, inputFolder: IFolder, outputFolder: IFolder): Promise<void>;
/**
* Static category map for grouping commands in the TOC.
* When a command is not listed here it goes into "Other".
*/
private static readonly COMMAND_CATEGORIES;
/**
* Map a numeric permission level to its human-readable label.
*/
private getPermissionLevelName;
/**
* Determine whether a command parameter type is a "keyword" (literal token in the syntax)
* vs. a "value" parameter that accepts user input.
*
* Keyword types appear as bare text in the syntax line: `/camera <players> set <preset> ease ...`
* Value types appear as `<name: type>` or `[name: type]`.
*/
private isKeywordParamType;
/**
* Extract a human-readable subcommand name from an ACTION-type commandType.
* e.g., CAMERASHAKEACTIONADD → "add", MUSICPLAYACTION → "play",
* SCOREBOARDADDACTION → "add", DIALOGUEOPENACTION → "open"
*
* Uses the command name to strip the known prefix from the type string.
*/
private getActionKeywordName;
/**
* Look up a field definition by its id from the command form's fields array.
* The fields in command forms carry `commandType`, `isOptional`, `subFormId`, etc.
* as raw JSON properties (not all are in the IField TypeScript interface).
*/
private getCommandField;
/**
* Get a human-readable type name for a command parameter.
* Uses the field's subFormId (type form title) if available, otherwise
* falls back to humanifying the commandType string.
*/
private getCommandParamTypeName;
/**
* Build a syntax line string from an overload's params and the form's fields.
*
* Example output:
* `/camera <players: target> set <preset: CameraPresets> ease <easeTime: float> <easeType: Easing>`
*/
private buildSyntaxLine;
/**
* Group overloads by their first distinguishing parameter (the "verb").
* For most commands, params[0] is the target selector and params[1] is the verb.
* For commands with no target selector at start, params[0] is the verb.
*
* Returns an ordered array of groups to preserve a natural order.
*/
private groupOverloadsByVerb;
/**
* Generate a descriptive title for an overload when the form's title is a placeholder
* like "Overload 27" or empty.
*
* Builds a description from the parameter names that distinguish this overload
* from others in the same verb group.
*/
private generateOverloadTitle;
/**
* Sub-group overloads within a verb group by their second distinguishing keyword.
*
* For example, the "set" verb group of the camera command has overloads that use
* ease, pos, rot, facing, view_offset, entity_offset, etc. This groups them into
* semantic sub-categories like "With easing", "Position and rotation only", etc.
*/
private subGroupOverloads;
/**
* Save a command documentation markdown file from a cmd_*.form.json definition.
*
* Output structure:
* - YAML frontmatter
* - # /commandname heading + description
* - Permission/cheats table
* - Syntax overview (all overload syntax lines)
* - Overloads grouped by verb, each with syntax + argument table
* - Flat arguments reference at the bottom
*/
saveCommandMarkdownDocFromForm(markdownFile: IFile, form: IFormDefinition, baseName: string, formsByPath: {
[name: string]: IFormDefinition;
}): Promise<void>;
/**
* Find a form definition by its subFormId reference.
* SubFormIds like "type_selection" map to paths like "/command/type_selection.form.json".
*/
private findFormBySubFormId;
/**
* Save a command type documentation markdown file from a type_*.form.json definition.
*
* These are simpler reference pages for argument types (like "Entity Selector", "Position", etc.).
*/
saveCommandTypeMarkdownDocFromForm(markdownFile: IFile, form: IFormDefinition, baseName: string): Promise<void>;
/**
* Export command catalog docs, calling the command-specific renderer
* instead of the generic component renderer.
*/
exportCommandMarkdownCatalogDocs(formsByPath: {
[name: string]: IFormDefinition;
}, outputFolder: IFolder, subFolderPath: string, formsPath: string): Promise<void>;
/**
* Export command type catalog docs using the type-specific renderer.
*/
exportCommandTypeMarkdownCatalogDocs(formsByPath: {
[name: string]: IFormDefinition;
}, outputFolder: IFolder, subFolderPath: string, formsPath: string): Promise<void>;
/**
* Export a categorized command list page organized by category.
*/
exportCommandListPage(formsByPath: {
[name: string]: IFormDefinition;
}, outputFolder: IFolder, subFolderPath: string, formsPath: string): Promise<void>;
/**
* Export a grouped TOC.yml for commands, organized by category.
*/
exportCommandListYml(formsByPath: {
[name: string]: IFormDefinition;
}, outputFolder: IFolder, subFolderPath: string, formsPath: string): Promise<void>;
}