{"id":17283671,"url":"https://github.com/danomatika/loaf","last_synced_at":"2025-04-14T10:13:36.653Z","repository":{"id":63090600,"uuid":"82973369","full_name":"danomatika/loaf","owner":"danomatika","description":"loaf: lua, osc, and openFrameworks ","archived":false,"fork":false,"pushed_at":"2025-04-02T16:17:19.000Z","size":4901,"stargazers_count":55,"open_issues_count":4,"forks_count":5,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-14T10:13:32.617Z","etag":null,"topics":["lua","openframeworks","osc"],"latest_commit_sha":null,"homepage":"http://danomatika.com/code/loaf","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danomatika.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.txt","contributing":null,"funding":null,"license":"LICENSE.txt","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":"2017-02-23T21:31:16.000Z","updated_at":"2025-04-02T16:17:23.000Z","dependencies_parsed_at":"2024-10-15T09:51:57.351Z","dependency_job_id":"6bd2d4c5-bcf8-415f-a2de-fd8ebdc101fe","html_url":"https://github.com/danomatika/loaf","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danomatika%2Floaf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danomatika%2Floaf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danomatika%2Floaf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danomatika%2Floaf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danomatika","download_url":"https://codeload.github.com/danomatika/loaf/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248860167,"owners_count":21173342,"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":["lua","openframeworks","osc"],"created_at":"2024-10-15T09:51:54.815Z","updated_at":"2025-04-14T10:13:36.640Z","avatar_url":"https://github.com/danomatika.png","language":"C++","readme":"loaf: lua, osc, and openFrameworks\n==================================\n\n![loaf icon](images/icon/icon-rounded.png)\n\nCopyright (c) [Dan Wilcox](danomatika.com) 2016-2025\n\nGPL v3\n\nFor information on usage and redistribution, and for a DISCLAIMER OF ALL\nWARRANTIES, see the file, \"LICENSE.txt,\" in this distribution.\n\n**loaf website**: [danomatika.com/code/loaf](http://danomatika.com/code/loaf)\n\nDESCRIPTION\n-----------\n\n\u003e cut off a slice of something nice\n\nloaf is an interpreter for [openFrameworks](http://openframeworks.cc) which allows you to write OF applications in the [Lua](http://www.lua.org) scripting language. This means you can quickly create using openFrameworks but without having to compile C++ or use a heavy IDE like Xcode or Visual Studio. A built-in OSC (Open Sound Control) server enables loaf to communicate natively with other creative coding and music applications over a network connection. Additionally, a built-in Syphon server allows for streaming loaf's screen output to visual applications on the same macoS system.\n\n\u003e Is loaf a replacement for building a native C++ application?\n\nNo. If you need to be able to include openFrameworks addons, stay with C++ for now.\n\n\u003e So what is it for?\n\nloaf is intended as a simple sandbox for sketching using the openFrameworks core API with a live-coding feel: make changes and see the result quickly. No compiling, no low level errors, just the basics. Think of loaf kind of like [Processing](http://processing.org) without the run button.\n\n![loaf workflow](doc/loaf_workflow.png)\n\n### Background\n\nloaf is the result of the author's need for a visual coding tool for performance that can run almost anywhere and communicate with tools such as [Pure Data](http://puredata.info) or [Max MSP](https://cycling74.com/products/max/). Using Lua allows for loaf to react to script changes so the process of creation matches that of a dataflow environment like Pd. The native inclusion of OSC allows for coupling of loaf and other creative applications for experimentation.\n\nloaf's design is influenced by the [LÖVE](https://love2d.org) Lua game engine and the [Fluxus](http://www.pawfal.org/fluxus/) live-coding environment. It is essentially the 3rd (or 4th) iteration of a similar tool for the author's [robotcowboy](http://robotcowboy.com) wearable performance project: [rc-visual](https://github.com/danomatika/rc-visual), originally a C++ application using [SDL](http://libsdl.org) which read XML scene descriptions and blitted to the console framebuffer. loaf is now used as the interpreter for rc-visual which is implemented completely in Lua and works with its controller input complement, [joyosc](https://github.com/danomatika/joyosc).\n\nQUICK START\n-----------\n\nDownload a release build from **[docs.danomatika.com/releases/loaf](http://docs.danomatika.com/releases/loaf/)** (currently macOS only) or build loaf after git cloning from [Github](https://github.com/danomatika/loaf)\n\nOnce you have a copy of loaf, drag the loaf.app into your Applications folder (macOS) or simple run it from the loaf folder by double-clicking.\n\n_Note: A more comprehensive User Guide will be added in the future._\n\n### Basic usage\n\n* Drag a Lua script or folder with a main.lua onto loaf to run it\n* Either save the script somehow (in a text editor) and/or use MOD+R in loaf to reload it automatically\n* Toggle fullscreen with MOD+F\n* Script errors are shown on the app window and on the console if you run it in a terminal application\n* Prints are shown in the console (useful for debugging)\n* The current script can be cleared with SHIFT+MOD+R\n\n_The MOD key depends on the platform: macOS COMMAND, Windows/Linux CONTROL._\n\n### Scripts, Folders, and Data Path\n\nloaf supports opening Lua scripts (.lua) and folders which contain a main.lua file. The folder option is useful for project encapsulation. Any data file paths are automatically relative to the script's parent folder, ie. loading an image from script.lua in the following project layout:\n\n    project/script.lua\n    project/image.jpg\n\nworks like this:\n\n    image = of.Image()\n    image:load(\"image.jpg\")\n\nThis also means Lua's require function works as expected when importing other Lua scripts or modules into  the main script.\n\n### Using Lua and OF\n\nA quick overview of using Lua and the Lua bindings for openFrameworks can be found in the [ofxLua readme](https://github.com/danomatika/ofxLua#of-api-bindings).\n\nThe best place to start is to look at the examples included with loaf zip and on the [loaf Github repo](https://github.com/danomatika/loaf/tree/master/examples).\n\nThere are also simple syntax lists for each of the built-in Lua bindings modules: of, osc, loaf, and syphon. These can be found in `doc/modules` and are a good place to start for creating auto-completion files for you favorite text editor.\n\n### Syphon Support\n\nOn macOS, loaf includes support for Syphon via a built-in server and a Lua \"syphon\" module with bindings for the ofxSyphonClient, ofxSyphonServer, and ofxSyphonServerDirectory classes.\n\nSimilar to the built-in OSC sender and receiver instances, the Syphon server can\nbe accessed via loaf module Lua functions:\n\n* loaf.startSyphon(): start server to publish screen each frame\n* loaf.stopSyphon(): stop server\n* loaf.setSyphonName(): set server name\n* loaf.isSyphonPublishing(): is the server publishing right now?\n* loaf.getSyphonServer(): get the built-in server instance\n\n_Note: Make sure to call loaf.getSyphonServer() *only* after starting the server, otherwise the instance will not exist, i.e returns as \"nil.\"_\n\nAdditionally, the \"syphon\" module allows for using Syphon directly in Lua scripts. See `examples/tests/syphon.lua`.\n\n### Setting Window Size\n\nBy default, loaf starts as a 640x480 window. If you want a different resolution or to go fullscreen, you can simply call the corresponding OF functions in your script:\n\n    function setup()\n        of.setWindowShape(1024, 768) -- resizes the window, like Processing size()\n        of.setFullscreen(true) -- go fullscreen! also the -f commandline option\n    end\n\n### loaf Commandline Options\n\nloaf has a number of options which can be set when running it from the commandline, the most basic being a script to run:\n\n    loaf path/to/script.lua\n\nUse -h to print a usage help print:\n\n~~~\nUsage: loaf [options] [PATH [args]]\n\n  lua, osc, and openFrameworks\n\nOptions:\n  -h, --help       print usage and exit\n  --version        print version and exit\n  -a, --address    OSC host address to send to (default: localhost)\n  -p, --port       OSC port to send to (default: 8880)\n  -l, --listen     OSC port to listen on (default: 9990)\n  -s, --start      start listening for OSC messages\n  -f, --fullscreen start in fullscreen\n  -i, --ignore     ignore script changes\n  -e, --exit       exit after script error\n  -r, --reload     reload timeout in secs after a script error\n  --gl             try to set gl version to use ie. \"4.1\"\n  --syphon-name    Syphon server name (default: screen)\n  --syphon         start streaming screen with Syphon (macOS only)\n  -v, --verbose    verbose printing\n\nArguments:\n  PATH             optional lua script or folder to run\n  args...          arguments to pass to the lua script\n~~~\n\nYou can also pass arguments to the script itself by placing them after the script path:\n\n    loaf script.lua hello 123\n\nSee the argument test script for more details: `examples/tests/arg.lua`\n\n#### macOS Terminal alias\n\nOn macOS, you can run a .app from Terminal by calling the binary hidden inside the application bundle:\n\n    /Applications/loaf.app/Contents/MacOS/loaf -h\n\nTo make this less cumbersome, you can add an alias in your .bash_profile:\n\n    alias loaf=\"/Applications/loaf.app/Contents/MacOS/loaf\"\n\nwhich allows you to call loaf with just the short alias instead:\n\n    loaf -h\n\n### Libraries\n\nAs loaf contains the Lua embedded scripting language, pure Lua libraries will work fine with it. Pre-compiled loadable Lua modules will also work as long as they are found within the `require` search path.\n\nAlso, a set of loaf-oriented Lua libraries is available in the [loaf-ingredients](https://github.com/danomatika/loaf-ingredients) repository.\n\nBUNDLING INTO STAND-ALONE APPS\n------------------------------\n\nAs of loaf 1.6.0, loaf projects can be \"bundled\" into stand-alone applications. If a \"main.lua\" script is found on startup, it will be used by default:\n\n* Windows / Linux: \"data\" folder next to loaf executable, `./data/`\n* macOS: \"data\" folder within a macOS .app bundle, `../Resources/data/`\n\nThe loaf executable can also be renamed.\n\n### macOS\n\nA macOS .app bundle is basically a folder structure presented by Finder as an \"application.\" It contains the application executable, dependent libraries, and resource files. This structure can be created \u0026 modified to make your own application which can then be distributed to run on other macOS systems.\n\nTo facilitate creating a stand-alone .app from a loaf project, the `scripts/make_osxapp.sh` shell script can make a copy of an existing loaf.app and use it to create a new application by copying the loaf project Lua scripts and data files inside the bundle. Additionally, it can modify metadata such as the application name, version string, and icon.\n\nFor example.\n\n    ./scripts/make_osxapp.sh -l bin/loaf.app ~/Desktop/loaf-project LoafProject\n\nwill create a `LoafProject.app` using the files in `~/Desktop/loaf-project`.\n\nSee the `make_osxapp.sh` help output for more info:\n\n    ./scripts/make_osxapp.sh --help\n\nBUILDING LOAF\n-------------\n\nTo build loaf, you will need a copy of openFrameworks: [http://openframeworks.cc/download/](http://openframeworks.cc/download/)\n\nloaf requires the following addons:\n\n* [ofxLua](https://github.com/danomatika/ofxLua)\n* ofxOsc (included with openFrameworks)\n* [ofxSyphon](https://github.com/astellato/ofxSyphon) (optional, macOS-only)\n\nProject files for building loaf on Windows or Linux are not included so you will need to generate them for your operating system and development environment using the OF ProjectGenerator which is included with the openFrameworks distribution.\n\nTo (re)generate project files for an existing project:\n\n* Click the \"Import\" button in the ProjectGenerator\n* Navigate to the base folder for the project ie. \"loaf\"\n* Click the \"Update\" button\n\nIf everything went Ok, you should now be able to open the generated project and build/run the example.\n\n### macOS\n\nOpen the Xcode project, select the \"loaf Release\" scheme, and hit \"Run\". Once built, the loaf.app is found in the `bin` directory.\n\nFor a Makefile build with Syphon (default), build and run on the terminal:\n\n    make ReleaseLoaf\n    make RunRelease\n\nIf not using Syphon, use the default make target:\n\n    make Release\n\n#### Updating Xcode Project After Generation\n\nIf the project is (re)generated using the OF ProjectGenerator, the openFrameworks-Info.plist file will be overwritten and these changes can be reversed with:\n\n    git checkout openFrameworks-Info.plist\n\n#### Enabling Syphon Support\n\nSyphon support must be enabled as a compile-time option using the `LOAF_USE_SYPHON` C++ define.\n\n* Select loaf project in the Xcode file tree\n* Select loaf under PROJECT list and Build Settings tab\n* Find Other C++ flags and add: `-DLOAF_USE_SYPHON`\n\nIf doing a Makefile build, use the additional targets which will also install the Syphon framework into loaf.app: `DebugLoaf` \u0026 `ReleaseLoaf`.\n\n#### Fixing Unknown option \"NSDocumentRevisionsDebugMode\"\n\nIf running the project does nothing except for showing the following console output:\n\n    Unknown option \"NSDocumentRevisionsDebugMode\"\n\nEdit the Debug and Release schemes and uncheck \"Document Versions\" in Run-\u003eOptions tab.\n\n### Linux\n\nTo build and run on the terminal:\n\n    make\n    make run\n\n### Windows\n\n_Instructions for Visual Studio to be added here. Contributions are welcome._\n\nDEVELOPING\n----------\n\nYou can help develop ofxLua on GitHub: https://github.com/danomatika/loaf\n\nCreate an account, clone or fork the repo, then request a push/merge.\n\nIf you find any bugs or suggestions please log them to GitHub as well.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanomatika%2Floaf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanomatika%2Floaf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanomatika%2Floaf/lists"}