{"id":13451172,"url":"https://github.com/soulweaver91/project-carrot","last_synced_at":"2025-03-23T18:31:58.413Z","repository":{"id":19267103,"uuid":"22503316","full_name":"soulweaver91/project-carrot","owner":"soulweaver91","description":"Project Carrot, an open source spiritual clone of the Jazz Jackrabbit 2 game engine","archived":false,"fork":false,"pushed_at":"2017-08-28T22:16:29.000Z","size":2917,"stargazers_count":39,"open_issues_count":20,"forks_count":4,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-10-28T18:14:47.297Z","etag":null,"topics":["bass","bass-fx","c-plus-plus","game-engine","jazz-jackrabbit","platformer","qt5","sfml"],"latest_commit_sha":null,"homepage":"https://carrot.soulweaver.fi/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/soulweaver91.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}},"created_at":"2014-08-01T09:27:08.000Z","updated_at":"2024-09-12T05:51:30.000Z","dependencies_parsed_at":"2022-08-30T23:40:59.862Z","dependency_job_id":null,"html_url":"https://github.com/soulweaver91/project-carrot","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soulweaver91%2Fproject-carrot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soulweaver91%2Fproject-carrot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soulweaver91%2Fproject-carrot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soulweaver91%2Fproject-carrot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/soulweaver91","download_url":"https://codeload.github.com/soulweaver91/project-carrot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245149415,"owners_count":20568903,"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":["bass","bass-fx","c-plus-plus","game-engine","jazz-jackrabbit","platformer","qt5","sfml"],"created_at":"2024-07-31T07:00:49.283Z","updated_at":"2025-03-23T18:31:53.377Z","avatar_url":"https://github.com/soulweaver91.png","language":"C++","funding_links":[],"categories":["Game \u0026 Studio Tools","C++"],"sub_categories":["Epic Games"],"readme":"![Project Carrot logo](https://raw.githubusercontent.com/soulweaver91/project-carrot/master/Data/PCLogo-300px.png)\n\n# Project Carrot\n\n[![AppVeyor build status](https://ci.appveyor.com/api/projects/status/2f9f6k3x3mytjifj?svg=true)](https://ci.appveyor.com/project/soulweaver91/project-carrot)\n[![Travis CI build Status](https://travis-ci.org/soulweaver91/project-carrot.svg)](https://travis-ci.org/soulweaver91/project-carrot)\n\nProject Carrot is a slowly progressing spiritual clone of the engine for Jazz Jackrabbit 2.\nYou can discuss it [here](http://www.jazz2online.com/jcf/showthread.php?t=19535).\n\n## Building\n\n### Common dependencies\n\n* [Qt](http://qt-project.org/downloads) 5.7 with Qt Gamepad Technology Preview addon installed\n* [SFML](http://www.sfml-dev.org/download.php) 2.3\n* [BASS](http://www.un4seen.com/bass.html) 2.4 and a compatible version of BASS FX\n\nIf you are planning to use a compiler different than one listed below, make sure it is\nsufficiently C++14 compliant as the codebase utilizes many of the more modern C++ features.\n\n### Windows\n\nThe suggested development environment, as well as the primary environment the code is written on,\nis [Microsoft Visual Studio 2015](http://www.visualstudio.com/). MSVC Windows build status is\nautomatically evaluated at [AppVeyor](https://ci.appveyor.com/project/soulweaver91/project-carrot).\n\nIf using Visual Studio, configure the Qt paths with the MSVS plugin and set the appropriate\nvalues for the `SFML_DIR`, `BASS_DIR`, and `BASS_FX_DIR` user macros in the user property\nsheets (`Microsoft.Cpp.Win32.user` and `Microsoft.Cpp.x64.user`). These are global to\nall projects you compile with Visual Studio, so if you are going to compile the related\nProject Carrot projects, you don't have to add these for them separately. Alternatively,\nsetting these as environment variables should work as well.\n\n### Linux\n\n[GCC 5.3](https://gcc.gnu.org/) or above and [Clang 3.7](http://clang.llvm.org/) or above are\nprovisionally supported and builds on the listed versions are automatically evaluated at\n[Travis CI](https://travis-ci.org/soulweaver91/project-carrot).\n\nDownload and extract the BASS and BASS FX Linux archives from their homepage and set\nSet the `BASS_DIR` and `BASS_FX_DIR` to point into that directory, and also add them\nto your `CPATH`. Additionally, install the other dependencies if you haven't done so\nalready. Then, configure and build the project, using the `spec` value corresponding \nto the compiler in use.\n\nFor example, a full set of commands that should get you started on a fresh Ubuntu Xenial\ninstallation:\n\n```shell\n# Add a Qt 5.7 repository to APT\nsudo add-apt-repository ppa:beineri/opt-qt571-xenial\n# Refresh package lists and install required packages\nsudo apt-get update\nsudo apt-get install git clang qt57base qt57gamepad libsfml-dev\n# Download BASS and BASS FX and uncompress them to your home folder\ncd ~\ncurl -o bass24.zip http://us.un4seen.com/files/bass24-linux.zip\ncurl -o bassfx24.zip http://us.un4seen.com/files/z/0/bass_fx24-linux.zip\nunzip bass24.zip -d bass\nunzip bassfx24.zip -d bassfx\nrm bass24.zip bassfx24.zip\n# Set up the necessary environment\n. /opt/qt57/bin/qt57-env.sh\nexport BASS_DIR=~/bass\nexport BASS_FX_DIR=~/bassfx\n# Clone this repository and compile the code\ngit clone https://github.com/soulweaver91/project-carrot.git\ncd project-carrot\nqmake -spec linux-clang\nmake release\n# Move to the release folder and copy the BASS and BASS FX library files\ncd Release\n# If on a 64-bit system:\ncp $BASS_DIR/x64/libbass.so .\ncp $BASS_FX_DIR/x64/libbass_fx.so .\n# If on a 32-bit system:\ncp $BASS_DIR/libbass.so .\ncp $BASS_FX_DIR/libbass_fx.so .\n```\n\nAssuming you got through these steps without any errors, you should now have an executable file\ncalled CarrotQt5 in the Release folder almost ready to go. The only thing left to do is to\ncopy over the asset, level, music and tileset files you converted with the other tools.\n\nIf in doubt, take a look at the [Travis configuration file](https://github.com/soulweaver91/project-carrot/blob/master/.travis.yml)\nand see if it can help you.\n\n### macOS\n\nProject Carrot can be compiled and run on macOS. You can either use Qt tools directly from the\ncommand line or use the included Xcode project, though at the moment neither of these approaches is\nfully bullet-proof.\n\n#### Option one: Qt command line\n\nFirst, make sure you have Xcode and Homebrew installed. Then, follow this script:\n\n```shell\n# Install required packages\nbrew install qt5 sfml\nbrew link qt5 --force\ncd ~\n# Download BASS and BASS FX\ncurl -o bass24.zip http://us.un4seen.com/files/bass24-osx.zip\ncurl -o bassfx24.zip http://us.un4seen.com/files/z/0/bass_fx24-osx.zip\nunzip bass24.zip -d bass\nunzip bassfx24.zip -d bassfx\nrm bass24.zip bassfx24.zip\n# Set up the necessary environment\nexport BASS_DIR=~/bass\nexport BASS_FX_DIR=~/bassfx\n# Clone this repository and compile the code\ngit clone https://github.com/soulweaver91/project-carrot.git\ncd project-carrot\nqmake -spec macx-clang\nmake release\n# Copy Qt and SFML dependencies into the bundle (only necessary for distribution)\nmacdeployqt Release/CarrotQt5.app\n# Copy other dependencies into the bundle\ncp $BASS_DIR/libbass.dylib Release/CarrotQt5.app/Contents/MacOS\ncp $BASS_FX_DIR/libbass_fx.dylib Release/CarrotQt5.app/Contents/MacOS\n```\n\nFollowing these steps should leave you with a bundle in the `Release` folder that you can run.\nThe caveat to this approach is that the bundle completely lacks identity and at this time it\nis not clear what would be the best practice for generating a coherent `Info.plist` file to\nfix that. (Copying as-is the existing stub, used by Xcode, will just break the application.)\nIf it was known, it'd go somewhat like\n\n```shell\n# Generate the icon file\nmkdir -p Release/CarrotQt5.app/Contents/Resources\ncp -r CarrotQt5.xcassets/AppIcon.appiconset ./tmp.iconset\nrm tmp.iconset/Contents.json\niconutil -c icns tmp.iconset\nrm -r tmp.iconset\ncp tmp/AppIcon.icns Release/CarrotQt5.app/Contents/AppIcon.icns\n# Generate finished Info.plist\n# ...\ncp GeneratedInfo.plist Release/CarrotQt5.app/Contents/Info.plist\n```\n\nDue to the compilation being tightly woven with the Qt project files, the advantage of\nthis method is that all builds that work on Linux (that is, hopefully all of them)\nalso work with this method. Barring rare exceptions that involve OS-specific code bits,\nof course.\n\n#### Option two: Xcode\n\nThe repository also contains an Xcode project that can be used to build Project Carrot.\nHowever, keeping these project files up to date would need a lot of unnecessary shuffling\nwhenever any work was done in the main environment (VS in Windows), so for most of the time,\n***the Xcode project will likely not compile***. Please check out the branch `xcode-master` if\nyou want to compile with Xcode and don't mind missing the latest features.\n\nMake sure you have Xcode and Homebrew installed, install Qt, SFML and BASS as above and\nopen the project. Some filenames in the project might use hard-coded paths with too narrow\nassumptions about where files can be. This is sometimes unavoidable; you'll need to fix\nthose for your own set-up first.\n\nBuilding with Xcode has the advantage that you don't need to deal with all the command line\nmumbo jumbo but can instead compile the whole thing by just clicking a button. The Xcode\nbuild also sets up the bundle properly so that it has its proper name, icon and other metadata.\n\nIdeally, qmake's tool that generates the project from the Qt .pro file (as was used)\nwould also be able to update an existing project. Alas, it doesn't appear to be able to do so.\n\n#### Summary\n\n|                                     | `qmake` + `make` | Xcode         |\n| :---                                | :---:            | :---:         |\n| Can compile `master`?               | :+1:             | :no_entry:    |\n| Can compile `xcode-master`?         | :+1:             | :+1:          |\n| Assembly required?                  | Quite a bit      | A little      |\n| Problems with paths?                | Minimal          | Probable      |\n| Can build debug features?           | :+1:             | Some          |\n| Can build complete bundle metadata? | :no_entry:       | :+1:          |\n| Tested in Travis CI?                | :+1:             | :no_entry:    |\n\nSo, if you are going to deploy a new version to the world (= be me), use Xcode;\notherwise best to stick to command line unless you really know what you're doing.\n\n## Running the game\n\nTo be able to run Project Carrot, you are required to extract the Jazz Jackrabbit 2 assets from\nthe `Anims.j2a` file in its installation folder. A tool specifically targeting Project Carrot,\n[PCAE](https://github.com/soulweaver91/project-carrot-pcae), will automate this task for you,\nnot only dumping the graphics and sounds but also assigning them an uniform name independent of\ntheir location inside the file itself. Those files should be moved to `Data\\Assets` relative\nto the project root or the compiled executable. It is safe to merge that folder to the one in\nthis repository, as the filetypes output by PCAE are excluded automatically and so should not\nend up in any potential commits later on.\n\nYou should also convert some tilesets and levels for yourself.\n[PCTC](https://github.com/soulweaver91/project-carrot-pctc) and\n[PCLC](https://github.com/soulweaver91/project-carrot-pclc) do this for you; make sure you\nalways convert the levels with the latest version of PCLC for highest level of compatibility\nwith the latest Project Carrot builds. As for music, you should convert the J2B files manually\nfor now to a more compatible format, such as .it, for example with OpenMPT on Windows. After\nconverting the levels, make sure the filename in the `config.ini` file for each level\ncorresponds exactly to a file in the music folder.\n\nPut the level folders into a folder called `Levels` right under the Project Carrot root folder,\ncreating it if it likely doesn't exist. Same applies to tileset folders, which go to `Tilesets`,\nand music files, which go to `Music`.\n\nOn Windows, you must put the relevant DLL files for Qt, SFML and BASS into a location the\napplication could expect to find them from, for example right into the same folder as the\nexecutable itself. On Linux, as long as both Qt 5 and SFML libraries have been installed,\nyou only need to copy `libbass.so` and `libbass_fx.so` to the same folder as the\nexecutable.\n\n## License\n\nThis software is licensed under the [MIT License](https://opensource.org/licenses/MIT).\nSee the included `LICENSE` file for the licenses of the third-party libraries used.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoulweaver91%2Fproject-carrot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoulweaver91%2Fproject-carrot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoulweaver91%2Fproject-carrot/lists"}