GodotNWS is a GDScript plugin for Godot 4.1+ that connects your game directly to the U.S. National Weather Service (NWS) API. With a few function calls you can pull live weather forecasts, active alerts, radar imagery, and current station observations into any scene — all without registering for an API key. Whether you’re building a simulation, adding dynamic weather events driven by real-world conditions, or just want to show players the actual forecast for their region, GodotNWS handles the HTTP requests and data parsing so you don’t have to.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/OdintheDoggo/GodotNWS/llms.txt
Use this file to discover all available pages before exploring further.
Key Capabilities
Daily Forecast
Fetch a multi-day forecast broken into named periods (e.g., “Monday Night”), each with temperature, wind, precipitation chance, and a detailed description.
Hourly Forecast
Retrieve hour-by-hour conditions including dewpoint, relative humidity, wind speed and direction, and short forecast text.
Current Observations
Get the latest readings from the nearest observation station: temperature, wind, pressure, visibility, heat index, wind chill, cloud layers, and more.
Active Weather Alerts
Receive active NWS alerts for the configured location — tornado warnings, flood watches, winter storm advisories — with full severity, urgency, and instruction text.
Radar GIFs
Download the animated base reflectivity or base velocity radar loop for the nearest radar station as a raw GIF buffer.
Graphicast Images
Fetch graphicast forecast images (indexed 1–n) produced by the local NWS forecast office, returned as
ImageTexture objects ready to display.Weather Stories
Pull illustrated weather stories from the local forecast office, including title, description, priority, and a downloaded PNG image.
Radio Broadcast
Retrieve the text of the current NWS radio broadcast for the configured coordinates, parsed into individual forecast paragraphs.
Drought Monitor
Download the current U.S. Drought Monitor PNG map as an
ImageTexture.US Warning Map
Fetch the national NWS active-warnings overview map as an
ImageTexture.Forecast Charts
Retrieve Weather Prediction Center forecast charts (indices 1–3) as GIF buffers for display or processing.
Public API
GodotNWS exposes thirteen public methods on theNws singleton. The two setup methods must be called first — all fetch methods assert that a location has been configured before making any network requests.
| Method | Description |
|---|---|
setup(latitude, longitude) | Configure location from explicit coordinates. |
setup_ip() | Auto-detect location from the user’s IP address. |
fetch_forecast(fetch_images) | Fetch the multi-period daily forecast. |
fetch_hourly_forecast(fetch_images) | Fetch the hour-by-hour forecast. |
fetch_current_observations(fetch_icon) | Fetch the latest station observation readings. |
fetch_alerts() | Fetch active NWS alerts for the area. |
fetch_radar_gif(velocity) | Download the radar loop GIF (base reflectivity or velocity). |
fetch_forecast_chart(index) | Download a WPC forecast chart GIF (index 1–3). |
fetch_graphicast(index) | Fetch an indexed graphicast image from the local office. |
fetch_weather_stories() | Fetch illustrated weather stories from the forecast office. |
fetch_radio_broadcast() | Fetch the NWS radio broadcast text for the location. |
fetch_us_warning_map() | Download the national active-warnings map. |
fetch_drought_monitor() | Download the current U.S. Drought Monitor map. |
| Signal | Payload |
|---|---|
location_setup_complete | (no arguments) |
forecast_fetched | periods: Array[ForecastPeriod] |
hourly_forecast_fetched | periods: Array[HourlyForecastPeriod] |
observations_fetched | observations: ObservationPacket |
alerts_fetched | alerts: Array[Alert] |
radar_fetched | image_buffer |
chart_fetched | image_buffer |
graphicast_fetched | image, index, last_modified |
weather_stories_fetched | stories: Array[WeatherStory] |
radio_broadcast_fetched | Paragraphs: Array[String] |
drought_fetched | image |
us_map_fetched | image |
How the Plugin Works
GodotNWS registers a global autoload singleton calledNws the moment you enable the plugin in your project settings. Because it is an autoload, the Nws node is available in every scene and every script without any extra preload or get_node calls.
The API is entirely signal-driven and asynchronous. Every fetch method spawns an internal HTTPRequest node, makes the network call on a background thread, parses the response, and then emits a typed signal carrying the result. Your code connects to those signals and reacts when the data arrives — there is no blocking, no polling loop, and no coroutine management required.
The typical flow looks like this:
- Connect to
Nws.location_setup_complete. - Call
Nws.setup(latitude, longitude)— orNws.setup_ip()to auto-detect from the user’s IP address. - Inside the signal handler, connect to the relevant result signal (e.g.,
Nws.forecast_fetched) and call the corresponding fetch method (e.g.,Nws.fetch_forecast(false)). - Handle the result in your signal callback.
Nws.SetUp property is false until setup completes. All fetch methods call an internal Check() guard that will raise an assertion error if you attempt a fetch before a location has been configured.
Important disclaimers before you ship:
- GodotNWS is not affiliated with or endorsed by the National Weather Service or any U.S. government agency.
- Some fields on forecasts, alerts, and observations may be omitted by the NWS API itself. This is expected behavior and is not a plugin bug.
- The NWS API only covers locations within the United States. Coordinates outside US territory will fail during the setup phase.