URL Argument Docs

URL Arguments

It's possible to link to the web version of ArcViewer with a set map, difficulty, and start time using URL arguments. This can be used for sharing maps or implementing preview links in map repositories, Discord bots, etc.

To add arguments to your link, add a ? to the end of the URL (https://allpoland.github.io/ArcViewer/), followed by an argument argument=value.

Additional arguments must be separated by an &. i.e. https://allpoland.github.io/ArcViewer/?id=ff9&t=26

The available arguments are as follows:

• url: a direct link to a .zip file containing a Beat Saber map. If this argument is present, the map will immediately start downloading when the app loads. If the url is invalid - a nonexistent link, not actually a Beat Saber map, etc. - loading will fail and the user will be routed to the normal map selection screen.

• id: a valid BeatSaver id matching a published map. If this argument is present, it acts exactly like url, except will automatically fetch the map download from BeatSaver.

  • NOTE: url and id cannot be used together. If both are present, id will take precedence.

• t: the time, in seconds, that the preview should start. If either url or id are present, the previewer will automatically set the player's time to t after loading. If t is less than 0, the player will start at 0 seconds. If t is greater than the song's length, the player will start at the end of the song.

• mode: the difficulty characteristic (game mode) to load by default. If either url or id are present, the specified characteristic will be set when the map loads. If the characteristic doesn't exist, the map's default characteristic will be loaded. If difficulty is present, the specified difficulty will also be set, otherwise the highest difficulty in the characteristic is set.

  • Valid values for mode are: Standard, OneSaber, NoArrows, ThreeSixty, Ninety, Legacy, Lightshow, Lawless, Unknown (case insensitive)

• difficulty: the difficulty level to load by default. If either url or id are present, the specified difficulty will be set when the map loads. If mode is not present, the map's default characteristic will be searched for matching difficulties. Otherwise, the specified characteristic will be searched. If the difficulty doesn't exist in the characteristic, the default (highest) difficulty will be loaded instead.

  • Valid values for difficulty are: Easy, Normal, Hard, Expert, ExpertPlus (case insensitive)

• noProxy: if url is present and this is set to true, the download will not be routed through the CORS proxy. Add noProxy=true if the download source has CORS headers or is being hosted locally.

• replayURL: a direct link to a .bsor file containing replay data. If this is present, the replay will be downloaded and BeatSaver is automatically searched for a map matching the replay. However, if either id or url are present, the specified map will be loaded instead.

• scoreID: a valid BeatLeader score ID, who's replay will automatically be fetched and loaded. Acts the same as replayURL.

  • NOTE: mode and difficulty do not work when loading a replay, since the difficulty will be automatically selected based on the replay metadata.

So, a shareable ArcViewer link that directs to a preview of Knock2 - dashstar* (Mapped by Phøenix & Timeweaver), One Saber, Expert, starting at 1:27, would be:

https://allpoland.github.io/ArcViewer/?id=2f187&t=87&mode=OneSaber&difficulty=Expert

Command Line Arguments

Although pasting a shareable link into the map input on desktop loads the map with arguments, this doesn't allow for a map to instantly load when starting the app. As of ArcViewer 0.3.5, however, the desktop version supports this functionality through command line arguments.

The format for command line arguments is the same as URL arguments, except they're separated with spaces instead of &. Arguments can be added in the ArcViewer executable properties (varies by operating system), but are most useful when running ArcViewer through the command line. When adding arguments to a command line call, add the first argument after the executable call, separated by a space. Further arguments get separated by another space.

I.E. a command line call with arguments on windows would be: Path\To\ArcViewer.exe argument=value secondArgument=value

Command line arguments support all of the URL arguments and function identically, with the exception of noProxy, which does nothing because the desktop version never uses a CORS proxy anyway.

Additionally, the path argument can be used to specify a directory to load a map from. This is unique to the desktop version, and must be a valid path to a directory containing a valid beatmap, a .zip containing a valid beatmap, or one of the .dat files in a beatmap directory.

• This causes the map to immediately begin loading when ArcViewer starts, and t, mode, and difficulty can all be used as normal.
• Both the id and url arguments take precedence over path if they are present.
• NOTE: When using the path argument, you should surround the entire argument with quotation marks " in order to treat the path as a single argument,
  I.E. Path\To\ArcViewer.exe "path=Path\To\Map\File\With Space\Map.zip"
  Otherwise, if the path contains spaces, it will be treated as multiple arguments and will break.

Surrounding other arguments with quotes will also cause whitespace to be treated as a single argument, although adding spaces to anything other than the value of the path argument will not work.