/ 
WWW-MetaForge-0.002
/ WWW::MetaForge::ArcRaiders

NAME

WWW::MetaForge::ArcRaiders - Perl client for the MetaForge ARC Raiders API

VERSION

version 0.002

SYNOPSIS

use WWW::MetaForge::ArcRaiders;

my $api = WWW::MetaForge::ArcRaiders->new;

# Get items
my $items = $api->items;
for my $item (@$items) {
    say $item->name . " (" . $item->rarity . ")";
}

# Search with parameters
my $ferro = $api->items(search => 'Ferro');

# Event timers with helper methods
my $events = $api->event_timers;
for my $event (@$events) {
    say $event->name;
    say "  Active!" if $event->is_active_now;
}

# Disable caching
my $api = WWW::MetaForge::ArcRaiders->new(use_cache => 0);

# For async usage (e.g., with WWW::Chain)
my $request = $api->request->items(search => 'Ferro');

DESCRIPTION

Perl interface to the MetaForge ARC Raiders API for game data (items, ARCs, quests, traders, event timers, map data).

maps

my @maps = $api->maps;

Returns list of available ARC Raiders map IDs (e.g., dam, spaceport, buried-city, blue-gate, stella-montis).

map_display_names

my %names = $api->map_display_names;

Returns hash of map ID to display name (e.g., dam => "Dam").

map_display_name

my $name = $api->map_display_name('dam');  # "Dam"

Returns human-readable display name for a map ID. Falls back to the ID itself if no display name is available.

ua

LWP::UserAgent instance. Built lazily with sensible defaults.

request

WWW::MetaForge::ArcRaiders::Request instance for creating HTTP::Request objects. Use for async framework integration.

cache

WWW::MetaForge::Cache instance for response caching.

use_cache

Boolean, default true. Set to false to disable caching.

cache_dir

Optional Path::Tiny path for cache directory. Defaults to XDG cache dir on Unix, LOCALAPPDATA on Windows.

json

JSON::MaybeXS instance for encoding/decoding JSON responses.

debug

Boolean. Enable debug output. Also settable via $ENV{WWW_METAFORGE_ARCRAIDERS_DEBUG}.

game_map_data

WWW::MetaForge::GameMapData instance used for map_data calls. Configured automatically with ARC Raiders specific marker class.

items

my $items = $api->items(%params);

Returns ArrayRef of WWW::MetaForge::ArcRaiders::Result::Item from first page. Supports search, page, limit parameters.

items_paginated

my $result = $api->items_paginated(%params);
my $items = $result->{data};
my $pagination = $result->{pagination};

Returns HashRef with data (items ArrayRef) and pagination info (total, page, totalPages, hasNextPage).

items_all

my $items = $api->items_all(%params);

Fetches all pages and returns complete ArrayRef of all items. Use with caution on large datasets.

arcs

my $arcs = $api->arcs(%params);

Returns ArrayRef of WWW::MetaForge::ArcRaiders::Result::Arc from first page. Supports includeLoot parameter.

arcs_paginated

my $result = $api->arcs_paginated(%params);

Returns HashRef with data and pagination info.

arcs_all

my $arcs = $api->arcs_all(%params);

Fetches all pages and returns complete ArrayRef of all ARCs.

quests

my $quests = $api->quests(%params);

Returns ArrayRef of WWW::MetaForge::ArcRaiders::Result::Quest from first page. Supports type parameter.

quests_paginated

my $result = $api->quests_paginated(%params);

Returns HashRef with data and pagination info.

quests_all

my $quests = $api->quests_all(%params);

Fetches all pages and returns complete ArrayRef of all quests.

traders

my $traders = $api->traders(%params);

Returns ArrayRef of WWW::MetaForge::ArcRaiders::Result::Trader.

event_timers

my $events = $api->event_timers(%params);

Returns ArrayRef of WWW::MetaForge::ArcRaiders::Result::EventTimer. Always fetches fresh data (bypasses cache) since event timers are time-sensitive.

event_timers_cached

my $events = $api->event_timers_cached(%params);

Like event_timers but uses cache. Only use when you don't need real-time event status.

event_timers_hourly

my $events = $api->event_timers_hourly;

Like event_timers_cached but invalidates the cache at the start of each hour (when minute becomes 0). Useful for scheduled data that updates hourly.

map_data

my $markers = $api->map_data(%params);

Returns ArrayRef of WWW::MetaForge::ArcRaiders::Result::MapMarker. Supports map parameter.

items_raw

arcs_raw

quests_raw

traders_raw

event_timers_raw

map_data_raw

Same as the corresponding methods but return raw HashRef/ArrayRef instead of result objects.

clear_cache

$api->clear_cache('items');  # Clear specific endpoint
$api->clear_cache;           # Clear all

Clear cached responses.

find_item_by_name

my $item = $api->find_item_by_name('Ferro I');

Find an item by exact name (case-insensitive). Loads all items on first call for fast subsequent lookups.

find_item_by_id

my $item = $api->find_item_by_id('ferro-i');

Find an item by its ID.

calculate_requirements

my $result = $api->calculate_requirements(
  items => [
    { item => 'Ferro II', count => 2 },
    { item => 'Advanced Circuit', count => 1 },
  ]
);

for my $req (@{$result->{requirements}}) {
  say $req->{item}->name . " x" . $req->{count};
}

Calculate the direct crafting materials needed to build the given items. Returns a hashref with:

requirements

ArrayRef of { item => $item_obj, count => N }

missing

ArrayRef of items that couldn't be resolved (not found, not craftable, etc.)

calculate_base_requirements

my $result = $api->calculate_base_requirements(
  items     => [{ item => 'Ferro III', count => 1 }],
  max_depth => 10,  # optional, default 20
);

Like calculate_requirements but recursively resolves all crafting chains down to base materials (items with no crafting requirements). Includes cycle detection and depth limiting.

clear_items_cache

$api->clear_items_cache;

Clear the internal item lookup cache. Call this if item data may have changed and you need fresh data for find_item_* and calculate_* methods.

ATTRIBUTION

This module uses the MetaForge ARC Raiders API. Please respect their terms:

Terms of Usage

This API contains data maintained by our team and community
contributors. If you use this API in a public project, you must
include attribution and a link to metaforge.app/arc-raiders so
others know where the data comes from.

Commercial/Paid Projects: If you plan to use this API in a paid
app, subscription service, or any product monetized in any way,
please contact us first via Discord.

For (limited) support, visit our Discord.

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-www-metaforge/issues.

IRC

You can reach Getty on irc.perl.org for questions and support.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.