{"id":16699689,"url":"https://github.com/sinanislekdemir/blackbook","last_synced_at":"2026-03-11T21:04:09.186Z","repository":{"id":29498055,"uuid":"33035874","full_name":"sinanislekdemir/blackbook","owner":"sinanislekdemir","description":"Pure Ruby 3D Engine","archived":false,"fork":false,"pushed_at":"2024-09-24T15:44:16.000Z","size":21494,"stargazers_count":14,"open_issues_count":1,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-24T05:04:56.699Z","etag":null,"topics":["3d","3d-engine","3d-game-engine","3d-graphics","game-development","game-engine","graphics","opengl","ruby"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sinanislekdemir.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-03-28T14:15:18.000Z","updated_at":"2024-10-19T15:02:52.000Z","dependencies_parsed_at":"2025-02-16T11:32:45.984Z","dependency_job_id":"89e7ac4f-3a5b-4b25-9738-cb787091bcff","html_url":"https://github.com/sinanislekdemir/blackbook","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinanislekdemir%2Fblackbook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinanislekdemir%2Fblackbook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinanislekdemir%2Fblackbook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinanislekdemir%2Fblackbook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sinanislekdemir","download_url":"https://codeload.github.com/sinanislekdemir/blackbook/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248154995,"owners_count":21056542,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d","3d-engine","3d-game-engine","3d-graphics","game-development","game-engine","graphics","opengl","ruby"],"created_at":"2024-10-12T18:07:54.677Z","updated_at":"2026-03-11T21:04:09.163Z","avatar_url":"https://github.com/sinanislekdemir.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BlackBook 3D Engine\n\n[![Gem Version](https://badge.fury.io/rb/blackbook3d.svg)](https://badge.fury.io/rb/blackbook3d)\n[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.0-ruby.svg)](https://www.ruby-lang.org)\n[![License: GPL v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)\n\nA pure Ruby 3D rendering engine built on OpenGL. Write 3D applications with the simplicity and elegance of Ruby.\n\n![BlackBook Sample](https://raw.github.com/sinanislekdemir/blackbook/master/sample.png)\n\n## Features\n\n- 🎮 **Pure Ruby** - No C++ required, write everything in Ruby\n- 🎨 **OpenGL Rendering** - Hardware-accelerated 3D graphics\n- 📦 **3D Model Loading** - Import .obj and .raw formats from Blender\n- 🎯 **Physics Simulation** - Collision detection with sphere-to-sphere physics\n- 🎬 **Camera System** - Mouse-controlled camera with multiple view support\n- 💡 **Lighting** - Multiple light sources with material support\n- 🖼️ **Texture Mapping** - Load and apply textures to 3D objects\n- 🧮 **Vector Math** - Complete 3D vector and matrix library\n- 🎪 **UI System** - Built-in UI for creating windows, buttons, and controls\n\n## Installation\n\n### From RubyGems (Recommended)\n\n```bash\ngem install blackbook3d\n```\n\nOr add to your Gemfile:\n\n```ruby\ngem 'blackbook3d', '~\u003e 0.5.0'\n```\n\n### System Dependencies\n\n**Ubuntu/Debian:**\n```bash\nsudo apt-get install libglfw3-dev imagemagick\n```\n\n**macOS:**\n```bash\nbrew install glfw imagemagick\n```\n\n**Arch Linux:**\n```bash\nsudo pacman -S glfw imagemagick\n```\n\n## Quick Start\n\n```ruby\nrequire 'blackbook'\n\nmodule BlackBook\n  class MyApp \u003c Engine\n    def initialize\n      super(800, 600, 'My 3D App')\n      \n      # Create a 3D space\n      @space = Space.new(@viewport_x, @viewport_y)\n      \n      # Add a camera\n      @space.add_camera(\n        eye_position: CVector.new(10, 10, 10),\n        up: CVector.new(0, 0, 1),\n        target_position: CVector.new(0, 0, 0)\n      )\n      \n      # Add a light\n      light = @space.create_light\n      light.position.set(5, 5, 10)\n      \n      # Load and add a 3D object\n      gem_dir = Gem::Specification.find_by_name('blackbook3d').gem_dir\n      sphere = File.join(gem_dir, 'data', 'sphere.raw')\n      \n      obj = @space.add_object(filename: sphere, name: 'my_sphere')\n      obj.material.color.set(1.0, 0.3, 0.3, 1.0)  # Red color\n    end\n    \n    def render\n      super\n      @space.init_gl unless @space.gl_active\n      @space.render\n    end\n  end\nend\n\n# Run the application\nMyApp.new.engine_loop\n```\n\nSave as `my_app.rb` and run:\n```bash\nruby my_app.rb\n```\n\n## Examples\n\nCheck out the [samples](samples/) directory for more examples:\n\n- **1_simple.rb** - Basic empty scene\n- **3_first_object.rb** - Loading and displaying 3D objects\n- **6_multiple_lights.rb** - Working with multiple light sources\n- **14_texture.rb** - Applying textures to objects\n- **15_bouncing_balls.rb** - Physics simulation with collision detection\n\nRun any sample:\n```bash\ncd samples\nruby 15_bouncing_balls.rb\n```\n\n## Configuration\n\nConfigure global settings using the Registry:\n\n```ruby\nBlackBook::Registry.setup(\n  grid: true,           # Show grid\n  grid_count: 100,      # Number of grid lines\n  grid_size: 2,         # Grid line spacing\n  shader: 'vbo'         # Rendering mode: 'vbo' or 'displaylist'\n)\n```\n\n## Creating 3D Models\n\n### From Blender\n\nBlackBook supports standard 3D formats:\n\n**Wavefront OBJ Format:**\n1. Export from Blender as `.obj`\n2. Set Forward: Y Forward, Up: Z Up\n3. Load with `space.add_object(filename: 'model.obj')`\n\n**RAW Format:**\n1. Export from Blender as RAW triangle format\n2. Load with `space.add_object(filename: 'model.raw')`\n\n![Blender Export Settings](https://raw.github.com/sinanislekdemir/blackbook/master/obj_export.png)\n\n## Architecture\n\n```\nEngine\n  └── Space (3D Scene)\n      ├── Camera (Multiple cameras supported)\n      ├── Light (Multiple lights)\n      ├── B3DObject (3D Models)\n      │   └── Material (Colors, Textures)\n      └── UI (Windows, Buttons, Labels)\n```\n\n### Key Classes\n\n- **`Engine`** - Window and main loop management\n- **`Space`** - 3D scene container\n- **`Camera`** - View and projection handling\n- **`B3DObject`** - 3D meshes with transform matrices\n- **`Material`** - Colors and texture properties\n- **`CVector`** - 3D vector math\n- **`Light`** - Light sources\n\n## Physics \u0026 Collision\n\nBlackBook includes basic physics simulation:\n\n```ruby\n# Objects automatically calculate bounding sphere radius\nobj = space.add_object(filename: 'sphere.raw')\nputs obj.radius  # Calculated from vertices\n\n# Implement collision detection in your update loop\nif ball1.position.distance(ball2.position) \u003c ball1.radius + ball2.radius\n  # Handle collision\nend\n```\n\nSee [samples/15_bouncing_balls.rb](samples/15_bouncing_balls.rb) for a complete example.\n\n## Camera Controls\n\nBuilt-in mouse camera controls:\n\n- **Left Mouse Button + Drag** - Rotate camera around target\n- Camera movement is automatic in the default implementation\n- Override `mouse_move` in your Engine subclass for custom controls\n\n## Documentation\n\nGenerate full API documentation:\n\n```bash\ngem install yard\nyard doc\n```\n\nView the documentation:\n```bash\nyard server\n```\n\nThen open http://localhost:8808\n\n## Contributing\n\nContributions are welcome!\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing`)\n3. Commit your changes (`git commit -am 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing`)\n5. Open a Pull Request\n\n### Development Setup\n\n```bash\ngit clone https://github.com/sinanislekdemir/blackbook.git\ncd blackbook\nbundle install\nruby samples/1_simple.rb\n```\n\n## Known Issues\n\n- Physics engine needs refactoring (contributions welcome!)\n- Display lists are used by default (VBOs available but not default)\n- Some UI components are work in progress\n\n## Version History\n\n### v0.5.0 (2025-12-24) - First RubyGems Release\n- ✨ Published to RubyGems.org\n- ✨ Modernized for Ruby 3.4+\n- ✨ Replaced abandoned `glfw3` with `glfw` 3.3.2\n- ✨ Switched from RMagick to MiniMagick\n- 🐛 Fixed window resizing and viewport updates\n- 🐛 Fixed texture loading with modern ImageMagick\n- 🎯 Added automatic radius calculation for collision detection\n- 🎯 Improved sphere-to-sphere collision physics\n- 📦 Included 103 data files (models, textures, fonts)\n\nSee [RELEASE_NOTES_v0.5.0.md](RELEASE_NOTES_v0.5.0.md) for complete details.\n\n## Requirements\n\n- Ruby \u003e= 3.0.0\n- GLFW 3.x (system library)\n- ImageMagick (for texture loading)\n- OpenGL support in your graphics driver\n\n## License\n\nGNU General Public License v2.0\n\nSee [LICENSE](LICENSE) for details.\n\n## Credits\n\n**Author:** Sinan ISLEKDEMIR ([@sinanislekdemir](https://github.com/sinanislekdemir))\n\n**Contributors:**\n- [@DarkSpyCyber](https://github.com/DarkSpyCyber) - Animation system and frames support\n- [@alx3dev](https://github.com/alx3dev) - Code improvements and refactoring\n- GitHub Copilot - Modernization assistance (v0.5.0)\n\n**Want to contribute?** PRs are welcome!\n\n## Links\n\n- **RubyGems:** https://rubygems.org/gems/blackbook3d\n- **GitHub:** https://github.com/sinanislekdemir/blackbook\n- **Issues:** https://github.com/sinanislekdemir/blackbook/issues\n\n---\n\nMade with ❤️ and Ruby. Perfect for learning 3D graphics or building small 3D visualizations without leaving Ruby.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsinanislekdemir%2Fblackbook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsinanislekdemir%2Fblackbook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsinanislekdemir%2Fblackbook/lists"}