{"id":21148573,"url":"https://github.com/schwalbe-t/iridium","last_synced_at":"2025-03-25T07:44:40.991Z","repository":{"id":190865603,"uuid":"683493741","full_name":"schwalbe-t/iridium","owner":"schwalbe-t","description":"*The* library for 2D game development with the Vilm programming language.","archived":false,"fork":false,"pushed_at":"2023-08-27T18:51:42.000Z","size":25,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-30T07:16:18.601Z","etag":null,"topics":["2d-game","2d-game-framework","2d-graphics","3d-audio","game-2d","game-dev","game-developement","game-development"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/schwalbe-t.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":"2023-08-26T18:41:12.000Z","updated_at":"2023-08-26T18:49:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"0159c290-01f1-45ec-9c15-6f5f43f30198","html_url":"https://github.com/schwalbe-t/iridium","commit_stats":null,"previous_names":["typesafeschwalbe/iridium","schwalbe-t/iridium"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schwalbe-t%2Firidium","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schwalbe-t%2Firidium/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schwalbe-t%2Firidium/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schwalbe-t%2Firidium/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/schwalbe-t","download_url":"https://codeload.github.com/schwalbe-t/iridium/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245422920,"owners_count":20612725,"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":["2d-game","2d-game-framework","2d-graphics","3d-audio","game-2d","game-dev","game-developement","game-development"],"created_at":"2024-11-20T09:27:24.595Z","updated_at":"2025-03-25T07:44:40.970Z","avatar_url":"https://github.com/schwalbe-t.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Iridium\n\nIridium is *the* library for 2D game development in the [Vilm programming language](https://github.com/typesafeschwalbe/vilm). It features:\n\n- resource loading\n- vector math\n- 2D graphics\n- keyboard, mouse and touch input\n- 3D audio\n- 2D collision detection\n- entity component system (ECS)\n\n# Using Iridium in your Vilm project\n\nTo include Iridium in your project, first copy the `src` directory into your project sources and rename it (for example `iridium`). Then, include the `iridium.js`-script from that directory in your HTML.\nTo now load Iridium for an instance of Vilm pass the instance, the path of the directory containg all the iridium source files as a string and a canvas element to `iridium.load`, which will return the instance of Vilm you passed to it.\n\n```js\nwindow.onload = () =\u003e {\n    const vilm = iridium.load(\n        new Vilm(),   // Vilm instance\n        \"./src\",   // directory containing Iridium source files\n        document.getElementById(\"game\")   // canvas to draw onto\n    );\n    vilm.evalFiles(\"test.vl\");   // load files that depend on Iridium afterwards\n};\n```\n\n# Documentation\n\nNow that you have Iridium up and running, let's get familiar with the packages and the macros / functions they contain.\n\n## `iridium`\n\nThis package contains *ALL* macros and functions that are part of Iridium:\n```\npkg iridium\nuseall iridium:core\nuseall iridium:math\nuseall iridium:graphics\nuseall iridium:resources\nuseall iridium:input\nuseall iridium:audio\nuseall iridium:collision\nuseall iridium:ecs\n```\n\n## `iridium:core`\n\nThis package contains functions and macros related to the game loop.\n\n**`gameloop \u003cbody\u003e`** - Starts the gameloop, executing the given body for each frame. `\u003cbody\u003e` shall be an expression or list of expressions.\n\n**`delta_time`** - Returns the time passed since the last frame in seconds.\n\n## `iridium:math`\n\nThis package contains functions and macros related to vector math. A \"vector\" shall be a list of numbers, meaning a \"2D vector\" would be `(x y)`, a \"3D vector\" would be `(x y z)`, and so on. None of the functions in this package modify the vectors they are given.\n\n**`[dim] \u003cx\u003e`** - Returns the number of dimensions of the given vector.\n\n**`[+] \u003ca\u003e \u003cb\u003e`** - Returns the two given vectors added component-wise. Both values may also be a number.\n\n**`[-] \u003ca\u003e \u003cb\u003e`** - Returns the two given vectors subtracted component-wise. Both values may also be a number.\n\n**`[*] \u003ca\u003e \u003cb\u003e`** - Returns the two given vectors multiplied component-wise. Both values may also be a number.\n\n**`[/] \u003ca\u003e \u003cb\u003e`** - Returns the two given vectors divided component-wise. Both values may also be a number.\n\n**`[%] \u003ca\u003e \u003cb\u003e`** - Returns the two given vectors reduced to modulo component-wise. Both values may also be a number.\n\n**`[~] \u003cx\u003e`** - Returns the vector negated.\n\n**`[len] \u003cx\u003e`** - Returns the norm of the vector.\n\n**`[unit] \u003cx\u003e`** - Returns the vector as a unit vector pointing in the same direction.\n\n**`[dot] \u003ca\u003e \u003cb\u003e`** - Returns the dot product of the the given vectors.\n\n**`[cross] \u003ca\u003e \u003cb\u003e`** - Returns the cross product of the given vectors. Both vectors must be 3-dimensional.\n\n**`[rotated] \u003cx\u003e \u003cangle\u003e`** - Returns the given vector rotated by a given angle around the origin. The given vector must be 2-dimensional.\n\n**`[.x] \u003cx\u003e`** - Returns the x-component of the given vector.\n\n**`[.y] \u003cx\u003e`** - Returns the y-component of the given vector.\n\n**`[.z] \u003cx\u003e`** - Returns the z-component of the given vector.\n\n**`[.w] \u003cx\u003e`** - Returns the w-component of the given vector.\n\n**`[.] \u003cx\u003e \u003ccomponents\u003e`** - Returns a new vector, created by the specified components of the given vector in the specified order. `\u003ccomponents\u003e` shall be a single identifier. Example: calling `[.] (1 2 3) xzy` would result in `(1 3 2)`, or `[.] (4 5 6) zzx` in `(6 6 4)`. [More info about swizzling here](https://en.wikipedia.org/wiki/Swizzling_(computer_graphics)).\n\n## `iridium:graphics`\n\nThis package contains functions and macros related to 2D graphics.\n\n**`Color \u003cr\u003e \u003cg\u003e \u003cb\u003e`** - Returns a new object representing the given color. All three values shall be numbers in the range of 0 to 255.\n\n**`enabled`** - A fancier alternative to `true`.\n\n**`disabled`** - A fancier alternative to `false`.\n\n**`Surface \u003csize\u003e`** - Returns a new surface with the given size. `\u003csize\u003e` shall be a 2-dimensional vector.\n\n**`canvas`** - Returns the surface representing the canvas that was provided to Iridium at load time.\n\n**`render_text \u003cheight\u003e \u003ccontent\u003e \u003cfont_family\u003e \u003ccolor\u003e`** - Returns a new transparent surface with the given text rendered onto it with the given font family and color. \n\n**`size_of \u003csurface\u003e`** - Returns a vector representing the size of the given surface.\n\n**`target \u003csurface\u003e`** - Configures *all drawing operations* to be done on the given surface.\n\n**`current_target`** - Returns the surface that is the current target of all drawing operations.\n\n**`with_target \u003csurface\u003e \u003cbody\u003e`** - Configures *all drawing operations* to be done on the given surface, but *only as long as the provided body is executed*. `\u003cbody\u003e` shall be an expression or list of expressions.\n\n**`custom \u003cv1\u003e \u003cv2\u003e`** - Returns a function representing the creation of a 2D transformation matrix with custom values. `\u003cv1\u003e` and `\u003cv2\u003e` shall be 3-dimensional vectors.\n\n**`translate \u003coffset\u003e`** - Returns a function representing translation by the given offset. `\u003coffset\u003e` shall be a 2-dimensional vector.\n\n**`rotate \u003cangle\u003e`** - Returns a function representing rotation around the origin by a given angle.\n\n**`scale \u003camount\u003e`** - Returns a function representing scaling by a given amount on the x- and y-axis. `\u003camount\u003e` shall be a 2-dimensional vector.\n\n**`transformation \u003ctransformations\u003e`** - Configures the given transformations to be applied to *all drawing operations*. `\u003ctransformations\u003e` shall be a list of functions returned from calls to `custom`, `translate`, `rotate` and `scale`.\n\n**`with_transformation \u003ctransformations\u003e \u003cbody\u003e`** - Configures the given transformations to be applied to *all drawing operations*, but *only as long as the provided body is executed*. `\u003ctransformations\u003e` shall be a list of functions returned from calls to `custom`, `translate`, `rotate` and `scale`. `\u003cbody\u003e` shall be an expression or list of expressions.\n\n**`image_smoothing \u003cenabled\u003e`** - Configures image smoothing to be enabled or disabled for *all drawing operations*.\n\n**`current_image_smoothing`** - Returns if image smoothing is currently enabled.\n\n**`with_image_smoothing \u003cenabled\u003e \u003cbody\u003e`** - Configures image smoothing to be enabled or disabled for *all drawing operations*, but *only as long as the provided body is executed*. `\u003cbody\u003e` shall be an expression or list of expressions.\n\n**`composition \u003ccomposition_operation\u003e`** - Configures the [composition operation](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Compositing/Example) for *all drawing operations*.\n\n**`current_composition`** - Returns the current composition operation.\n\n**`with_composition \u003ccomposition_operation\u003e \u003cbody\u003e`** - Configures the [composition operation](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Compositing/Example) for *all drawing operations*, but *only as long as the provided body is executed*. `\u003cbody\u003e` shall be an expression or list of expressions.\n\n**`alpha \u003calpha\u003e`** - Configures the amount of alpha to use for *all drawing operations*. The alpha value shall be a number in the range of 0 to 255.\n\n**`current_alpha`** - Returns the current alpha value.\n\n**`with_alpha \u003calpha\u003e \u003cbody\u003e`** - Configures the amount of alpha to use for *all drawing operations*, but *only as long as the provided body is executed*. The alpha value shall be a number in the range of 0 to 255. `\u003cbody\u003e` shall be an expression or list of expressions.\n\n**`draw_rect \u003cd_pos\u003e \u003cd_size\u003e \u003ccolor\u003e`** - Draws a rectangle at the given position with the given size and the given color. `\u003cd_pos\u003e` and `\u003cd_size\u003e` shall be 2-dimensional vectors. `\u003ccolor\u003e` shall be a `Color`.\n\n**`draw_oval \u003cd_pos\u003e \u003cd_size\u003e \u003ccolor\u003e`** - Draws an oval that has the box described by the given position and the given size as its bounds with the given color. `\u003cd_pos\u003e` and `\u003cd_size\u003e` shall be 2-dimensional vectors. `\u003ccolor\u003e` shall be a `Color`.\n\n**`draw_subsurface \u003cd_pos\u003e \u003cd_size\u003e \u003csurface\u003e \u003csrc_pos\u003e \u003csrc_size\u003e`** - Draws a given surface at the given position with the given size, drawing only the part of the surface at the given position with a given size. `\u003cd_pos\u003e`, `\u003cd_size\u003e`, `\u003csrc_pos\u003e` and `\u003csrc_size\u003e` shall be 2-dimensional vectors.\n\n**`draw_surface \u003cd_pos\u003e \u003cd_size\u003e \u003csurface\u003e`** - Draws a given surface at the given position with the given size. `\u003cd_pos\u003e` and `\u003cd_size\u003e` shall be 2-dimensional vectors.\n\n**`draw_subimage \u003cd_pos\u003e \u003cd_size\u003e \u003cimage\u003e \u003csrc_pos\u003e \u003csrc_size\u003e`** - Draws a given image at the given position with the given size, drawing only the part of the image at the given position with a given size. `\u003cd_pos\u003e`, `\u003cd_size\u003e`, `\u003csrc_pos\u003e` and `\u003csrc_size\u003e` shall be 2-dimensional vectors. `\u003cimage\u003e` shall be a loaded image file returned from a call to `getr` (from `iridium:resources`).\n\n**`draw_image \u003cd_pos\u003e \u003cd_size\u003e \u003cimage\u003e`** - Draws a given image at the given position with the given size. `\u003cd_pos\u003e` and `\u003cd_size\u003e` shall be 2-dimensional vectors. `\u003cimage\u003e` shall be a loaded image file returned from a call to `getr` (from `iridium:resources`).\n\n**`draw_line \u003cstart_pos\u003e \u003cend_pos\u003e \u003cwidth\u003e \u003ccolor\u003e`** - Draws a line from the given start position to the given end position with the given width and color.  `\u003cstart_pos\u003e` and `\u003cend_pos\u003e` shall be 2-dimensional vectors. `\u003ccolor\u003e` shall be a `Color`.\n\n**`draw_quadratic_bezier \u003cstart_pos\u003e \u003cc1_pos\u003e \u003cend_pos\u003e \u003cwidth\u003e \u003ccolor\u003e`** - Draws a bezier curve from the given start position over the given control point to the given end position with the given width and color. `\u003cstart_pos\u003e`, `\u003cc1_pos\u003e` and `\u003cend_pos\u003e` shall be 2-dimensional vectors. `\u003ccolor\u003e` shall be a `Color`.\n\n**`draw_cubic_bezier \u003cstart_pos\u003e \u003cc1_pos\u003e \u003cc2_pos\u003e \u003cend_pos\u003e \u003cwidth\u003e \u003ccolor\u003e`** - Draws a bezier curve from the given start position over the given control points to the given end position with the given width and color. `\u003cstart_pos\u003e`, `\u003cc1_pos\u003e`, `\u003cc2_pos\u003e` and `\u003cend_pos\u003e` shall be 2-dimensional vectors. `\u003ccolor\u003e` shall be a `Color`.\n\n**`draw_shape js \u003clines\u003e \u003ccolor\u003e`** - Draws a shape that has the given lines as its outline with the given color. `\u003clines\u003e` shall be a list of at least three elements, each of which shall be a list consisting of 1 2-dimensional vector (straight line), 2 2-dimensional vectors (quadratic bezier) or 3 2-dimensional vectors (cubic bezier). The first element must be a list consisting of a single 2-dimensional vector. `\u003ccolor\u003e` shall be a `Color`.\n\n## `iridium:resources`\n\nThis package contains functions and macros related to loading resources from files.\n\n**`Image \u003cpath\u003e`** - Represents a path to a file containing image data.\n\n**`Audio \u003cpath\u003e`** - Represents a path to a file containing audio data.\n\n**`load \u003cresources\u003e`** - Loads a list of resources. `\u003cresources\u003e` shall be a list containing objects returned from calls to `Image` and `Audio` and returns an object representing them.\n\n**`when_loaded \u003cres\u003e \u003cbody\u003e`** - Executes the given body when all the resources in the provided resource bundle have finished loading. `\u003cres\u003e` shall be an object returned from a call to `load`. `\u003cbody\u003e` shall be an expression or list of expressions.\n\n**`getr \u003cres\u003e \u003cpath\u003e`** - Returns the object loaded from a given path from inside of a given resource bundle. `\u003cres\u003e` shall be an object returned from a call to `load`, and shall have finished loading. `\u003cpath\u003e` shall be the exact same path passed to `Image` or `Audio`.\n\n## `iridium:input`\n\nThis package contains functions and macros related to keyboard, mouse and touch input.\n\n**`Key:CtrlL` `Key:CtrlR` `Key:ShiftL` `Key:ShiftR` `Key:Space` `Key:Backspace` `Key:Enter` `Key:AltL` `Key:AltR`\n`Key:A` `Key:B` `Key:C` `Key:D` `Key:E` `Key:F` `Key:G` `Key:H` `Key:I` `Key:J` `Key:K` `Key:L` `Key:M` `Key:N` `Key:O` `Key:P` `Key:Q` `Key:R` `Key:S` `Key:T` `Key:U` `Key:V` `Key:W` `Key:X` `Key:Y` `Key:Z`\n`Key:ArrUp` `Key:ArrDown` `Key:ArrLeft` `Key:ArrRight`\n`Key:0` `Key:1` `Key:2` `Key:3` `Key:4` `Key:5` `Key:6` `Key:7` `Key:8` `Key:9`\n`Key:F1` `Key:F2` `Key:F3` `Key:F4` `Key:F5` `Key:F6` `Key:F7` `Key:F8` `Key:F9` `Key:F10` `Key:F11` `Key:F12`\n`Key:Esc`** - Represent keys on the keyboard.\n\n**`is_pressed \u003ckey\u003e`** - Returns a boolean representing if the given key is pressed. `\u003ckey\u003e` shall be one of `Key:XXX`.\n\n**`Button:Left` `Button:Scroll` `Button:Right`** - Represent mouse buttons.\n\n**`is_clicked \u003cbutton\u003e`** - Returns a boolean representing if the given button is clicked. If touch input is received, `Button:Left` will be registered as clicked. `\u003cbutton\u003e` shall be one of `Button:XXX`.\n\n**`cursor_position`** - Returns a 2-dimensional vector representing the position of the cursor on the canvas. If touch input is received, the \"primary\" touch position is returned.\n\n**`touch_positions`** - Returns a list of 2-dimensional vectors representing the positions of all received touches.\n\n## `iridium:audio`\n\nThis package contains functions and macros related to 3D audio.\n\n**`set_listener_position \u003cpos\u003e`** - Sets the position of the audio listener. `\u003cpos\u003e` shall be a 3-dimensional vector.\n\n**`set_listener_orientation \u003cat\u003e \u003cup\u003e`** - Sets the orientation of the audio listener to look in the given direction, with the given vector pointing up. `\u003cat\u003e` and `\u003cup\u003e` shall be 3-dimensional vectors.\n\n**`set_listener_volume \u003cvolume\u003e`** - Sets the volume of all the audio perceived by the audio listener. \n\n**`AudioSource \u003cposition\u003e`** - Returns a new audio source, configured to be at the given position. `\u003cposition\u003e` shall be a 3-dimensional vector.\n\n**`set_source_position \u003csource\u003e \u003cposition\u003e`** - Sets the position of the given audio source. `\u003csource\u003e` shall be an `AudioSource`. `\u003cposition\u003e` shall be a 3-dimensional vector.\n\n**`set_source_volume \u003csource\u003e \u003cvolume\u003e`** - Sets the playback volume of the given audio source. `\u003csource\u003e` shall be an `AudioSource`.\n\n**`set_source_pitch \u003csource\u003e \u003cpitch\u003e`** - Sets the playback pitch of the given audio source. `\u003csource\u003e` shall be an `AudioSource`.\n\n**`set_source_repeating \u003csource\u003e \u003crepeating\u003e`** - Configures the given audio source to repeat the audio that's played back over and over again. `\u003csource\u003e` shall be an `AudioSource`.\n\n**`play \u003csource\u003e \u003caudio\u003e`** - Plays the given audio from the given audio source. `\u003csource\u003e` shall be an `AudioSource`. `\u003caudio\u003e` shall be a loaded audio file returned from a call to `getr` (from `iridium:resources`).\n\n**`is_playing \u003csource\u003e`** - Returns a boolean representing if the given audio source is currently playing back audio.`\u003csource\u003e` shall be an `AudioSource`.\n\n## `iridium:collision`\n\nThis package contains functions and macros related to 2D collision.\n\n**`BoxCollider \u003cpos\u003e \u003csize\u003e`** - Returns an object representing a 2-dimensional, axis aligned box collider. `\u003cpos\u003e` shall be a 2-dimensional vector.\n\n**`CircleCollider \u003cpos\u003e \u003cradius\u003e`** - Returns an object representing a circle collider. `\u003cpos\u003e` shall be a 2-dimensional vector.\n\n**`colliding_with \u003ca\u003e \u003cb\u003e`** - Returns a boolean representing if the two given colliders overlap. `\u003ca\u003e` and `\u003cb\u003e` shall be objects returned from calls to `BoxCollider` and `CircleCollider`.\n\n## `iridium:ecs`\n\nThis package contains functions and macros related to Iridium's entity component system (ECS).\n\n**`system \u003cbody\u003e`** - Registers a system with the given body. The system will only start being called every frame once `gameloop` (from `iridium:core`) has been invoked. `\u003cbody\u003e` shall be a list of expressions.\n\n**`component \u003cname\u003e \u003cvalue\u003e`** - Registers a component with the given name and default value. `\u003cname\u003e` shall be a single identifier.\n\n**`entity \u003cname\u003e \u003ccomponent_names\u003e`** - Registers an entity with the given name and contained components. A function with the name of the entity will be registered in the package the macro was invoked from, which can be invoked to create new instances of the entity. `\u003cname\u003e` shall be a single identifier. `\u003ccomponent_names\u003e` shall be a list of single identifiers, being names of already registered components.\n\n**`entities`** - Returns an iterator over all entity instances.\n\n**`entities_called \u003cname\u003e`** - Returns an iterator over all entity instances of the given name. `\u003cname\u003e` shall be a single identifier.\n\n**`entities_with \u003ccomponent_names\u003e`** - Returns an iterator over all entity instances that have all the given components. `\u003ccomponent_names\u003e` shall be a single identifier or list of single identifiers, being names of already registered components.\n\n**`delete_entity \u003centity\u003e`** - Removes the given entity from the ECS. **DO NOT USE THE ENTITY AFTERWARDS**, as the ECS will keep a reference to it to reuse it when a new entity of the same name is created.\n\n**`hasc \u003ce\u003e \u003ccomponent_name\u003e`** - Returns a boolean representing if the given entity instance has a component with the given name. `\u003ccomponent_name\u003e` shall be a single identifier.\n\n**`setc \u003ce\u003e \u003ccomponent_name\u003e \u003cvalue\u003e`** - Sets the value of the component with the given name of the given entity instance. `\u003ccomponent_name\u003e` shall be a single identifier, being the name of a component inside of the entity instance.\n\n**`getc \u003ce\u003e \u003ccomponent_name\u003e`** - Gets the value of the component with the given name of the given entity instance. `\u003ccomponent_name\u003e` shall be a single identifier, being the name of a component inside of the entity instance.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschwalbe-t%2Firidium","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fschwalbe-t%2Firidium","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschwalbe-t%2Firidium/lists"}