{"id":13526511,"url":"https://github.com/bjornbytes/cargo","last_synced_at":"2025-10-24T23:04:59.292Z","repository":{"id":40522968,"uuid":"42832823","full_name":"bjornbytes/cargo","owner":"bjornbytes","description":"LÖVE asset manager","archived":false,"fork":false,"pushed_at":"2020-02-02T02:10:04.000Z","size":16,"stargazers_count":163,"open_issues_count":2,"forks_count":11,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-11-02T11:34:40.396Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Lua","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/bjornbytes.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":"2015-09-20T22:55:42.000Z","updated_at":"2024-09-12T08:53:17.000Z","dependencies_parsed_at":"2022-07-16T17:30:36.862Z","dependency_job_id":null,"html_url":"https://github.com/bjornbytes/cargo","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/bjornbytes%2Fcargo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjornbytes%2Fcargo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjornbytes%2Fcargo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjornbytes%2Fcargo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bjornbytes","download_url":"https://codeload.github.com/bjornbytes/cargo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225486619,"owners_count":17481934,"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":"2024-08-01T06:01:30.820Z","updated_at":"2025-10-24T23:04:59.274Z","avatar_url":"https://github.com/bjornbytes.png","language":"Lua","funding_links":[],"categories":["Utilities"],"sub_categories":[],"readme":"Cargo\n===\n\nCargo makes it easy to manage assets in a Love2D project by exposing project directories as Lua tables.\nThis means you can access your files from a table automatically without needing to load them first.\nAssets are lazily loaded, cached, and can be nested arbitrarily.\n\nYou can also manually preload sets of assets at a specific time to avoid loading hitches.\n\nExample\n---\n\nIf you have a project structured like this:\n\n```\n├── main.lua\n└── assets\n    ├── config\n    │   └── player\n    │       └── stats.lua\n    ├── fonts\n    │   └── my_font.ttf\n    └── images\n        └── player.png\n```\n\nThen you can do this:\n\n```lua\nassets = require('cargo').init('assets')\n\nfunction love.load()\n  print(assets.config.player.stats.maxHealth)\n  myFont = assets.fonts.my_font(16)\nend\n\nfunction love.draw()\n  love.graphics.draw(assets.images.player)\nend\n```\n\nAnd it will just work.  You can also do the following to expose your entire project as part of the Lua global scope:\n\n```lua\nsetmetatable(_G, {\n  __index = require('cargo').init('/')\n})\n```\n\nIn this example, if you have an image located at `images/player.png`, you can just call `love.graphics.draw(images.player)` without having to call `love.graphics.newImage`.\n\nAdvanced\n---\n\nThere are two ways to tell cargo to load a directory. The first is by passing in the name of the directory you want to load:\n\n```lua\nassets = cargo.init('my_assets')\n```\n\nThe second is by passing in an options table, which gives you more power over how things are loaded:\n\n```lua\nassets = cargo.init({\n  dir = 'my_assets',\n  loaders = {\n    jpg = love.graphics.newImage\n  },\n  processors = {\n    ['images/'] = function(image, filename)\n      image:setFilter('nearest', 'nearest')\n    end\n  }\n})\n```\n\nAfter something has been loaded, you can set it to `nil` to clear it from the cargo table.  Note\nthat it will only be garbage collected if nothing else references it.\n\nYou can also preload all of the assets in a cargo table by calling it (or any of its children) as a function:\n\n```lua\nassets = cargo.init('media')()     -- Load everything in 'media'\nassets = cargo.init('media')(true) -- Load everything in 'media', recursively\n\nassets.sound.background()          -- Preload all of the background music\n```\n\n### Loaders\n\nThe `loaders` option specifies how to load assets.\nCargo uses filename extensions to determine how to load files.\nThe keys of entries in the `loaders` table are the file extensions.\nThese map to functions that take in a filename and return a loaded asset.\nIn the above example, we run the function `love.graphics.newImage` on any filenames that end in `.jpg`.\n\nHere is a list of default loaders used:\n\n| Extension | Loader                    |\n| --------- | ------------------------- |\n| lua       | `love.filesystem.load`    |\n| png       | `love.graphics.newImage`  |\n| jpg       | `love.graphics.newImage`  |\n| dds       | `love.graphics.newImage`  |\n| ogv       | `love.graphics.newVideo`  |\n| glsl      | `love.graphics.newShader` |\n| mp3       | `love.audio.newSource`    |\n| ogg       | `love.audio.newSource`    |\n| wav       | `love.audio.newSource`    |\n| flac      | `love.audio.newSource`    |\n| txt       | `love.filesystem.read`    |\n| fnt       | `love.graphics.newFont`   |\n\nThe loader for `.ttf` and `.otf` files is special. Instead of directly returning an asset, this loader returns a function that accepts a size for the font and returns a new font with the specified size.\n\nThe loader for `.fnt` files requires the image file path to be set in the file as it won't be passed to [love.graphics.newFont](https://love2d.org/wiki/love.graphics.newFont#Function_3).\n\nTo have cargo ignore files with a certain extension, specify `false` as the loader.\n\n### Processors\n\nSometimes, it can be helpful to do some extra processing on assets after they are loaded.\nThis extra work can be configured by the `processors` option.\nThe keys are Lua patterns that match filenames, and the values are functions that get passed the asset and the filename of the asset.\nIn the above example, we set the scaling filter on all assets in the `images/` directory, regardless of extension.\n\nLicense\n---\n\nMIT, see [`LICENSE`](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjornbytes%2Fcargo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbjornbytes%2Fcargo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjornbytes%2Fcargo/lists"}