diff --git a/docs/Developers/Managers/animation-manager.md b/docs/Developers/Managers/animation-manager.md index 3198c584..b29903e6 100644 --- a/docs/Developers/Managers/animation-manager.md +++ b/docs/Developers/Managers/animation-manager.md @@ -12,6 +12,7 @@ Manages animations for a character, including loading, playing, and controlling Properties are not meant to be edited directly they are modified with methods. - `animationPaths` + - `defaultAnimationPaths` - `lastAnimID` - `mainControl` - `animationControl` diff --git a/docs/Modders/getting-started.md b/docs/Modders/getting-started.md new file mode 100644 index 00000000..51affa4a --- /dev/null +++ b/docs/Modders/getting-started.md @@ -0,0 +1,402 @@ +--- +sidebar_position: 1 +--- + +# Getting Started with Manifest Files + +This guide will help you set up your first character collection for Character Studio. We'll walk through creating a manifest file that tells the studio how to display and organize your 3D models, textures, and other assets. + +## What is a Manifest File? + +A manifest file is like a recipe that tells Character Studio: +- Where to find your 3D models and textures +- How to organize them into categories (like body, clothing, hair) +- How they should interact with each other (like clothes covering the body) +- What colors and textures can be applied + +## Creating Your First Manifest File + +### Step 1: Create a New Text File + +1. Open your favorite text editor (like Notepad, TextEdit, or VS Code) +2. Create a new file +3. Save it as `manifest.json` (make sure to include the `.json` extension) + +### Step 2: Basic Structure + +Copy and paste this basic structure into your file: + +```json +{ + "assetsLocation": "/character-assets", + "traitsDirectory": "/your-collection/", + "thumbnailsDirectory": "/your-collection/", + "format": "vrm", + "displayScale": 1.0, + "traits": [] +} +``` + +### Step 3: Organize Your Files + +Create these folders in your project: +``` +character-assets/ +└── your-collection/ + ├── BODY/ + │ ├── female.vrm + │ └── female.png + ├── CLOTHING/ + │ ├── dress.vrm + │ └── dress.png + ├── HAIR/ + │ ├── long.vrm + │ └── long.png + └── icons/ + └── body.svg +``` + +### Step 4: Add Your First Trait + +Let's add a body trait. Replace the empty `"traits": []` with: + +```json +"traits": [ + { + "trait": "BODY", + "name": "Body", + "iconSvg": "icons/body.svg", + "cullingLayer": 0, + "cameraTarget": { + "distance": 0.75, + "height": 1.35 + }, + "collection": [ + { + "id": "FEMALE", + "name": "Female", + "directory": "BODY/female.vrm", + "thumbnail": "BODY/female.png" + } + ] + } +] +``` + +### Step 5: Add More Traits + +Add clothing and hair traits following the same pattern: + +```json +"traits": [ + { + "trait": "BODY", + "name": "Body", + "iconSvg": "icons/body.svg", + "cullingLayer": 0, + "cameraTarget": { + "distance": 0.75, + "height": 1.35 + }, + "collection": [ + { + "id": "FEMALE", + "name": "Female", + "directory": "BODY/female.vrm", + "thumbnail": "BODY/female.png" + } + ] + }, + { + "trait": "CLOTHING", + "name": "Clothing", + "iconSvg": "icons/clothing.svg", + "cullingLayer": 1, + "cameraTarget": { + "distance": 1.0, + "height": 1.0 + }, + "collection": [ + { + "id": "DRESS", + "name": "Dress", + "directory": "CLOTHING/dress.vrm", + "thumbnail": "CLOTHING/dress.png" + } + ] + }, + { + "trait": "HAIR", + "name": "Hair", + "iconSvg": "icons/hair.svg", + "cullingLayer": 2, + "cameraTarget": { + "distance": 0.5, + "height": 1.5 + }, + "collection": [ + { + "id": "LONG", + "name": "Long", + "directory": "HAIR/long.vrm", + "thumbnail": "HAIR/long.png" + } + ] + } +] +``` + +### Step 6: Add Colors and Textures + +Add color, texture and decal options + +```json +"colorCollections": [ + { + "trait": "HAIR_COLORS", + "collection": [ + { + "id": "BLACK", + "name": "Black", + "value": ["#000000"] + }, + { + "id": "BROWN", + "name": "Brown", + "value": ["#8B4513"] + } + ] + } +], +"textureCollections": [ + { + "trait": "CLOTH_COLORS", + "collection": [ + { + "id": "LIGHT", + "name": "Light", + "directory": "textures/skin_light.png", + "thumbnail": "textures/skin_light_thumb.png" + }, + { + "id": "MEDIUM", + "name": "Medium", + "directory": "textures/skin_medium.png", + "thumbnail": "textures/skin_medium_thumb.png" + } + ] + } +], +"decalCollections": [ + { + "trait": "TATTOOS", + "collection": [ + { + "id": "TATTOO", + "name": "tattoo", + "directory": "decals/tattoo.png", + "thumbnail": "decals/tattoo.png" + }, + { + "id": "TATTOO_2", + "name": "tattoo 2", + "directory": "decals/tattoo_2.png", + "thumbnail": "decals/tattoo_2.png" + } + ] + } +] +``` +### Step 7: Connect to model traits + +Go back to traits and connect decals to desired trait model, example: +```json +{ + "id": "FEMALE", + "name": "Female", + "directory": "BODY/female.vrm", + "thumbnail": "BODY/female.png", + "textureCollection":"SKIN_TONES", + "decalCollection":"TATTOOS" +} +... +{ + "id": "DRESS", + "name": "Dress", + "directory": "CLOTHING/dress.vrm", + "thumbnail": "CLOTHING/dress.png", + "colorCollection":"CLOTH_COLORS", +} + +``` + +### Step 8: Save and Test + +1. Save your `manifest.json` file +2. Place it in your `character-assets` folder +3. Load it in Character Studio to test + +## Adding Your Collection to Character Studio + +Now that you've created your character collection manifest, you need to add it to the main manifest file that Character Studio uses to load all available collections. + +### Step 1: Find the Main Manifest File + +The main manifest file is located at: +``` +CharacterStudio/public/manifest.json +``` + +### Step 2: Add Your Collection + +Open the main manifest file and add your collection to the `collections` array. Here's an example: + +```json +{ + "characters":[ + { + "id": "your-collection", + "name": "Your Collection Name", + "description": "A brief description of your collection", + "thumbnail": "your-collection/thumbnail.png", + "manifest": "your-collection/manifest.json", + "authors": ["Your Name"], + "version": "1.0" + } + ] +} +``` + +### Step 3: Required Fields + +- `id`: A unique identifier for your collection (use lowercase, no spaces) +- `name`: The display name of your collection +- `description`: A brief description of what's in your collection +- `thumbnail`: Path to your collection's thumbnail image +- `manifest`: Path to your collection's manifest file +- `authors`: Array of author names +- `version`: Version number of your collection + +### Step 4: Example with Multiple Collections + +Here's how the main manifest might look with multiple collections: + +```json +{ + "collections": [ + { + "id": "other-collection", + "name": "Other Collection", + "description": "A collection of anime-style characters", + "thumbnail": "other/thumbnail.png", + "manifest": "other/manifest.json", + "authors": ["Artist Name"], + "version": "1.0" + }, + { + "id": "your-collection", + "name": "Your Collection Name", + "description": "A brief description of your collection", + "thumbnail": "your-collection/thumbnail.png", + "manifest": "your-collection/manifest.json", + "authors": ["Your Name"], + "version": "1.0" + } + ] +} +``` + +## Additional Manifest Sections + +The main manifest file (`CharacterStudio/public/manifest.json`) can include several optional sections that provide additional functionality for all character collections: + +### 1. LoRAs (Low-Rank Adaptations) +This section defines how to capture images for training AI models with your characters. It includes: +- Camera angles and positions +- Lighting setups +- Background requirements +- Image resolution and format specifications + +For more details, see the [LoRA Documentation](./manifest-files/vrm-to-lora.md). + +### 2. Sprites +This section defines how to generate sprite sheets from your 3D characters. It includes: +- Animation sequences to capture +- Camera settings for each pose +- Output format and resolution +- Background and lighting requirements + +For more details, see the [Sprite Sheet Documentation](./manifest-files/vrm-to-spritesheet.md). + +### 3. Thumbnails +This section defines how to generate thumbnails for your character assets. It includes: +- Camera positions for different trait types +- Lighting setups +- Background colors +- Output resolution and format + +For more details, see the [Thumbnail Documentation](./manifest-files/vrm-to-thumbnails). + +### 4. Default Animations +This section provides a set of default animations that can be used by all character collections. It includes: +- Common animation sequences (idle, walk, run, etc.) +- Animation file locations +- Animation descriptions and usage notes + +For more details, see the [Animation Documentation](./character-traits.md#animationpath). + +## Tips for Artists + +### File Organization +- Keep your files organized in clear folders +- Use descriptive names for your files +- Include thumbnails for all your 3D models +- Create simple SVG icons for each category + +### 3D Models +- Export your models in VRM format +- Make sure your models are properly scaled +- Test your models in Character Studio before adding them to the manifest + +### Textures and Colors +- Use PNG format for textures +- Keep texture sizes reasonable (2048x2048 is usually enough) +- Use web-safe colors for color options + +### Culling Layers +- Base body should be layer 0 +- Clothing should be layer 1 +- Accessories should be layer 2 or higher +- Use -1 for things that shouldn't cull (like hair) + +## Common Issues and Solutions + +### My models don't show up +- Check if the file paths in the manifest match your folder structure +- Make sure your VRM files are properly exported +- Verify that the file names match exactly (including case) + +### Textures look wrong +- Check if your texture files are in the correct format (PNG) +- Verify the texture paths in the manifest +- Make sure your UV maps are correct + +### Colors don't apply +- Check if the color values are in the correct format (#RRGGBB) +- Verify that the trait IDs match between traits and color collections + +### Collection doesn't appear in Character Studio +- Make sure your collection is properly added to the main manifest file +- Verify that all paths in the main manifest are correct +- Check that your collection's manifest file is in the right location + +## Next Steps + +1. Test your manifest with a few basic traits +2. Add more options to each category +3. Experiment with different culling layers +4. Add more color and texture options +5. Add your collection to the main manifest file +6. Explore additional manifest sections for LoRAs, sprites, and animations + +For more detailed information about each field, refer to the [Character Traits Documentation](./character-traits.md). \ No newline at end of file diff --git a/docs/Modders/change-animations.md b/docs/Modders/manifest-files/character-animations.md similarity index 65% rename from docs/Modders/change-animations.md rename to docs/Modders/manifest-files/character-animations.md index 851d39f9..0c5f0b45 100644 --- a/docs/Modders/change-animations.md +++ b/docs/Modders/manifest-files/character-animations.md @@ -1,4 +1,42 @@ -# Change animations +# Character animations +There are 2 ways to add animations to characters: + +## Default animations + +The animation files are referenced via main manifest in the defaultAnimations array section. You can add as many as you want, and all the loaded characters will have these animations: + +```json! +{ + "defaultAnimations":[ + { + "name": "T-Pose", + "description": "1_T-Pose", + "location":"./animations/T-Pose.fbx", + "icon": "|" + }, + { + "name": "Idle", + "description": "Basic Dance Animation", + "location":"./animations/2_Idle.fbx", + "icon": "|" + }, + { + "name": "Walking", + "description": "Basic Walk Animation", + "location":"./animations/3_Walking.fbx", + "icon": "|" + }, + { + "name": "Waving", + "description": "Basic Waving Animation", + "location":"./animations/4_Waving.fbx", + "icon": "|" + } + ] +} +``` + +## Per character animations The animation files are referenced via `animationPath` in the manifest.json file, here's an example ([source](https://github.com/M3-org/loot-assets/blob/main/loot/models/manifest.json)): diff --git a/docs/Modders/manifest-files/character-traits.md b/docs/Modders/manifest-files/character-traits.md index a76a30ca..8f48244a 100644 --- a/docs/Modders/manifest-files/character-traits.md +++ b/docs/Modders/manifest-files/character-traits.md @@ -59,7 +59,7 @@ Alternative subfolder location where thumbnails for traits will be loaded from: Example: ```json -"traitsDirectory":"/traitsThumbnails/" +"thumbnailsDirectory":"/traitsThumbnails/" ``` Character studio will search on assetLocation + thumbnailsDirectory: @@ -70,17 +70,17 @@ Character studio will search on assetLocation + thumbnailsDirectory: ### traitIconsDirectorySvg *optional string* -Alternative subfolder location where thumbnails for traits will be loaded from: +Alternative subfolder location where SVG icons for traits will be loaded from: Example: ```json -"traitsDirectory":"/traitsThumbnails/" +"traitIconsDirectorySvg":"/traitIcons/" ``` -Character studio will search on assetLocation + thumbnailsDirectory: +Character studio will search on assetLocation + traitIconsDirectorySvg: -```./character-assets/traitThumbnails/``` +```./character-assets/traitIcons/``` ### animationPath *optional string array* @@ -106,6 +106,29 @@ Example: "displayScale":0.7 ``` +### exportScale +*optional number* + +Scale value for the exported model, default is 1 + +Example: +```json +"exportScale":0.7 +``` + +### initialTraits +*optional object* + +Initial traits that will be selected when the character is loaded. Keys are trait group IDs and values are trait IDs. + +Example: +```json +"initialTraits": { + "BODY": "Feminine", + "CLOTHING": "Dress" +} +``` + ### requiredTraits *optional string array* @@ -119,7 +142,7 @@ Example: ### randomTraits *optional string array* -Trait group names that will be randomized when clicking ransomize button. Trait group names are defined inside trait collections. +Trait group names that will be randomized when clicking randomize button. Trait group names are defined inside trait collections. Example: ```json @@ -226,161 +249,141 @@ Example: "offset":[0.0,0.1,0.0] ``` -___ - -## download options -*optional object data* - -Includes export download options for final downloaded 3d model. - -```json -"downloadOptions":{ - - ...(options from below) -} -``` - -### scale -*optional number* +### canDownload +*optional boolean* -Default export scale value for character when downloading, default is 1 +Whether the character can be downloaded. Default is true. Example: ```json -"scale":0.7 +"canDownload": false ``` -### exportStdAtlas -*optional boolean* +### downloadOptions +*optional object* -should final model export standard material? default is False +Includes export download options for final downloaded 3d model. -Example: ```json -"exportStdAtlas":true +"downloadOptions":{ + "scale": 0.7, + "exportStdAtlas": true, + "exportMtoonAtlas": true, + "mToonAtlasSize": 2048, + "mToonAtlasSizeTransp": 2048, + "stdAtlasSize": 2048, + "stdAtlasSizeTransp": 2048, + "screenshotFaceDistance": 1.0, + "screenshotFaceOffset": [0, 0, 0], + "screenshotResolution": [512, 512], + "screenshotBackground": [0.1, 0.1, 0.1], + "screenshotFOV": 75 +} ``` -### exportMtoonAtlas -*optional boolean* +### vrmMeta +*optional object* -should final model export mToon material? default is True +Metadata that will be saved to final VRM file after download happens. Example: ```json -"exportMtoonAtlas":true +"vrmMeta":{ + "authors":["Author Name"], + "version":"v1", + "commercialUssageName": "personalNonProfit", + "contactInformation": "https://example.com/", + "allowExcessivelyViolentUsage":false, + "allowExcessivelySexualUsage":false, + "allowPoliticalOrReligiousUsage":false, + "allowAntisocialOrHateUsage":false, + "creditNotation":"required", + "allowRedistribution":false, + "modification":"prohibited" +} ``` -### mToonAtlasSize -*optional number* +### chainName +*optional string* -Atlas size for final mToon atlas download image, default is 2048 (use square numbers) +Name of the blockchain chain for NFT integration. Example: ```json -"mToonAtlasSize":4096 +"chainName": "ethereum" ``` +### collectionLockID +*optional string* -### mToonAtlasSizeTransp -*optional number* - -Atlas size for final transparent mToon atlas download image, default is 2048 (use square numbers) +ID for locking the collection. Example: ```json -"mToonAtlasSizeTransp":4096 +"collectionLockID": "my-collection-123" ``` -### stdAtlasSize -*optional number* +### dataSource +*optional string* -Atlas size for final standard atlas material download image, default is 2048 (use square numbers) +Source of the data for the collection. ("attributes", "image", "none") Example: ```json -"stdAtlasSize":4096 +"dataSource": "attributes" ``` -### stdAtlasSizeTransp -*optional number* +### solanaPurchaseAssets +*optional object* -Atlas size for final transparent standard atlas material download image, default is 2048 (use square numbers) +Configuration for Solana purchase assets. Example: ```json -"stdAtlasSizeTransp":4096 +"solanaPurchaseAssets": { + "collectionAddress": "Add", + "merkleTreeAddress":"AnrgANw3znNQ52TyAmBth7kqeTxbacyS8bWwezS6XP9J" +} ``` - -### screenshotFaceDistance +### price *optional number* -Distance the camera will take a portrait screenshot for portrait image, default is 1 +Default price all assets of the character in the specified currency. Example: ```json -"screenshotFaceDistance":0.8 +"price": 10.99 ``` -### screenshotFaceOffset -*optional array[3] number* - -Set an offset value (x,y,z) to the camera face screenshot. - -Example: -```json -"screenshotFaceOffset":[0,0.1,0] -``` -### screenshotResolution -*optional array[2] number* +### currency +*optional string* -Set the resolution of final portrait image of downloaded vrm, default is [512,512] (use square numbers) +Currency for the price. Example: ```json -"screenshotResolution":[256,256] +"currency": "USD" ``` -### screenshotBackground -*optional array[3] number* -Sets a background color for the portrait image (rgb). values are from 0 to 1. default is [0.1,0.1,0.1] - -Example: -```json -"screenshotBackground":[0.8,0.8,0.8] -``` -### screenshotFOV -*optional number* +### purchasable +*optional boolean* -Set camera FOV for vrm portrait screenshot. Default is 75. +Whether the default value of the assets is set to purchsable or not Example: ```json -"screenshotFOV":80 +"purchasable": true ``` +### locked +*optional boolean* - -### vrmMeta -*optional object data* - -Metadata that will be saved to final VRM file after download happens. +Whether the default value of the assets is set to locked or not Example: ```json -"vrmMeta":{ - "authors":["Memelotsqui"], - "version":"v1", - "commercialUssageName": "personalNonProfit", - "contactInformation": "https://example.com/", - "allowExcessivelyViolentUsage":false, - "allowExcessivelySexualUsage":false, - "allowPoliticalOrReligiousUsage":false, - "allowAntisocialOrHateUsage":false, - "creditNotation":"required", - "allowRedistribution":false, - "modification":"prohibited" -} +"locked": false ``` ___ @@ -426,7 +429,7 @@ Display name for this group trait. Example: ```json -"trait":"Skin" +"name":"Skin" ``` ### iconSvg @@ -609,7 +612,7 @@ ___ Used to define a collections of colors that can be assigned to specific traits. ```json - "textureCollections": [ + "colorCollections": [ { "trait": "SKIN_COLORS", "collection": [...] @@ -637,6 +640,43 @@ An array of all the textures that will be available for this texture trait id. ] ``` +___ + +## Decal Collection Section (decalCollections): +Used to define a collections of decals that can be assigned to specific traits. + +```json + "decalCollections": [ + { + "trait": "DECALS", + "collection": [...] + } +] +``` + +### collection (decals) + +An array of all the decals that will be available for this decal trait id. + +**id *(required string)***: Unique ID for this decal trait (can be used by nft metadata to fetch this value by id). + +**name *(optional string)***: Display Name for this decal trait. + +**directory *(required string)***: Relative location of the decal texture file. + +**thumbnail *(optional string)***: Relative location of the thumbnail for this decal. + +```json +"collection": [ + { + "id": "STAR_DECAL", + "name": "Star", + "directory": "decals/star.png", + "thumbnail": "decals/star_thumb.png" + } +] +``` + ___ # Culling Distance diff --git a/docs/Modders/manifest-files/vrm-to-thumbnails.md b/docs/Modders/manifest-files/vrm-to-thumbnails.md new file mode 100644 index 00000000..2da246ba --- /dev/null +++ b/docs/Modders/manifest-files/vrm-to-thumbnails.md @@ -0,0 +1,43 @@ +--- +sidebar_position: 6 +--- + +# VRM to Thumbnails + +The thumbnails generator allows you to create thumbnails with the assets that will be loaded in each trait group. + +A single image for each asset will be taken and saved into disk with trait groups subdirectories. You can use these generated thumbnails to update your character manifest.json. + +--- + +Example: + + +```json +{ + "poseAnimation": "/Idle.fbx", + "animationTime":0, + "backgroundColor":[0,0,0,0], + "screenshotOffset":[0,0], + "topFrameOffset":0.1, + "bottomFrameOffset":0.1, + "thumbnailsWidth":512, + "thumbnailsHeight":512, + "thumbnailsCollection":[ + { + "traitGroup":"CLOTHING", + "cameraPosition":"front-left", + "cameraFrame":"mediumShot", + "groupTopOffset":0.1, + "groupBotomOffset":0.1 + }, + { + "traitGroup":"HAIR", + "cameraPosition":"front-left", + "cameraFrame":"mediumShot", + "groupTopOffset":0.1, + "groupBotomOffset":0.1 + } + ] +} +``` diff --git a/sidebars.js b/sidebars.js index 1ad8457f..064f443e 100644 --- a/sidebars.js +++ b/sidebars.js @@ -15,13 +15,14 @@ const sidebars = { type: 'category', label: 'Modders', items: [ + 'Modders/getting-started', { type: 'link', label: 'Sample Files', href: 'https://github.com/m3-org/loot-assets' }, 'Modders/process-avatars', - 'Modders/change-animations', + { type: 'category', label: 'Manifest Files', @@ -29,8 +30,10 @@ const sidebars = { 'Modders/manifest-files/overview', 'Modders/manifest-files/character-select', 'Modders/manifest-files/character-traits', + 'Modders/manifest-files/character-animations', 'Modders/manifest-files/vrm-to-lora', 'Modders/manifest-files/vrm-to-spritesheet', + 'Modders/manifest-files/vrm-to-thumbnails', 'Modders/manifest-files/ai-personalities', 'Modders/manifest-files/generate-manifest-files', ]