ADD uid refs listings

deepnight · Aug 29, 2024 · 4459a89 · 4459a89
1 parent 192c5dd
commit 4459a89
Show file tree

Hide file tree

Showing 2 changed files with 30 additions and 7 deletions.
diff --git a/docs/JSON_DOC.md b/docs/JSON_DOC.md
@@ -88,7 +88,7 @@ Value | Type | Description
 `layerInstances`<br/> ![Generic badge](https://img.shields.io/badge/Changed_0.7.0-gray.svg)  | Array&nbsp;of&nbsp;[Layer&nbsp;instance](#ldtk-LayerInstanceJson)&nbsp;*(can&nbsp;be&nbsp;`null`)* | An array containing all Layer instances. **IMPORTANT**: if the project option "*Save levels separately*" is enabled, this field will be `null`.<br/>		This array is **sorted in display order**: the 1st layer is the top-most and the last is behind.
 `pxHei` | Int | Height of the level in pixels
 `pxWid` | Int | Width of the level in pixels
-`uid` | Int | Unique Int identifier
+`uid` | Int | Unique Int identifier<br/> This UID is refered from:<br/> ↖ [levelUid](#ldtk-NeighbourLevel;levelUid) (Neighbour level)<br/> ↖ [levelId](#ldtk-LayerInstanceJson;levelId) (Layer instance)
 `worldDepth`<br/> ![Generic badge](https://img.shields.io/badge/Added_1.0.0-gray.svg)  | Int | Index that represents the "depth" of the level in the world. Default is 0, greater means "above", lower means "below".<br/>		This value is mostly used for display only and is intended to make stacking of levels easier to manage.
 `worldX`<br/> ![Generic badge](https://img.shields.io/badge/Added_0.6.0-gray.svg) ![Generic badge](https://img.shields.io/badge/Changed_1.0.0-gray.svg)  | Int | World X coordinate in pixels.<br/>		Only relevant for world layouts where level spatial positioning is manual (ie. GridVania, Free). For Horizontal and Vertical layouts, the value is always -1 here.
 `worldY`<br/> ![Generic badge](https://img.shields.io/badge/Added_0.6.0-gray.svg) ![Generic badge](https://img.shields.io/badge/Changed_1.0.0-gray.svg)  | Int | World Y coordinate in pixels.<br/>		Only relevant for world layouts where level spatial positioning is manual (ie. GridVania, Free). For Horizontal and Vertical layouts, the value is always -1 here.
@@ -223,7 +223,7 @@ Value | Type | Description
 `pxOffsetX`<br/> ![Generic badge](https://img.shields.io/badge/Added_0.5.0-gray.svg)  | Int | X offset of the layer, in pixels (IMPORTANT: this should be added to the `LayerInstance` optional offset)
 `pxOffsetY`<br/> ![Generic badge](https://img.shields.io/badge/Added_0.5.0-gray.svg)  | Int | Y offset of the layer, in pixels (IMPORTANT: this should be added to the `LayerInstance` optional offset)
 `tilesetDefUid`<br/><sup class="only">Only *Tile layers, Auto-layers*</sup><br/><sup class="uidRef">UID ref to [Tileset definition](#ldtk-TilesetDefJson)</sup><br/> ![Generic badge](https://img.shields.io/badge/Changed_1.0.0-gray.svg)  | Int&nbsp;*(can&nbsp;be&nbsp;`null`)* | Reference to the default Tileset UID being used by this layer definition.<br/>		**WARNING**: some layer *instances* might use a different tileset. So most of the time, you should probably use the `__tilesetDefUid` value found in layer instances.<br/>		Note: since version 1.0.0, the old `autoTilesetDefUid` was removed and merged into this value.
-`uid` | Int | Unique Int identifier
+`uid` | Int | Unique Int identifier<br/> This UID is refered from:<br/> ↖ [layerDefUid](#ldtk-LayerInstanceJson;layerDefUid) (Layer instance)<br/> ↖ [autoSourceLayerDefUid](#ldtk-LayerDefJson;autoSourceLayerDefUid) (Layer definition)<br/> ↖ [autoTilesKilledByOtherLayerUid](#ldtk-LayerDefJson;autoTilesKilledByOtherLayerUid) (Layer definition)
 `autoRuleGroups`<br/><sup class="only">Only *Auto-layers*</sup><br/><sup class="internal">*Only used by editor*</sup> | Array&nbsp;of&nbsp;Object | Contains all the auto-layer rule definitions.<br/> This array contains objects with the following fields:<br/> <ul class='subFields'><li>**`active`** **(Bool**)</li><li>**`biomeRequirementMode`** **(Int**)  ![Generic badge](https://img.shields.io/badge/Added_1.5.0-green.svg) </li><li>~~collapsed~~ **(Bool**)    *This field was removed in 1.0.0 and should no longer be used.*</li><li>**`color`** **(String *(can be `null`)***)  ![Generic badge](https://img.shields.io/badge/Added_1.4.0-gray.svg) </li><li>**`icon`** **([Tileset rectangle](#ldtk-TilesetRect) *(can be `null`)***)  ![Generic badge](https://img.shields.io/badge/Added_1.4.0-gray.svg) </li><li>**`isOptional`** **(Bool**)  ![Generic badge](https://img.shields.io/badge/Added_0.9.0-gray.svg) </li><li>**`name`** **(String**)</li><li>**`requiredBiomeValues`** **(Array of String**)  ![Generic badge](https://img.shields.io/badge/Added_1.5.0-green.svg) </li><li>**`rules`** **(Array of [Auto-layer rule definition](#ldtk-AutoRuleDef)**)</li><li>**`uid`** **(Int**)</li><li>**`usesWizard`** **(Bool**)  ![Generic badge](https://img.shields.io/badge/Added_1.1.4-gray.svg) </li></ul>
 `autoTilesKilledByOtherLayerUid`<br/><sup class="only">Only *Auto layers*</sup><br/><sup class="uidRef">UID ref to [Layer definition](#ldtk-LayerDefJson)</sup><br/><sup class="internal">*Only used by editor*</sup><br/> ![Generic badge](https://img.shields.io/badge/Added_1.5.0-green.svg)  | Int&nbsp;*(can&nbsp;be&nbsp;`null`)* | 
 `biomeFieldUid`<br/><sup class="uidRef">UID ref to [Field definition](#ldtk-FieldDefJson)</sup><br/><sup class="internal">*Only used by editor*</sup><br/> ![Generic badge](https://img.shields.io/badge/Added_1.5.0-green.svg)  | Int&nbsp;*(can&nbsp;be&nbsp;`null`)* | 
@@ -276,7 +276,7 @@ Value | Type | Description
 `tileRectsIds`<br/><sup class="internal">*Only used by editor*</sup> | Array&nbsp;of&nbsp;Array&nbsp;of&nbsp;Int | Array containing all the possible tile IDs rectangles (picked randomly).
 `tileXOffset`<br/><sup class="internal">*Only used by editor*</sup><br/> ![Generic badge](https://img.shields.io/badge/Added_1.3.0-gray.svg)  | Int | Tile X offset
 `tileYOffset`<br/><sup class="internal">*Only used by editor*</sup><br/> ![Generic badge](https://img.shields.io/badge/Added_1.3.0-gray.svg)  | Int | Tile Y offset
-`uid`<br/><sup class="internal">*Only used by editor*</sup> | Int | Unique Int identifier
+`uid`<br/><sup class="internal">*Only used by editor*</sup> | Int | Unique Int identifier<br/> This UID is refered from:<br/> ↖ [optionalRules](#ldtk-LayerInstanceJson;optionalRules) (Layer instance)
 `xModulo`<br/><sup class="internal">*Only used by editor*</sup> | Int | X cell coord modulo
 `xOffset`<br/><sup class="internal">*Only used by editor*</sup> | Int | X cell start offset
 `yModulo`<br/><sup class="internal">*Only used by editor*</sup> | Int | Y cell coord modulo
@@ -297,7 +297,7 @@ Value | Type | Description
 `tileRenderMode`<br/> ![Generic badge](https://img.shields.io/badge/Changed_0.8.1-gray.svg)  | Enum | An enum describing how the Entity tile is rendered inside the Entity bounds.<br/> Possible values: `Cover`, `FitInside`, `Repeat`, `Stretch`, `FullSizeCropped`, `FullSizeUncropped`, `NineSlice`
 `tilesetId` | Int&nbsp;*(can&nbsp;be&nbsp;`null`)* | Tileset ID used for optional tile display
 `uiTileRect`<br/> ![Generic badge](https://img.shields.io/badge/Added_1.4.0-gray.svg)  | [Tileset&nbsp;rectangle](#ldtk-TilesetRect)&nbsp;*(can&nbsp;be&nbsp;`null`)* | This tile overrides the one defined in `tileRect` in the UI
-`uid` | Int | Unique Int identifier
+`uid` | Int | Unique Int identifier<br/> This UID is refered from:<br/> ↖ [defUid](#ldtk-EntityInstanceJson;defUid) (Entity instance)<br/> ↖ [allowedRefsEntityUid](#ldtk-FieldDefJson;allowedRefsEntityUid) (Field definition)
 `width` | Int | Pixel width
 `allowOutOfBounds`<br/><sup class="internal">*Only used by editor*</sup><br/> ![Generic badge](https://img.shields.io/badge/Added_1.5.0-green.svg)  | Bool | If enabled, this entity is allowed to stay outside of the current level bounds
 `doc`<br/><sup class="internal">*Only used by editor*</sup><br/> ![Generic badge](https://img.shields.io/badge/Added_1.2.5-gray.svg)  | String&nbsp;*(can&nbsp;be&nbsp;`null`)* | User defined documentation for this element to provide help/tips to level designers.
@@ -341,7 +341,7 @@ Value | Type | Description
 `min`<br/><sup class="only">Only *Int, Float*</sup><br/><sup class="internal">*Only used by editor*</sup> | Float&nbsp;*(can&nbsp;be&nbsp;`null`)* | Min limit for value, if applicable
 `regex`<br/><sup class="only">Only *String*</sup><br/><sup class="internal">*Only used by editor*</sup><br/> ![Generic badge](https://img.shields.io/badge/Added_0.6.2-gray.svg)  | String&nbsp;*(can&nbsp;be&nbsp;`null`)* | Optional regular expression that needs to be matched to accept values. Expected format: `/some_reg_ex/g`, with optional "i" flag.
 `type`<br/><sup class="internal">*Only used by editor*</sup> | String | Internal enum representing the possible field types. Possible values: F_Int, F_Float, F_String, F_Text, F_Bool, F_Color, F_Enum(...), F_Point, F_Path, F_EntityRef, F_Tile
-`uid`<br/><sup class="internal">*Only used by editor*</sup> | Int | Unique Int identifier
+`uid`<br/><sup class="internal">*Only used by editor*</sup> | Int | Unique Int identifier<br/> This UID is refered from:<br/> ↖ [defUid](#ldtk-FieldInstanceJson;defUid) (Field instance)<br/> ↖ [biomeFieldUid](#ldtk-LayerDefJson;biomeFieldUid) (Layer definition)
 `allowOutOfLevelRef`<br/><sup class="internal">*Only used by editor*</sup><br/> ![Generic badge](https://img.shields.io/badge/Added_1.0.0-gray.svg)  | Bool | 
 `allowedRefTags`<br/><sup class="internal">*Only used by editor*</sup><br/> ![Generic badge](https://img.shields.io/badge/Added_1.0.0-gray.svg)  | Array&nbsp;of&nbsp;String | 
 `allowedRefs`<br/><sup class="internal">*Only used by editor*</sup><br/> ![Generic badge](https://img.shields.io/badge/Added_1.0.0-gray.svg)  | Enum | Possible values: `Any`, `OnlySame`, `OnlyTags`, `OnlySpecificEntity`
@@ -384,7 +384,7 @@ Value | Type | Description
 `tags`<br/> ![Generic badge](https://img.shields.io/badge/Added_1.0.0-gray.svg)  | Array&nbsp;of&nbsp;String | An array of user-defined tags to organize the Tilesets
 `tagsSourceEnumUid`<br/><sup class="uidRef">UID ref to [Enum definition](#ldtk-EnumDefJson)</sup><br/> ![Generic badge](https://img.shields.io/badge/Added_0.9.0-gray.svg)  | Int&nbsp;*(can&nbsp;be&nbsp;`null`)* | Optional Enum definition UID used for this tileset meta-data
 `tileGridSize` | Int | 
-`uid` | Int | Unique Intidentifier
+`uid` | Int | Unique Intidentifier<br/> This UID is refered from:<br/> ↖ [overrideTilesetUid](#ldtk-LayerInstanceJson;overrideTilesetUid) (Layer instance)<br/> ↖ [tilesetDefUid](#ldtk-LayerDefJson;tilesetDefUid) (Layer definition)<br/> ↖ [autoTilesetDefUid](#ldtk-LayerDefJson;autoTilesetDefUid) (Layer definition)<br/> ↖ [tilesetUid](#ldtk-FieldDefJson;tilesetUid) (Field definition)<br/> ↖ [tilesetUid](#ldtk-TilesetRect;tilesetUid) (Tileset rectangle)<br/> ↖ [iconTilesetUid](#ldtk-EnumDefJson;iconTilesetUid) (Enum definition)
 `cachedPixelData`<br/><sup class="internal">*Only used by editor*</sup><br/> ![Generic badge](https://img.shields.io/badge/Added_0.6.0-gray.svg)  | Object&nbsp;*(can&nbsp;be&nbsp;`null`)* | The following data is used internally for various optimizations. It's always synced with source image changes.<br/> This object contains the following fields:<br/> <ul class='subFields'><li>**`averageColors`** **(String *(can be `null`)***)  ![Generic badge](https://img.shields.io/badge/Added_0.6.0-gray.svg)  : *Average color codes for each tileset tile (ARGB format)*</li><li>**`opaqueTiles`** **(String**)  ![Generic badge](https://img.shields.io/badge/Changed_0.6.0-gray.svg)  : *An array of 0/1 bytes, encoded in Base64, that tells if a specific TileID is fully opaque (1) or not (0)*</li></ul>
 `savedSelections`<br/><sup class="internal">*Only used by editor*</sup> | Array&nbsp;of&nbsp;Object | Array of group of tiles selections, only meant to be used in the editor<br/> This array contains objects with the following fields:<br/> <ul class='subFields'><li>**`ids`** **(Array of Int**)</li><li>**`mode`** **(Enum**)</li></ul>
 
@@ -408,7 +408,7 @@ Value | Type | Description
 `iconTilesetUid`<br/><sup class="uidRef">UID ref to [Tileset definition](#ldtk-TilesetDefJson)</sup> | Int&nbsp;*(can&nbsp;be&nbsp;`null`)* | Tileset UID if provided
 `identifier` | String | User defined unique identifier
 `tags`<br/> ![Generic badge](https://img.shields.io/badge/Added_1.0.0-gray.svg)  | Array&nbsp;of&nbsp;String | An array of user-defined tags to organize the Enums
-`uid` | Int | Unique Int identifier
+`uid` | Int | Unique Int identifier<br/> This UID is refered from:<br/> ↖ [tagsSourceEnumUid](#ldtk-TilesetDefJson;tagsSourceEnumUid) (Tileset definition)
 `values` | Array&nbsp;of&nbsp;[Enum&nbsp;value&nbsp;definition](#ldtk-EnumDefValues) | All possible enum values, with their optional Tile infos.
 `externalFileChecksum`<br/><sup class="internal">*Only used by editor*</sup> | String&nbsp;*(can&nbsp;be&nbsp;`null`)* | 
 

diff --git a/src/docGenerator/DocGenerator.hx b/src/docGenerator/DocGenerator.hx
@@ -78,6 +78,7 @@ class DocGenerator {
 	#if( macro || display )
 	static var allGlobalTypes: Array<GlobalType>;
 	static var uidRoots: Map<String, { globalType:GlobalType, field:FieldInfos }>;
+	static var uidRefs: Map<String, Array<{ globalType:GlobalType, field:FieldInfos }>>;
 	static var allEnums : Map<String, Array<String>>;
 	static var verbose = false;
 	static var appVersion = new dn.Version();
@@ -89,6 +90,7 @@ class DocGenerator {
 		allGlobalTypes = [];
 		allEnums = [];
 		uidRoots = new Map();
+		uidRefs = new Map();
 
 		// Read app version from "package.json"
 		haxe.macro.Context.registerModuleDependency("DocGenerator", "app/package.json");
@@ -174,6 +176,18 @@ class DocGenerator {
 				}
 		}
 
+		// List all UID refs
+		for(gt in allGlobalTypes) {
+			var allFields = getFieldsInfos(gt.xml.node.a);
+			for(f in allFields) {
+				if( f.uidRef==null )
+					continue;
+				if( !uidRefs.exists(f.uidRef) )
+					uidRefs.set(f.uidRef, []);
+				uidRefs.get(f.uidRef).push( { globalType:gt, field:f } );
+			}
+		}
+
 		// Markdown doc output
 		Sys.println("Generating Markdown doc...");
 		genMarkdownDoc(xml, className, xmlPath, mdPath);
@@ -327,6 +341,15 @@ class DocGenerator {
 							cell.push("This object contains the following fields:");
 						cell.push( getSubFieldsHtml( f.subFields ) );
 					}
+					if( f.uidRoot!=null && uidRefs.exists(f.uidRoot) ) {
+						var allRefLinks = [];
+						// trace(f.displayName);
+						for(ref in uidRefs.get(f.uidRoot)) {
+							var refUrl = '[${ref.field.displayName}](#${anchorId(ref.globalType.rawName)};${ref.field.displayName}) (${ref.globalType.displayName})';
+							allRefLinks.push(refUrl);
+						}
+						cell.push('This UID is refered from:<br/> ↖ ${allRefLinks.join("<br/> ↖ ")}');
+					}
 					tableCols.push( cell.join("<br/> ") );
 				}