{"id":29608228,"url":"https://github.com/idriz4work/cube3dd","last_synced_at":"2025-07-20T19:04:40.912Z","repository":{"id":302861522,"uuid":"1013351638","full_name":"Idriz4work/Cube3dd","owner":"Idriz4work","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-11T16:24:15.000Z","size":15011,"stargazers_count":0,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-11T18:35:57.323Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Idriz4work.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2025-07-03T18:52:26.000Z","updated_at":"2025-07-11T16:24:15.000Z","dependencies_parsed_at":"2025-07-04T14:17:46.719Z","dependency_job_id":null,"html_url":"https://github.com/Idriz4work/Cube3dd","commit_stats":null,"previous_names":["idriz4work/cube3dd"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Idriz4work/Cube3dd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Idriz4work%2FCube3dd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Idriz4work%2FCube3dd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Idriz4work%2FCube3dd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Idriz4work%2FCube3dd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Idriz4work","download_url":"https://codeload.github.com/Idriz4work/Cube3dd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Idriz4work%2FCube3dd/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266180835,"owners_count":23888810,"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":[],"created_at":"2025-07-20T19:04:35.176Z","updated_at":"2025-07-20T19:04:40.900Z","avatar_url":"https://github.com/Idriz4work.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cub3D - 3D Raycasting Game Engine\n\nA 42 School project that creates a 3D graphical representation of a maze using raycasting techniques, similar to classic games like Wolfenstein 3D.\n\n## 📋 Project Overview\n\nCub3D is an advanced graphics project that builds upon concepts from so_long, implementing:\n- Ray casting algorithm for 3D rendering\n- Texture mapping and image manipulation\n- Real-time player movement and rotation\n- Flood fill map validation\n- Event handling and graphics optimization\n\n**Expected Performance**: ~750 fps on modern hardware (12th Gen Intel i7, 16GB RAM, Ubuntu 22.04)\n\n## 🎯 Learning Objectives\n\n- Understand and implement raycasting algorithms\n- Master 3D graphics concepts using 2D techniques\n- Work with image buffers and pixel manipulation\n- Optimize graphics rendering performance\n- Handle mathematical calculations for 3D projection\n\n## 🛠️ Setup and Installation\n\n### Prerequisites\nTheese can be installed with the command below\n- MinilibX library\n- GCC compiler\n- Github\n- Make\n- Math library (-lm)\n\n### Installing Prerequisites\nIf you are missing some prerequisites, run this command, to install all the neccesary packages:\n(Admin/Sudo priviliges required)\n   ```bash\n   sudo apt install build-essential gcc git make\n   ```\n\n### Installation Steps\n1. Clone the repository\n\t```bash\n   git clone https://github.com/Idriz4work/Cube3dd.git cub3d\n   ```\n2. Navigate into repository\n\t```bash\n   cd cub3d\n   ```\n3. Compile the project:\n   ```bash\n   make\n   ```\n### Running the game\nThe game requires a map file, which holds information about the map, which the game should load\u003cbr/\u003e\nThe repository comes prepared with some maps, in the \"maps\" folder\u003cbr/\u003e\nMaps have to satisfy certain requirements, which the program will complain about if invalid\u003cbr/\u003e\n\nDifferent ways of running the game:\n1. Quick Run:\nWill run the game with the pre-delivered \"test.cub\" map file\n\t```bash\n   make run\n   ```\n2. Custom Map:\nReplace MAP_PATH with something like \"./maps/test.cub\"\u003cbr/\u003e\nReplace \"test\" from that with whatever other name your map has\u003cbr/\u003e\nThe map has to be in a \".cub\" format\n\t```bash\n   ./cub3d MAP_PATH\n   ```\n\n### Map Files\nMap Files have to hold 3 types of information\u003cbr/\u003e\nThere should only be 1 of theese per line\u003cbr/\u003e\n1.\t4x A path to a texture file per corresponding wall\u003cbr/\u003e\n\tWALL_IDENTIFIER: WALL_TEXTURE\u003cbr/\u003e\n\tYou will need to specify the direction for the wall, and then the texture file\u003cbr/\u003e\n\tWALL IDENTIFIERs are \"NO\", \"SO\", \"WE\" or \"EA\"\u003cbr/\u003e\n\tWALL_TEXTURE is the file, which has to be in an xpm file format\u003cbr/\u003e\n\tIt is also expected that theese files are 64x64 pixels\u003cbr/\u003e\n\tExample:\u003cbr/\u003e\n\tNO: ./textures/rick.xpm\u003cbr/\u003e\n2.\t2x Color data for the ceiling and floor\u003cbr/\u003e\n\tIDENTIFIER RED_VALUE, GREEN_VALUE, BLUE_VALUE\u003cbr/\u003e\n\tIDENTIFIERs are 'C' or 'F'\u003cbr/\u003e\n\tThe rgb values should be between (including) 0-255\u003cbr/\u003e\n\tExample:\u003cbr/\u003e\n\tC 0, 69, 255\u003cbr/\u003e\n3.\tThe map\u003cbr/\u003e\n\tThe map consists of ' ', '1', '0' and a single identifer for the player\u003cbr/\u003e\n\tPlayer identifers are 'N', 'E', 'S', or 'W', corresponding to the initial direction of the player\u003cbr/\u003e\n\t' ' are Empty Spaces, they can seperate map pieces, but may not be encountered by the player\u003cbr/\u003e\n\t'1' are walls, they limit the players movement and view, and should encase the player\u003cbr/\u003e\n\t'0' are free spaces, allowing the player to move on them\u003cbr/\u003e\n\tThe player may be surrounded by free spaces, but the area HAS TO be surrounded in walls.\u003cbr/\u003e\n \tExample:\u003cbr/\u003e\n\t111111\u003cbr/\u003e\n  \t1E01011\u003cbr/\u003e\n  \t1100001\u003cbr/\u003e\n  \t 1111111\u003cbr/\u003e\n\nThe map should be the last piece of information in the file\u003cbr/\u003e\nAll Map files are text files in the \".cub\" file format\u003cbr/\u003e\nYou can open the maps in the \"maps\" folder with a text editor for some examples\u003cbr/\u003e\n\n## 📁 Project Structure\n\n```\ncub3d/\n├── sources/\n│   ├── main.c\n│   ├── hooks/\n│   ├── movement/\n│   ├── parsing/\n│   ├── raycasting/\n│   ├── rendering/\n│   └── utils/\n├── maps/\n├── textures/\n├── Makefile\n└── README.md\n```\n\n## 🗺️ Implementation Roadmap\n\n### Phase 1: Environment Setup and Parsing\n- [x] Set up MinilibX environment\n- [x] Implement map file parsing (.cub format)\n- [x] Validate map structure and requirements\n- [x] Implement flood fill algorithm for map validation\n- [x] Parse texture paths and colors\n- [x] Error handling for invalid maps/textures\n\n### Phase 2: Basic Window and Graphics\n- [x] Initialize MLX window\n- [x] Set up basic image buffer system\n- [x] Implement window event handling (ESC to close)\n- [x] Basic pixel manipulation functions\n- [ ] Test rendering simple shapes\n\n### Phase 3: Player System\n- [x] Initialize player position and orientation\n- [x] Implement player movement (WASD keys)\n- [x] Add player rotation (arrow keys or mouse)\n- [x] Implement collision detection\n- [x] Add smooth movement and rotation\n- [ ] Variable speed implementation\n\n### Phase 4: Raycasting Algorithm Implementation\n\n#### Step 1: Ray Direction Calculation\n- [x] Implement camera plane setup\n- [x] Calculate ray direction for each screen column\n- [x] Set up player direction and plane vectors\n\n#### Step 2: Delta Distance Calculation\n- [x] Calculate delta distances for x and y grid intersections\n- [x] Implement grid position mapping\n\n#### Step 3: Step and Side Distance Calculation\n- [x] Calculate step directions (±1)\n- [x] Initialize side distances for ray traversal\n\n#### Step 4: Digital Differential Analysis (DDA)\n- [ ] Implement DDA algorithm\n- [ ] Wall detection logic\n- [ ] Track which side of wall was hit\n\n#### Step 5: Wall Height and Distance Calculation\n- [x] Calculate wall distance from player\n- [x] Determine wall height on screen\n- [x] Calculate draw start and end positions\n\n### Phase 5: Texture Implementation\n- [x] Load textures into memory buffers\n- [x] Implement texture coordinate calculation\n- [x] Map wall intersection to texture coordinates\n- [x] Handle different wall orientations (N, S, E, W)\n- [ ] Add shading for visual depth\n\n### Phase 6: Rendering Optimization\n- [ ] Implement pixel map system\n- [ ] Optimize image buffer manipulation\n- [x] Use MLX image functions instead of individual pixel drawing\n- [x] Implement ceiling and floor coloring\n- [x] Prevent screen flickering\n\n### Phase 7: Polish and Optimization\n- [ ] Fine-tune performance\n- [ ] Add visual enhancements\n- [ ] Implement smooth animations\n- [ ] Code cleanup and documentation\n- [ ] Memory leak checking with Valgrind\n\n## 🔧 Key Data Structures\n\n### Core Structures\n```c\ntypedef struct s_data\n{\n\tvoid\t*mlx;\n\tvoid\t*win;\n\tt_img\t*tex[NUM_TEXTURES];\n\tint\t\taction;\n\tdouble\tpos_x;\n\tdouble\tpos_y;\n\tdouble\trot;\n\tdouble\tplane_x;\n\tdouble\tplane_y;\n\tdouble\tdir_x;\n\tdouble\tdir_y;\n\tt_img\t*image;\n\tint\t\t**pixels_map;\n\tt_map\t*minfo;\n}\tt_data;\n\ntypedef struct s_img\n{\n    void    *img;\n    int     *addr;\n    int     bpp;\n    int     line_length;\n    int     endian;\n} t_img;\n\ntypedef struct s_map\n{\n\tchar\t**grid;\n\tint\t\twidth;\n\tint\t\theight;\n\tchar\t*north_texture;\n\tchar\t*south_texture;\n\tchar\t*east_texture;\n\tchar\t*west_texture;\n\tint\t\tfloor_color[3];\n\tint\t\tceiling_color[3];\n}\tt_map;\n```\n\n## 🎮 Controls\n- **W/A/S/D**: Move forward/left/backward/right\n- **Arrow Keys**: Rotate view left/right, Move forward/backward\n- **ESC**: Exit game\n\n## 🧮 Mathematical Concepts\n\n### Essential Formulas\n- **Ray Direction**: `ray_dir = player_dir + cam_dir + camera_plane * camera_x`\n- **Delta Distance**: `delta_dist = |1 / ray_dir|`\n- **Wall Distance**: `wall_dist = (map_pos - player_pos + adjustment) / ray_dir`\n- **Texture Coordinate**: `tex_x = wall_x * TEXTURE_SIZE`\n\n## 🚀 Performance Tips\n\n1. **Use Image Buffers**: Manipulate entire image buffer instead of individual pixels\n2. **Optimize Texture Access**: Use efficient array indexing for texture data\n3. **Minimize Function Calls**: Reduce MLX function calls in main loop\n4. **Efficient Memory Management**: Properly manage texture buffers\n5. **Variable Frame Rate**: Implement frame rate independent movement\n\n## 🐛 Common Pitfalls to Avoid\n\n- **Mathematical Understanding**: Don't skip learning the math behind raycasting\n- **Continuous Movement**: Implement proper key event handling for smooth movement\n- **Variable Speed**: Account for different computer performances\n- **Memory Leaks**: Properly free all allocated resources\n- **Texture Errors**: Handle texture loading failures gracefully\n- **Map Validation**: Thoroughly validate map file format\n\n## 📚 Recommended Resources\n\n- Raycasting tutorials and mathematical explanations\n- MinilibX documentation\n- Computer graphics fundamentals\n- Game development optimization techniques\n\n## 🧪 Testing\n\n### Test Cases\n- [ ] Various map configurations\n- [ ] Invalid map handling\n- [ ] Performance benchmarking\n- [ ] Memory leak testing with Valgrind\n- [ ] Edge case scenarios (corners, small spaces)\n\n### Debugging Tips\n- Use visual debugging (draw rays, mark positions)\n- Test with simple maps first\n- Verify mathematical calculations step by step\n- Check texture loading and indexing\n\n## 🤝 Team Collaboration\n\n### Division of Work Suggestions\n- **Person 1**: Parsing, validation, and setup\n- **Person 2**: Raycasting algorithm and rendering\n- **Both**: Testing, optimization, and documentation\n\n### Communication\n- Regular code reviews\n- Shared understanding of mathematical concepts\n- Coordinated testing and debugging sessions\n\n## 📝 Submission Checklist\n\n- [ ] Code compiles without warnings\n- [ ] All required features implemented\n- [ ] No memory leaks (Valgrind clean)\n- [ ] Proper error handling\n- [ ] Code follows 42 School norms\n- [ ] Performance meets expectations\n- [ ] Documentation complete\n\n## 🏆 Bonus Features Ideas\n\n- [x] Wall collision\n- [x] Minimap display\n- [ ] Sprite rendering\n- [ ] Sound effects\n- [ ] Multiple levels\n- [ ] Mouse look control\n\n---\n\n**Good luck with your Cub3D adventure! Remember: understanding the mathematics is crucial for successful implementation and debugging.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidriz4work%2Fcube3dd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fidriz4work%2Fcube3dd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidriz4work%2Fcube3dd/lists"}