├── .gitignore ├── README.md ├── data ├── avatar-tags.json ├── avatars.json ├── avatars.json.backup ├── download-counts.json ├── projects.json ├── tags.json ├── test-connection-test-2025-03-11T08:11:23.959Z-5x30xgms.json ├── test-connection.json └── users.json ├── docs ├── README.md ├── api-reference.md ├── avatar-format.md ├── contributing │ └── technical-requirements.md ├── faq.md └── technical-guide.md └── download-counts.json /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | .AppleDouble 3 | .LSOverride 4 | 5 | # Icon must end with two \r 6 | Icon 7 | 8 | # Thumbnails 9 | ._* 10 | 11 | # Files that might appear in the root of a volume 12 | .DocumentRevisions-V100 13 | .fseventsd 14 | .Spotlight-V100 15 | .TemporaryItems 16 | .Trashes 17 | .VolumeIcon.icns 18 | .com.apple.timemachine.donotpresent 19 | 20 | # Directories potentially created on remote AFP share 21 | .AppleDB 22 | .AppleDesktop 23 | Network Trash Folder 24 | Temporary Items 25 | .apdisk -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Open Source Avatars 2 | 3 |
4 |

🌐 opensourceavatars.com

5 |

A community-driven gallery of free 3D avatars for the metaverse

6 |
7 | 8 | ## 🌟 What is Open Source Avatars? 9 | 10 | Open Source Avatars (OSA) is a growing collection of freely available 3D avatars primarily in VRM format for use in virtual reality, gaming, metaverse applications, and any other 3D environments. Our mission is to create an inclusive library of high-quality avatars that anyone can use without worrying about licensing restrictions. 11 | 12 | This repository serves as the **data backbone** for the [Open Source Avatars website](https://www.opensourceavatars.com), containing all the metadata and information about the avatars, projects, and related resources. 13 | 14 | ### What is VRM? 15 | 16 | VRM is an open file format for 3D humanoid avatars primarily used in VR applications. Key features include: 17 | 18 | - **Cross-platform compatibility** across different applications and engines 19 | - **Standardized rigging** making animations work consistently 20 | - **Customizable expressions** for facial animations 21 | - **Material definitions** that work across different rendering systems 22 | 23 | VRM files can be viewed and used with libraries like [Three.js](https://threejs.org/) and applications like [VRoid Studio](https://vroid.com/en/studio) or [Pixiv's VRoid Mobile](https://vroid.com/en/mobile). 24 | 25 | ## 🚀 Why Open Source Avatars? 26 | 27 | - **Free and accessible 3D avatars** for everyone 28 | - **Permissive licensing** that allows for personal and commercial use 29 | - **Community-driven** development and contributions 30 | - **Diverse selection** of avatar styles, characters, and designs 31 | - **Compatible formats** for popular platforms and engines 32 | 33 | ## 📂 What's in this Repository? 34 | 35 | This repository is structured as a database with JSON files containing all the metadata: 36 | 37 | - `/data` - The core data directory 38 | - `avatars.json` - Detailed information about each avatar (3D models stored on Arweave) 39 | - `projects.json` - Collections of related avatars 40 | - `tags.json` - Categories and tags for organizing avatars 41 | - `users.json` - Creator and contributor information 42 | - `downloads.json` - Usage statistics 43 | - `avatar-tags.json` - Tagging relationships 44 | 45 | ### 🔍 Exploring the Avatars 46 | 47 | Rather than browsing the JSON files directly, we recommend visiting our gallery at [opensourceavatars.com](https://www.opensourceavatars.com) for an interactive experience with: 48 | 49 | - Visual previews and thumbnails 50 | - 3D model viewers 51 | - Filtering by tags, style, and format 52 | - Download options for different platforms 53 | - Creator information and attribution 54 | 55 | 56 | 57 | ## 🔧 How to Use This Avatars 58 | 59 | ### For 3D Artists and Avatar Users 60 | 61 | Visit [opensourceavatars.com](https://www.opensourceavatars.com) for a user-friendly interface to: 62 | 63 | - Browse and search for avatars 64 | - Preview models in 3D before downloading 65 | - Download in various formats (VRM, FBX, etc.) 66 | 67 | ### For Developers 68 | 69 | 1. **Direct API Access**: Access the data via GitHub's raw content: 70 | ``` 71 | https://raw.githubusercontent.com/ToxSam/open-source-avatars/main/data/avatars.json 72 | ``` 73 | 74 | 2. **Clone the Repository**: 75 | ```bash 76 | git clone https://github.com/ToxSam/open-source-avatars.git 77 | ``` 78 | 79 | 3. **Integrate with Your Project**: 80 | - Use the well-structured JSON data in your applications 81 | - Access the 3D models directly via the Arweave links 82 | - Build your own avatar selection interface 83 | 84 | 85 | 86 | ### Technical Requirements 87 | 88 | To work with VRM files in your own projects, you'll typically need: 89 | 90 | - **For web applications**: Three.js with [three-vrm](https://github.com/pixiv/three-vrm) plugin 91 | - **For Unity**: [UniVRM](https://github.com/vrm-c/UniVRM) package 92 | - **For Unreal Engine**: [VRM4U](https://github.com/ruyo/VRM4U) plugin 93 | - **For viewing/editing**: VRoid Studio, Blender (with VRM add-on), or other 3D tools 94 | 95 | ## 📊 Data Structure 96 | 97 | Each avatar in our collection includes rich metadata such as: 98 | 99 | ```json 100 | { 101 | "id": "unique-identifier", 102 | "name": "Avatar Name", 103 | "description": "A detailed description of the avatar", 104 | "thumbnailUrl": "https://assets.opensourceavatars.com/...", 105 | "modelFileUrl": "https://arweave.net/...", 106 | "format": "vrm", 107 | "polygonCount": 12500, 108 | "materialCount": 8, 109 | "metadata": { 110 | "alternateModels": { 111 | "voxel_vrm": "https://arweave.net/...", 112 | "fbx": "https://arweave.net/..." 113 | }, 114 | "license": "CC-BY-4.0", 115 | "creator": "Creator Name", 116 | "attributes": { 117 | "height": 1.7, 118 | "style": "anime" 119 | } 120 | } 121 | } 122 | ``` 123 | 124 | 125 | ## 💻 Quick Start Guide 126 | 127 | ### Web Applications 128 | 129 | 1. **Install Dependencies** 130 | ```bash 131 | # Using npm 132 | npm install @pixiv/three-vrm three 133 | 134 | # Using yarn 135 | yarn add @pixiv/three-vrm three 136 | ``` 137 | 138 | 2. **Basic Implementation** 139 | ```javascript 140 | import * as THREE from 'three'; 141 | import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader'; 142 | import { VRMLoaderPlugin } from '@pixiv/three-vrm'; 143 | 144 | // Create a basic Three.js scene 145 | const scene = new THREE.Scene(); 146 | const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000); 147 | const renderer = new THREE.WebGLRenderer(); 148 | renderer.setSize(window.innerWidth, window.innerHeight); 149 | document.body.appendChild(renderer.domElement); 150 | 151 | // Set up lighting 152 | const light = new THREE.DirectionalLight(0xffffff); 153 | light.position.set(0, 1, 1).normalize(); 154 | scene.add(light); 155 | 156 | // Load an avatar 157 | const loader = new GLTFLoader(); 158 | loader.registerPlugin(new VRMLoaderPlugin()); 159 | 160 | // Fetch avatar data 161 | fetch('https://raw.githubusercontent.com/ToxSam/open-source-avatars/main/data/avatars.json') 162 | .then(response => response.json()) 163 | .then(avatars => { 164 | const avatar = avatars[0]; // Get first avatar for example 165 | loader.load( 166 | avatar.modelFileUrl, 167 | (gltf) => { 168 | const vrm = gltf.userData.vrm; 169 | scene.add(vrm.scene); 170 | 171 | // Position camera 172 | camera.position.z = 2; 173 | 174 | // Animation loop 175 | function animate() { 176 | requestAnimationFrame(animate); 177 | renderer.render(scene, camera); 178 | } 179 | animate(); 180 | }, 181 | (progress) => console.log('Loading:', (progress.loaded / progress.total * 100) + '%'), 182 | (error) => console.error('Error loading VRM:', error) 183 | ); 184 | }); 185 | ``` 186 | 187 | ### Unity Integration 188 | 189 | 1. **Install UniVRM** 190 | - Open Package Manager (Window > Package Manager) 191 | - Click '+' > Add package from git URL 192 | - Enter: `https://github.com/vrm-c/UniVRM.git?path=/Assets/VRMShaders` 193 | - Repeat for: `https://github.com/vrm-c/UniVRM.git?path=/Assets/VRM` 194 | 195 | 2. **Basic Usage** 196 | ```csharp 197 | using UnityEngine; 198 | using VRM; 199 | 200 | public class VRMLoader : MonoBehaviour 201 | { 202 | async void Start() 203 | { 204 | // Load avatar from URL 205 | var avatarUrl = "https://arweave.net/your-avatar-url"; 206 | using (var webRequest = UnityWebRequest.Get(avatarUrl)) 207 | { 208 | await webRequest.SendWebRequest(); 209 | 210 | if (webRequest.result == UnityWebRequest.Result.Success) 211 | { 212 | var bytes = webRequest.downloadHandler.data; 213 | var context = new VRMImporterContext(); 214 | 215 | // Load VRM model 216 | await context.LoadAsync(bytes); 217 | var gameObject = context.Root; 218 | 219 | // Add to scene 220 | gameObject.transform.SetParent(transform, false); 221 | } 222 | } 223 | } 224 | } 225 | ``` 226 | 227 | ### Unreal Engine Setup 228 | 229 | 1. **Install VRM4U Plugin** 230 | - Open Epic Games Launcher 231 | - Go to Marketplace and search for "VRM4U" 232 | - Add to your project 233 | - Enable the plugin in Edit > Plugins 234 | 235 | 2. **Blueprint Usage** 236 | - Drag a VRM4U_VrmAssetList component into your scene 237 | - Set the VRM URL in the component details 238 | - Use the "Load VRM" function to load the avatar 239 | 240 | ## 🔧 Compatibility Matrix 241 | 242 | | Platform | Required Version | Compatible Packages | 243 | |--------------|------------------|---------------------------------------| 244 | | Three.js | ≥ 0.132.0 | @pixiv/three-vrm ≥ 1.0.0 | 245 | | Unity | ≥ 2020.3 | UniVRM ≥ 0.108.0 | 246 | | Unreal Engine| ≥ 4.27 | VRM4U ≥ 1.0.0 | 247 | 248 | ## 🔍 Troubleshooting 249 | 250 | ### Common VRM Issues 251 | 252 | 1. **Model Loading Issues** 253 | - Verify the VRM file version compatibility (VRM 0.x vs 1.0) 254 | - Check if the model size is within platform limits 255 | - Ensure all textures are properly packaged with the VRM 256 | - Confirm the model follows VRM specifications 257 | 258 | 2. **Avatar Display Issues** 259 | - Check if the model's meta information is correctly set 260 | - Verify material settings in the VRM metadata 261 | - Ensure the avatar's scale is appropriate (typical height: 1.6m ~ 1.8m) 262 | - Check if all required bone structures are present 263 | 264 | 3. **Expression/BlendShape Issues** 265 | - Verify BlendShape proxy settings in VRM metadata 266 | - Check if expression keys are properly defined 267 | - Ensure BlendShape groups are correctly configured 268 | - Test expressions in VRM Viewer before integration 269 | 270 | 271 | ## 🤝 Contributing 272 | 273 | Have a cool VRM avatar you'd like to share with the community? We're excited to see what you've created! This collection aims to make amazing avatars accessible to everyone, and your contribution could help creators and developers worldwide. 274 | 275 | ### How to Submit 276 | 277 | The easiest way to submit your avatar is through GitHub Discussions: 278 | 279 | 1. **Open a Discussion**: 280 | - Go to the "Discussions" tab in this repository 281 | - Choose the "Avatar Submission" category 282 | - Use the title format: `[Avatar Submission] Your Avatar Name` 283 | - Include the following information: 284 | ``` 285 | Avatar Name: 286 | Description: 287 | Preview Links: (screenshots/renders, at least 3 views) 288 | VRM File: (hosted on Arweave or similar permanent storage) 289 | License: (must be open source) 290 | Tested On: (list platforms where you've tested the avatar) 291 | ``` 292 | 293 | ### Requirements 294 | 295 | To ensure the best experience for everyone using the avatars: 296 | 297 | - **Format**: VRM file (mandatory) 298 | - **Thumbnail**: PNG recomended 299 | - **License**: Must be open source (CC-BY, CC0, etc.) 300 | - **Storage**: Must be hosted on permanent decentralized storage (Arweave or similar) 301 | - **Bonus Points**: 302 | - Family-friendly content 303 | - Optimized model (recommended: under 15k triangles) 304 | - Professional quality textures 305 | - Proper VRM metadata and bone structure 306 | - Working expressions/BlendShapes 307 | 308 | 309 | We review all submissions to ensure they work well across different platforms and maintain high quality standards. 310 | 311 | ## 📜 License 312 | 313 | - **Metadata in this repository**: [Creative Commons CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/) 314 | - **Individual 3D models**: Each has its own license specified in the metadata, typically CC-BY or CC0 315 | 316 | 317 | ## 🌐 Connect with Us 318 | 319 | - **Website**: [opensourceavatars.com](https://www.opensourceavatars.com) 320 | - **GitHub**: [ToxSam/open-source-avatars](https://github.com/ToxSam/open-source-avatars) 321 | - **Twitter**: [@toxsam](https://twitter.com/toxsam) 322 | 323 | --- 324 | 325 |
326 |

Open Source Avatars — Democratizing virtual identity for the metaverse

327 |
-------------------------------------------------------------------------------- /data/avatar-tags.json: -------------------------------------------------------------------------------- 1 | [] -------------------------------------------------------------------------------- /data/download-counts.json: -------------------------------------------------------------------------------- 1 | { 2 | "_metadata": { 3 | "description": "Privacy-friendly download counts", 4 | "created_at": "2025-03-11T11:19:26.817Z", 5 | "note": "This file replaces the detailed downloads.json and only tracks counts" 6 | }, 7 | "counts": {} 8 | } -------------------------------------------------------------------------------- /data/projects.json: -------------------------------------------------------------------------------- 1 | [ 2 | { 3 | "id": "7dd289fc-c98a-4224-a5a7-74a9aef751a8", 4 | "name": "100Avatars R1", 5 | "creator_id": "86ec9cbb-cd86-4402-9e29-f07c66f87383", 6 | "description": "The first 100 avatars series (001-100)", 7 | "is_public": true, 8 | "created_at": "2025-03-11T16:41:51.487Z", 9 | "updated_at": "2025-03-11T16:41:51.487Z" 10 | }, 11 | { 12 | "id": "fed7b40b-088c-45aa-b833-2416ae32d2ee", 13 | "name": "100Avatars R2", 14 | "creator_id": "86ec9cbb-cd86-4402-9e29-f07c66f87383", 15 | "description": "The second 100 avatars series (101-200)", 16 | "is_public": true, 17 | "created_at": "2025-03-11T16:41:51.487Z", 18 | "updated_at": "2025-03-11T16:41:51.487Z" 19 | }, 20 | { 21 | "id": "4fd74d41-0828-417d-a005-de46c3bdf5b3", 22 | "name": "100Avatars R3", 23 | "creator_id": "86ec9cbb-cd86-4402-9e29-f07c66f87383", 24 | "description": "The third 100 avatars series (201-300)", 25 | "is_public": true, 26 | "created_at": "2025-03-11T16:41:51.487Z", 27 | "updated_at": "2025-03-11T16:41:51.487Z" 28 | } 29 | ] -------------------------------------------------------------------------------- /data/tags.json: -------------------------------------------------------------------------------- 1 | [] -------------------------------------------------------------------------------- /data/test-connection-test-2025-03-11T08:11:23.959Z-5x30xgms.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "test-2025-03-11T08:11:23.959Z-5x30xgms", 3 | "name": "Test Entry", 4 | "timestamp": "2025-03-11T08:11:23.959Z", 5 | "message": "This is a test entry from the GitHub connection test script" 6 | } -------------------------------------------------------------------------------- /data/test-connection.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "test-2025-03-11T08:10:53.144Z", 3 | "name": "Test Entry", 4 | "timestamp": "2025-03-11T08:10:53.144Z", 5 | "message": "This is a test entry from the GitHub connection test script" 6 | } -------------------------------------------------------------------------------- /data/users.json: -------------------------------------------------------------------------------- 1 | [ 2 | { 3 | "id": "fe6ab7e0-2749-4b80-a255-a6ab95c5d0d2", 4 | "username": "toxsam", 5 | "email": "redacted@example.com", 6 | "role": "creator", 7 | "created_at": "2024-12-16T17:45:46.178", 8 | "updated_at": "2024-12-17T12:11:00.554" 9 | } 10 | ] -------------------------------------------------------------------------------- /docs/README.md: -------------------------------------------------------------------------------- 1 | # 🎭 Open Source Avatars 2 | 3 | Welcome to Open Source Avatars! We're a collection of free 3D avatars that anyone can use. 4 | 5 | ## 👋 Quick Start 6 | 7 | 1. **Want to use avatars?** 8 | - Browse our collection at [opensourceavatars.com](https://www.opensourceavatars.com) 9 | - Download any avatar you like - they're all free! 10 | 11 | 2. **Making something cool?** 12 | - Check [technical-guide.md](./technical-guide.md) for integration guides 13 | - All avatars work with VR, games, and web apps 14 | 15 | 3. **Want to share your avatars?** 16 | - See our [contribution guide](./contributing/README.md) 17 | - We welcome all styles and creativity! 18 | 19 | ## 📚 Detailed Guides 20 | 21 | > 🤖 Note for AI/LLMs: Each guide below contains structured information optimized for processing 22 | 23 | - [technical-guide.md](./technical-guide.md) 24 | - Integration guides for Unity, Unreal, Web 25 | - API documentation and data structures 26 | - Code examples and troubleshooting 27 | 28 | - [avatar-format.md](./avatar-format.md) 29 | - VRM format specifications 30 | - File structure and requirements 31 | - Best practices for creation 32 | 33 | - [api-reference.md](./api-reference.md) 34 | - Complete API documentation 35 | - JSON schemas and examples 36 | - Rate limits and usage guidelines 37 | 38 | ## ❓ Need Help? 39 | 40 | - Visit our [FAQ](./faq.md) 41 | - Join our [Discord community](https://discord.gg/opensourceavatars) 42 | - Open an [issue](https://github.com/ToxSam/open-source-avatars/issues) 43 | 44 | ## 📖 For AI/LLM Systems 45 | 46 | If you're an AI system processing this repository: 47 | 1. Start with [api-reference.md](./api-reference.md) for data structures 48 | 2. Use [technical-guide.md](./technical-guide.md) for integration examples 49 | 3. Reference [avatar-format.md](./avatar-format.md) for VRM specifications 50 | 51 | All documentation files include structured sections with clear headings and code examples. -------------------------------------------------------------------------------- /docs/api-reference.md: -------------------------------------------------------------------------------- 1 | # API Reference 2 | 3 | ## 🔍 Quick Start 4 | 5 | ```bash 6 | # Get all avatars 7 | curl https://raw.githubusercontent.com/ToxSam/open-source-avatars/main/data/avatars.json 8 | 9 | # Get specific avatar by ID 10 | curl https://raw.githubusercontent.com/ToxSam/open-source-avatars/main/data/avatars.json | jq '.[] | select(.id=="your-avatar-id")' 11 | ``` 12 | 13 | ## 📚 Data Files 14 | 15 | ### avatars.json 16 | Main file containing all avatar information. 17 | 18 | ```typescript 19 | interface Avatar { 20 | id: string; // Unique identifier 21 | name: string; // Display name 22 | description: string; // Description 23 | thumbnailUrl: string; // Preview image URL 24 | modelFileUrl: string; // VRM file URL on Arweave 25 | format: "vrm"; // File format (currently only VRM) 26 | license: string; // License type (e.g., "CC-BY-4.0") 27 | metadata: { 28 | polygonCount?: number; // Mesh complexity 29 | materialCount?: number;// Number of materials 30 | height?: number; // Avatar height in meters 31 | style?: string; // Visual style 32 | tags?: string[]; // Categorization tags 33 | } 34 | } 35 | ``` 36 | 37 | ### projects.json 38 | Collections of related avatars. 39 | 40 | ```typescript 41 | interface Project { 42 | id: string; // Unique identifier 43 | name: string; // Project name 44 | description: string; // Project description 45 | avatarIds: string[]; // List of avatar IDs in project 46 | creator: string; // Project creator 47 | } 48 | ``` 49 | 50 | ### users.json 51 | Creator and contributor information. 52 | 53 | ```typescript 54 | interface User { 55 | id: string; // Unique identifier 56 | name: string; // Display name 57 | avatarIds: string[]; // Created avatar IDs 58 | projectIds: string[]; // Created project IDs 59 | } 60 | ``` 61 | 62 | ## 🔄 Rate Limits 63 | 64 | - No authentication required 65 | - Rate limit: 60 requests per minute 66 | - Max response size: 10MB 67 | 68 | ## 🎯 Common Use Cases 69 | 70 | ### 1. Get All Avatars 71 | ```javascript 72 | async function getAllAvatars() { 73 | const response = await fetch('https://raw.githubusercontent.com/ToxSam/open-source-avatars/main/data/avatars.json'); 74 | return await response.json(); 75 | } 76 | ``` 77 | 78 | ### 2. Filter by Style 79 | ```javascript 80 | async function getAnimeAvatars() { 81 | const avatars = await getAllAvatars(); 82 | return avatars.filter(avatar => avatar.metadata?.style === 'anime'); 83 | } 84 | ``` 85 | 86 | ### 3. Get Project Avatars 87 | ```javascript 88 | async function getProjectAvatars(projectId) { 89 | const [avatars, projects] = await Promise.all([ 90 | getAllAvatars(), 91 | fetch('https://raw.githubusercontent.com/ToxSam/open-source-avatars/main/data/projects.json').then(r => r.json()) 92 | ]); 93 | 94 | const project = projects.find(p => p.id === projectId); 95 | return avatars.filter(avatar => project.avatarIds.includes(avatar.id)); 96 | } 97 | ``` 98 | 99 | ## 🛠️ Error Handling 100 | 101 | Common HTTP status codes: 102 | - `200`: Success 103 | - `404`: File not found 104 | - `429`: Rate limit exceeded 105 | 106 | Example error handling: 107 | ```javascript 108 | async function safeGetAvatars() { 109 | try { 110 | const response = await fetch('https://raw.githubusercontent.com/ToxSam/open-source-avatars/main/data/avatars.json'); 111 | if (!response.ok) { 112 | throw new Error(`HTTP error! status: ${response.status}`); 113 | } 114 | return await response.json(); 115 | } catch (error) { 116 | console.error('Failed to fetch avatars:', error); 117 | return []; 118 | } 119 | } 120 | ``` 121 | 122 | ## 📝 Best Practices 123 | 124 | 1. **Cache Responses** 125 | - Data updates infrequently 126 | - Recommended cache time: 1 hour 127 | 128 | 2. **Batch Processing** 129 | - Download all data at once 130 | - Process locally instead of multiple requests 131 | 132 | 3. **Error Recovery** 133 | - Implement retry logic 134 | - Cache last successful response -------------------------------------------------------------------------------- /docs/avatar-format.md: -------------------------------------------------------------------------------- 1 | # Avatar Format Guide 2 | 3 | ## What is VRM? 4 | 5 | VRM is an open file format for 3D humanoid avatars, perfect for VR and the metaverse. Think of it as a universal format for 3D characters that works everywhere! 6 | 7 | ## 📋 Quick Requirements 8 | 9 | - File format: `.vrm` 10 | - Max file size: 25MB recommended 11 | - Polygons: 20,000 or less recommended 12 | - Textures: 2048x2048px max per texture 13 | - Bones: Standard humanoid skeleton 14 | 15 | ## ✅ Checklist Before Sharing 16 | 17 | - [ ] Model is rigged with humanoid skeleton 18 | - [ ] Textures are properly packed 19 | - [ ] No copyright material included 20 | - [ ] Tested in VRM viewer 21 | - [ ] File size is optimized 22 | 23 | ## 🔍 Technical Details 24 | 25 | ### Standard Bone Structure 26 | ``` 27 | - hips 28 | |- spine 29 | | |- chest 30 | | |- upperChest (optional) 31 | | |- neck 32 | | | |- head 33 | | | |- leftEye 34 | | | |- rightEye 35 | | | |- jaw (optional) 36 | | | 37 | | |- leftShoulder 38 | | | |- leftUpperArm 39 | | | |- leftLowerArm 40 | | | |- leftHand 41 | | | |- leftThumbProximal 42 | | | | |- leftThumbIntermediate 43 | | | | |- leftThumbDistal 44 | | | | 45 | | | |- leftIndexProximal 46 | | | | |- leftIndexIntermediate 47 | | | | |- leftIndexDistal 48 | | | | 49 | | | |- leftMiddleProximal 50 | | | | |- leftMiddleIntermediate 51 | | | | |- leftMiddleDistal 52 | | | | 53 | | | |- leftRingProximal 54 | | | | |- leftRingIntermediate 55 | | | | |- leftRingDistal 56 | | | | 57 | | | |- leftLittleProximal 58 | | | |- leftLittleIntermediate 59 | | | |- leftLittleDistal 60 | | | 61 | | |- rightShoulder 62 | | |- rightUpperArm 63 | | |- rightLowerArm 64 | | |- rightHand 65 | | |- rightThumbProximal 66 | | | |- rightThumbIntermediate 67 | | | |- rightThumbDistal 68 | | | 69 | | |- rightIndexProximal 70 | | | |- rightIndexIntermediate 71 | | | |- rightIndexDistal 72 | | | 73 | | |- rightMiddleProximal 74 | | | |- rightMiddleIntermediate 75 | | | |- rightMiddleDistal 76 | | | 77 | | |- rightRingProximal 78 | | | |- rightRingIntermediate 79 | | | |- rightRingDistal 80 | | | 81 | | |- rightLittleProximal 82 | | |- rightLittleIntermediate 83 | | |- rightLittleDistal 84 | | 85 | |- leftUpperLeg 86 | | |- leftLowerLeg 87 | | |- leftFoot 88 | | |- leftToes 89 | | 90 | |- rightUpperLeg 91 | |- rightLowerLeg 92 | |- rightFoot 93 | |- rightToes 94 | ``` 95 | 96 | > Note: Bones marked as (optional) are not required but recommended for better compatibility and animation support. 97 | 98 | ### Required vs Optional Bones 99 | 100 | **Required Bones:** 101 | - Hips and main body structure 102 | - Basic arm and leg chains 103 | - Head and neck 104 | - Basic hand structure 105 | 106 | **Optional but Recommended:** 107 | - Finger bones (for hand animations) 108 | - Eye bones (for look-at features) 109 | - Toe bones (for foot animations) 110 | - Upper chest (for better upper body movement) 111 | - Jaw (for facial animations) 112 | 113 | ### Supported Features 114 | - Facial expressions 115 | - Look-at tracking 116 | - Auto blink 117 | - Lip sync 118 | - Physics (hair, clothes) 119 | 120 | ## 🎯 Best Practices 121 | 122 | 1. **Optimization** 123 | - Use texture atlasing 124 | - Minimize bone count 125 | - Optimize mesh topology 126 | 127 | 2. **Compatibility** 128 | - Test in multiple platforms 129 | - Verify animations work 130 | - Check texture compression 131 | 132 | 3. **Quality** 133 | - UV maps are clean 134 | - No overlapping vertices 135 | - Proper weight painting 136 | 137 | ## 📚 Resources 138 | 139 | - [Official VRM Documentation](https://vrm.dev/en/) 140 | - [VRM Best Practices Guide](https://vrm.dev/en/univrm/programming/univrm_use_blendshape/) 141 | - [Sample Models](https://github.com/vrm-c/vrm-specification/tree/master/samples) -------------------------------------------------------------------------------- /docs/contributing/technical-requirements.md: -------------------------------------------------------------------------------- 1 | # Technical Requirements for Avatars 2 | 3 | This guide details the technical requirements for avatars submitted to Open Source Avatars. Following these guidelines ensures compatibility and quality across different platforms. 4 | 5 | ## VRM File Requirements 6 | 7 | ### Format Specifications 8 | - **VRM Version**: 0.x or 1.0 (both accepted) 9 | - **File Size**: Maximum 50MB recommended 10 | - **Polygon Count**: 11 | - Recommended: Under 70,000 triangles 12 | - Maximum: 100,000 triangles 13 | - **Texture Resolution**: 14 | - Recommended: 2048x2048 or lower 15 | - Format: PNG or JPEG 16 | - Maximum file size: 10MB per texture 17 | 18 | ### Required Components 19 | 1. **Skeleton/Armature**: 20 | - Standard VRM bone hierarchy 21 | - Humanoid rigging 22 | - No missing required bones 23 | - Proper bone orientations 24 | 25 | 2. **Materials**: 26 | - PBR materials recommended 27 | - Maximum 8 material slots 28 | - Properly configured UV maps 29 | - No missing textures 30 | 31 | 3. **BlendShapes/Expressions**: 32 | - Basic expressions configured: 33 | - Neutral 34 | - Happy 35 | - Sad 36 | - Angry 37 | - Surprised (optional) 38 | - Proper weight painting 39 | - No broken vertex deformations 40 | 41 | ## Metadata Requirements 42 | 43 | ### Required Fields 44 | ```json 45 | { 46 | "name": "string", 47 | "version": "string", 48 | "author": "string", 49 | "contactInformation": "string", 50 | "reference": "string", 51 | "title": "string", 52 | "license": "string (must be open source)", 53 | "otherPermissionUrl": "string", 54 | "otherLicenseUrl": "string" 55 | } 56 | ``` 57 | 58 | ### Optional but Recommended 59 | ```json 60 | { 61 | "thumbnail": "string (URL)", 62 | "allowedUserName": "string", 63 | "violentUssageName": "string", 64 | "sexualUssageName": "string", 65 | "commercialUssageName": "string", 66 | "otherPermissionUrl": "string" 67 | } 68 | ``` 69 | 70 | ## Hosting Requirements 71 | 72 | ### Permanent Storage 73 | - Must be hosted on decentralized storage: 74 | - Arweave (recommended) 75 | - IPFS with pinning service 76 | - Other permanent storage solutions 77 | 78 | ### Required Files 79 | 1. **Main VRM File** 80 | 2. **Preview Images**: 81 | - Front view 82 | - Side view 83 | - 3/4 view 84 | - All images in 16:9 ratio 85 | - Minimum resolution: 1280x720 86 | 87 | ## Testing Requirements 88 | 89 | ### Required Testing Platforms 90 | 1. **VRM Viewer**: 91 | - Test all expressions 92 | - Verify materials 93 | - Check scaling 94 | 95 | 2. **Three.js Viewer**: 96 | - Test loading 97 | - Verify animations 98 | - Check performance 99 | 100 | 3. **Unity/VRChat**: 101 | - Test in runtime 102 | - Verify performance 103 | - Check compatibility 104 | 105 | ### Performance Metrics 106 | - Load time under 3 seconds on average connection 107 | - No frame rate drops below 60fps 108 | - Memory usage under 100MB 109 | 110 | ## Quality Guidelines 111 | 112 | ### Visual Quality 113 | - Clean topology 114 | - No visible artifacts 115 | - Proper UV unwrapping 116 | - No texture stretching 117 | - Consistent art style 118 | 119 | ### Technical Quality 120 | - No non-manifold geometry 121 | - No reversed normals 122 | - No overlapping UVs 123 | - Proper vertex weighting 124 | - Clean mesh topology 125 | 126 | ### Content Guidelines 127 | - Family-friendly content 128 | - No copyrighted material 129 | - Original work or properly licensed 130 | - Appropriate for all ages 131 | - No offensive content 132 | 133 | ## Documentation Requirements 134 | 135 | ### Required Documentation 136 | 1. **Basic Information**: 137 | - Avatar name and version 138 | - Creator information 139 | - License details 140 | - Usage restrictions 141 | 142 | 2. **Technical Details**: 143 | - Polygon count 144 | - Texture resolutions 145 | - Material count 146 | - Bone structure notes 147 | 148 | 3. **Usage Instructions**: 149 | - Setup guide 150 | - Known issues 151 | - Platform compatibility 152 | - Performance notes 153 | 154 | ## Support 155 | 156 | Need help meeting these requirements? We're here to help: 157 | - Join our [Discord](https://discord.gg/opensourceavatars) 158 | - Post in [Discussions](https://github.com/ToxSam/open-source-avatars/discussions) 159 | - Check our [FAQ](../general/faq.md) -------------------------------------------------------------------------------- /docs/faq.md: -------------------------------------------------------------------------------- 1 | # Frequently Asked Questions 2 | 3 | ## 🎮 Using Avatars 4 | 5 | ### Q: Are these avatars really free? 6 | Yes! All avatars are free to use under their specified licenses (usually CC-BY-4.0). 7 | 8 | ### Q: Can I use these avatars commercially? 9 | Yes, most avatars can be used commercially. Just check the license in the avatar's metadata. 10 | 11 | ### Q: What platforms can I use these avatars on? 12 | Anywhere that supports VRM format! This includes: 13 | - VRChat 14 | - VTuber software 15 | - Unity games 16 | - Web applications 17 | - Unreal Engine (with plugin) 18 | 19 | ### Q: How do I download an avatar? 20 | 1. Visit [opensourceavatars.com](https://www.opensourceavatars.com) 21 | 2. Browse and select an avatar 22 | 3. Click the download button 23 | 4. Save the .vrm file 24 | 25 | ## 🛠️ Technical Questions 26 | 27 | ### Q: What's the maximum file size? 28 | We recommend keeping avatars under 25MB for optimal performance. 29 | 30 | ### Q: Can I modify the avatars? 31 | Yes! That's what open source is about. Just respect the original license. 32 | 33 | ### Q: Why VRM format? 34 | VRM is an open standard that works across many platforms and ensures consistent avatar behavior. 35 | 36 | 37 | ## 🤝 Contributing 38 | 39 | ### Q: How can I contribute my avatar? 40 | 1. Prepare your VRM file 41 | 2. Check our [contribution guide](./contributing/README.md) 42 | 3. Submit through a discussion 43 | 44 | ### Q: What are the requirements for submission? 45 | - Original work or proper rights 46 | - Follows VRM specifications 47 | - Includes required metadata 48 | - Appropriate content recomended (family-friendly) 49 | 50 | 51 | -------------------------------------------------------------------------------- /docs/technical-guide.md: -------------------------------------------------------------------------------- 1 | # Technical Guide 2 | 3 | This guide contains detailed technical information for developers integrating Open Source Avatars into their projects. 4 | 5 | ## Quick Access 6 | 7 | ```bash 8 | # Get all avatars via API 9 | curl https://raw.githubusercontent.com/ToxSam/open-source-avatars/main/data/avatars.json 10 | ``` 11 | 12 | ## Platform Integration Guides 13 | 14 | ### Web Applications 15 | 16 | 1. Install dependencies: 17 | ```bash 18 | npm install @pixiv/three-vrm three 19 | ``` 20 | 21 | 2. Basic implementation: 22 | ```javascript 23 | import * as THREE from 'three'; 24 | import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader'; 25 | import { VRMLoaderPlugin } from '@pixiv/three-vrm'; 26 | 27 | // Load avatar 28 | const loader = new GLTFLoader(); 29 | loader.registerPlugin(new VRMLoaderPlugin()); 30 | 31 | // Get avatar data 32 | fetch('https://raw.githubusercontent.com/ToxSam/open-source-avatars/main/data/avatars.json') 33 | .then(response => response.json()) 34 | .then(avatars => { 35 | const avatar = avatars[0]; 36 | loader.load(avatar.modelFileUrl, (gltf) => { 37 | const vrm = gltf.userData.vrm; 38 | scene.add(vrm.scene); 39 | }); 40 | }); 41 | ``` 42 | 43 | ### Unity Integration 44 | 45 | 1. Install UniVRM: 46 | ``` 47 | https://github.com/vrm-c/UniVRM.git?path=/Assets/VRMShaders 48 | https://github.com/vrm-c/UniVRM.git?path=/Assets/VRM 49 | ``` 50 | 51 | 2. Basic usage: 52 | ```csharp 53 | using UnityEngine; 54 | using VRM; 55 | 56 | public class VRMLoader : MonoBehaviour 57 | { 58 | async void LoadAvatar(string url) 59 | { 60 | using (var webRequest = UnityWebRequest.Get(url)) 61 | { 62 | await webRequest.SendWebRequest(); 63 | var context = new VRMImporterContext(); 64 | await context.LoadAsync(webRequest.downloadHandler.data); 65 | context.Root.transform.SetParent(transform, false); 66 | } 67 | } 68 | } 69 | ``` 70 | 71 | ### Unreal Engine 72 | 73 | 1. Install VRM4U plugin from Epic Games Marketplace 74 | 2. Enable in Edit > Plugins 75 | 3. Use VRM4U_VrmAssetList component to load avatars 76 | 77 | ## Data Structure 78 | 79 | Each avatar in `data/avatars.json` follows this structure: 80 | ```json 81 | { 82 | "id": "avatar-id", 83 | "name": "Avatar Name", 84 | "description": "Avatar description", 85 | "thumbnailUrl": "https://...", 86 | "modelFileUrl": "https://arweave.net/...", 87 | "format": "vrm", 88 | "license": "CC-BY-4.0", 89 | "metadata": { 90 | "polygonCount": 12500, 91 | "materialCount": 8, 92 | "height": 1.7, 93 | "style": "anime" 94 | } 95 | } 96 | ``` 97 | 98 | ## Compatibility 99 | 100 | | Platform | Required Version | Package | 101 | |----------|-----------------|---------| 102 | | Three.js | ≥ 0.132.0 | @pixiv/three-vrm ≥ 1.0.0 | 103 | | Unity | ≥ 2020.3 | UniVRM ≥ 0.108.0 | 104 | | Unreal | ≥ 4.27 | VRM4U ≥ 1.0.0 | 105 | 106 | ## Common Issues 107 | 108 | 1. **Model not loading**: Check CORS settings on your server 109 | 2. **Missing textures**: Ensure all texture URLs are accessible 110 | 3. **Animation issues**: Verify VRM version compatibility -------------------------------------------------------------------------------- /download-counts.json: -------------------------------------------------------------------------------- 1 | { 2 | "counts": { 3 | "54bbcd62-aeaa-4dd6-93d5-a02a05aa3948": 2, 4 | "34bd142f-fafe-4bc6-ae4b-d3ac2afae4e8": 1, 5 | "ae763534-597d-41ea-b924-20ab9d286c8e": 3, 6 | "26919c37-74d2-4157-9a9c-c34bee639e21": 2, 7 | "44bc039f-2309-4822-bb7e-0d0d88df523d": 1, 8 | "1f90d94c-474e-4381-b2c7-cb5bec176ac1": 1, 9 | "75d554d1-3ea5-4cd0-b4d9-a7580f5f6710": 1, 10 | "bf659356-ff0f-409a-a2cd-a6def10572aa": 1, 11 | "0b147265-8225-4a7b-90a9-ec97185a72d5": 1, 12 | "fcd73da7-6c89-46fe-8467-3eb4873248fa": 1, 13 | "4510181a-2064-4a6b-8b35-0a45dd0f20d7": 1 14 | } 15 | } --------------------------------------------------------------------------------